| 1 | --- |
| 2 | layout: reference |
| 3 | --- |
| 4 | |
| 5 | <div class="box"> |
| 6 | <h2> |
| 7 | <span class="docs"> |
| 8 | <a target="new" href="http://git-scm.com/book/en/Git-Basics-Working-with-Remotes">book</a> |
| 9 | </span> |
| 10 | Sharing and Updating Projects |
| 11 | </h2> |
| 12 | <div class="block"> |
| 13 | <p> |
| 14 | Git doesn't have a central server like Subversion. All of the commands |
| 15 | so far have been done locally, just updating a local database. |
| 16 | To collaborate with other developers in Git, you have to put all that |
| 17 | data on a server that the other developers have access to. The way Git |
| 18 | does this is to synchronize your data with another repository. There |
| 19 | is no real difference between a server and a client - a Git repository |
| 20 | is a Git repository and you can synchronize between any two easily. |
| 21 | </p> |
| 22 | |
| 23 | <p>Once you have a Git repository, either one that you set up on your |
| 24 | own server, or one hosted someplace like GitHub, you can tell Git to |
| 25 | either push any data that you have that is not in the remote repository |
| 26 | up, or you can ask Git to fetch differences down from the other repo. |
| 27 | </p> |
| 28 | |
| 29 | <p>You can do this any time you are online, it does not have to correspond |
| 30 | with a <code>commit</code> or anything else. Generally you will do a |
| 31 | number of commits locally, then fetch data from the online shared repository |
| 32 | you cloned the project from to get up to date, merge any new work into the |
| 33 | stuff you did, then push your changes back up.</p> |
| 34 | |
| 35 | <p class="nutshell"> |
| 36 | <b>In a nutshell</b> you can update your project with <code>git fetch</code> |
| 37 | and share your changes with <code>git push</code>. You can manage your |
| 38 | remote repositories with <code>git remote</code>. |
| 39 | </p> |
| 40 | </div> |
| 41 | </div> |
| 42 | |
| 43 | <div class="box"> |
| 44 | <h2> |
| 45 | <span class="docs"> |
| 46 | <a target="new" href="http://git-scm.com/docs/git-remote">docs</a> |
| 47 | <a target="new" href="http://git-scm.com/book/en/Git-Basics-Working-with-Remotes#Showing-Your-Remotes">book</a> |
| 48 | </span> |
| 49 | <a name="remote">git remote</a> |
| 50 | <span class="desc">list, add and delete remote repository aliases</span> |
| 51 | </h2> |
| 52 | |
| 53 | <div class="block"> |
| 54 | |
| 55 | <p>Unlike centralized version control systems that have a client that is |
| 56 | very different from a server, Git repositories are all basically equal and |
| 57 | you simply synchronize between them. This makes it easy to have more than |
| 58 | one remote repository - you can have some that you have read-only access to |
| 59 | and others that you can write to as well.</p> |
| 60 | |
| 61 | <p>So that you don't have to use the full URL of a remote repository every |
| 62 | time you want to synchronize with it, Git stores an alias or nickname for |
| 63 | each remote repository URL you are interested in. You use the |
| 64 | <code>git remote</code> command to manage this list of remote repos that |
| 65 | you care about.</p> |
| 66 | |
| 67 | <h4 id="remote-list"> |
| 68 | git remote |
| 69 | <small>list your remote aliases</small> |
| 70 | </h4> |
| 71 | |
| 72 | <p>Without any arguments, Git will simply show you the remote repository |
| 73 | aliases that it has stored. By default, if you cloned the project (as |
| 74 | opposed to creating a new one locally), Git will automatically add the |
| 75 | URL of the repository that you cloned from under the name 'origin'. If |
| 76 | you run the command with the <code>-v</code> option, you can see the |
| 77 | actual URL for each alias.</p> |
| 78 | |
| 79 | <pre> |
| 80 | <b>$ git remote</b> |
| 81 | origin |
| 82 | <b>$ git remote -v</b> |
| 83 | origin git@github.com:github/git-reference.git (fetch) |
| 84 | origin git@github.com:github/git-reference.git (push) |
| 85 | </pre> |
| 86 | |
| 87 | <p>You see the URL there twice because Git allows you to have different |
| 88 | push and fetch URLs for each remote in case you want to use different |
| 89 | protocols for reads and writes.</p> |
| 90 | |
| 91 | <h4 id="remote-add"> |
| 92 | git remote add |
| 93 | <small>add a new remote repository of your project</small> |
| 94 | </h4> |
| 95 | |
| 96 | <p>If you want to share a locally created repository, or you want to take |
| 97 | contributions from someone else's repository - if you want to interact in |
| 98 | any way with a new repository, it's generally easiest to add it as a remote. |
| 99 | You do that by running <code>git remote add [alias] [url]</code>. That |
| 100 | adds <code>[url]</code> under a local remote named <code>[alias]</code>.</p> |
| 101 | |
| 102 | <p>For example, if we want to share our Hello World program with the world, |
| 103 | we can create a new repository on a server (Using GitHub as an example), |
| 104 | which should give you a URL, in this case "git@github.com:schacon/hw.git". |
| 105 | To add that to our project so we can push to it and fetch updates from it |
| 106 | we would do this:</p> |
| 107 | |
| 108 | <pre> |
| 109 | <b>$ git remote</b> |
| 110 | <b>$ git remote add github git@github.com:schacon/hw.git</b> |
| 111 | <b>$ git remote -v</b> |
| 112 | github git@github.com:schacon/hw.git (fetch) |
| 113 | github git@github.com:schacon/hw.git (push) |
| 114 | </pre> |
| 115 | |
| 116 | <p>Like the branch naming, remote alias names are arbitrary - just as 'master' |
| 117 | has no special meaning but is widely used because <code>git init</code> |
| 118 | sets it up by default, 'origin' is often used as a remote name because |
| 119 | <code>git clone</code> sets it up by default as the cloned-from URL. In |
| 120 | this case we'll name the remote 'github', but you could name it just |
| 121 | about anything. |
| 122 | </p> |
| 123 | |
| 124 | <h4 id="remote-remove"> |
| 125 | git remote rm |
| 126 | <small>removing an existing remote alias</small> |
| 127 | </h4> |
| 128 | |
| 129 | <p>Git addeth and Git taketh away. If you need to remove a remote - you are |
| 130 | not using it anymore, the project is gone, etc - you can remove it with |
| 131 | <code>git remote rm [alias]</code>.</p> |
| 132 | |
| 133 | <pre> |
| 134 | <b>$ git remote -v</b> |
| 135 | github git@github.com:schacon/hw.git (fetch) |
| 136 | github git@github.com:schacon/hw.git (push) |
| 137 | <b>$ git remote add origin git://github.com/pjhyett/hw.git</b> |
| 138 | <b>$ git remote -v</b> |
| 139 | github git@github.com:schacon/hw.git (fetch) |
| 140 | github git@github.com:schacon/hw.git (push) |
| 141 | origin git://github.com/pjhyett/hw.git (fetch) |
| 142 | origin git://github.com/pjhyett/hw.git (push) |
| 143 | <b>$ git remote rm origin</b> |
| 144 | <b>$ git remote -v</b> |
| 145 | github git@github.com:schacon/hw.git (fetch) |
| 146 | github git@github.com:schacon/hw.git (push) |
| 147 | </pre> |
| 148 | |
| 149 | <h4 id="remote-rename"> |
| 150 | git remote rename [old-alias] [new-alias] |
| 151 | <small>rename remote aliases</small> |
| 152 | </h4> |
| 153 | |
| 154 | <p>If you want to rename remote aliases without having to delete them and add them again |
| 155 | you can do that by running <code>git remote rename [old-alias] [new-alias]</code>. This will |
| 156 | allow you to modify the current name of the remote.</p> |
| 157 | |
| 158 | <pre> |
| 159 | <b>$ git remote add github git@github.com:schacon/hw.git</b> |
| 160 | <b>$ git remote -v</b> |
| 161 | github git@github.com:schacon/hw.git (fetch) |
| 162 | github git@github.com:schacon/hw.git (push) |
| 163 | <b>$ git remote rename github origin</b> |
| 164 | <b>$ git remote -v</b> |
| 165 | origin git@github.com:schacon/hw.git (fetch) |
| 166 | origin git@github.com:schacon/hw.git (push) |
| 167 | </pre> |
| 168 | |
| 169 | <p class="nutshell"> |
| 170 | <b>In a nutshell</b> with <code>git remote</code> you can list our |
| 171 | remote repositories and whatever URL |
| 172 | that repository is using. You can use <code>git remote add</code> to |
| 173 | add new remotes, <code>git remote rm</code> to delete existing ones or <code>git remote rename [old-alias] [new-alias]</code> to rename them. |
| 174 | </p> |
| 175 | |
| 176 | <h4 id="remote-update"> |
| 177 | git remote set-url |
| 178 | <small>update an existing remote URL</small> |
| 179 | </h4> |
| 180 | |
| 181 | <p>Should you ever need to update a remote's URL, you can do so with |
| 182 | the <code>git remote set-url</code> command. |
| 183 | </p> |
| 184 | |
| 185 | <pre> |
| 186 | <b>$ git remote -v</b> |
| 187 | github git@github.com:schacon/hw.git (fetch) |
| 188 | github git@github.com:schacon/hw.git (push) |
| 189 | origin git://github.com/pjhyett/hw.git (fetch) |
| 190 | origin git://github.com/pjhyett/hw.git (push) |
| 191 | <b>$ git remote set-url origin git://github.com/github/git-reference.git</b> |
| 192 | <b>$ git remote -v</b> |
| 193 | github git@github.com:schacon/hw.git (fetch) |
| 194 | github git@github.com:schacon/hw.git (push) |
| 195 | origin git://github.com/github/git-reference.git (fetch) |
| 196 | origin git://github.com/github/git-reference.git (push) |
| 197 | </pre> |
| 198 | |
| 199 | <p>In addition to this, you can set a different push URL when you |
| 200 | include the <code>--push</code> flag. This allows you to fetch from |
| 201 | one repo while pushing to another and yet both use the same remote alias. |
| 202 | </p> |
| 203 | |
| 204 | <pre> |
| 205 | <b>$ git remote -v</b> |
| 206 | github git@github.com:schacon/hw.git (fetch) |
| 207 | github git@github.com:schacon/hw.git (push) |
| 208 | origin git://github.com/github/git-reference.git (fetch) |
| 209 | origin git://github.com/github/git-reference.git (push) |
| 210 | <b>$ git remote set-url --push origin git://github.com/pjhyett/hw.git</b> |
| 211 | <b>$ git remote -v</b> |
| 212 | github git@github.com:schacon/hw.git (fetch) |
| 213 | github git@github.com:schacon/hw.git (push) |
| 214 | origin git://github.com/github/git-reference.git (fetch) |
| 215 | origin git://github.com/pjhyett/hw.git (push) |
| 216 | </pre> |
| 217 | |
| 218 | <p>Internally, the <code>git remote set-url</code> command calls |
| 219 | <code>git config remote</code>, but has the added benefit of reporting |
| 220 | back any errors. <code>git config remote</code> on the other hand, will |
| 221 | silently fail if you mistype an argument or option and not actually set |
| 222 | anything. |
| 223 | </p> |
| 224 | |
| 225 | <p>For example, we'll update the <code>github</code> remote but |
| 226 | instead reference it as <code>guhflub</code> in both invocations. |
| 227 | </p> |
| 228 | |
| 229 | <pre> |
| 230 | <b>$ git remote -v</b> |
| 231 | github git@github.com:schacon/hw.git (fetch) |
| 232 | github git@github.com:schacon/hw.git (push) |
| 233 | origin git://github.com/github/git-reference.git (fetch) |
| 234 | origin git://github.com/github/git-reference.git (push) |
| 235 | <b>$ git config remote.guhflub git://github.com/mojombo/hw.git</b> |
| 236 | <b>$ git remote -v</b> |
| 237 | github git@github.com:schacon/hw.git (fetch) |
| 238 | github git@github.com:schacon/hw.git (push) |
| 239 | origin git://github.com/github/git-reference.git (fetch) |
| 240 | origin git://github.com/github/git-reference.git (push) |
| 241 | <b>$ git remote set-url guhflub git://github.com/mojombo/hw.git</b> |
| 242 | fatal: No such remote 'guhflub' |
| 243 | </pre> |
| 244 | |
| 245 | <p class="nutshell"> |
| 246 | <b>In a nutshell</b>, you can update the locations of your remotes |
| 247 | with <code>git remote set-url</code>. You can also set different push |
| 248 | and fetch URLs under the same remote alias. |
| 249 | </p> |
| 250 | |
| 251 | </div> |
| 252 | </div> |
| 253 | |
| 254 | <div class="box"> |
| 255 | <h2> |
| 256 | <span class="docs"> |
| 257 | <a target="new" href="http://git-scm.com/docs/git-fetch">docs</a> |
| 258 | <a target="new" href="http://git-scm.com/book/en/Git-Basics-Working-with-Remotes#Fetching-and-Pulling-from-Your-Remotes">book</a> |
| 259 | </span> |
| 260 | <a name="fetch">git fetch</a> |
| 261 | <span class="desc">download new branches and data from a remote repository</span> |
| 262 | </h2> |
| 263 | |
| 264 | <br/> |
| 265 | |
| 266 | <h2> |
| 267 | <span class="docs"> |
| 268 | <a target="new" href="http://git-scm.com/docs/git-pull">docs</a> |
| 269 | <a target="new" href="http://git-scm.com/book/en/Git-Basics-Working-with-Remotes#Fetching-and-Pulling-from-Your-Remotes">book</a> |
| 270 | </span> |
| 271 | <a name="pull">git pull</a> |
| 272 | <span class="desc">fetch from a remote repo and try to merge into the current branch</span> |
| 273 | </h2> |
| 274 | |
| 275 | <div class="block"> |
| 276 | |
| 277 | <p>Git has two commands to update itself from a remote repository. |
| 278 | <code>git fetch</code> will synchronize you with another repo, pulling down any data |
| 279 | that you do not have locally and giving you bookmarks to where each branch on |
| 280 | that remote was when you synchronized. These are called "remote branches" and are |
| 281 | identical to local branches except that Git will not allow you to check them out - |
| 282 | however, you can merge from them, diff them to other branches, run history logs on |
| 283 | them, etc. You do all of that stuff locally after you synchronize. |
| 284 | </p> |
| 285 | |
| 286 | <p>The second command that will fetch down new data from a remote server is |
| 287 | <code>git pull</code>. This command will basically run a <code>git fetch</code> |
| 288 | immediately followed by a <code>git merge</code> of the branch on that remote |
| 289 | that is tracked by whatever branch you are currently in. Running the |
| 290 | <code>fetch</code> and <code>merge</code> commands separately involves less magic |
| 291 | and less problems, but if you like the idea of <code>pull</code>, you can |
| 292 | read about it in more detail in the |
| 293 | <a target="new" href="http://git-scm.com/docs/git-pull">official docs</a>. |
| 294 | </p> |
| 295 | |
| 296 | <p>Assuming you have a remote all set up and you want to pull in updates, you |
| 297 | would first run <code>git fetch [alias]</code> to tell Git to fetch down all the |
| 298 | data it has that you do not, then you would run <code>git merge [alias]/[branch]</code> |
| 299 | to merge into your current branch anything new you see on the server |
| 300 | (like if someone else has pushed in the meantime). So, if you were working on a |
| 301 | Hello World project with several other people and wanted to bring in any changes |
| 302 | that had been pushed since we last connected, we would do something like this:</p> |
| 303 | |
| 304 | <pre> |
| 305 | <b>$ git fetch github</b> |
| 306 | remote: Counting objects: 4006, done. |
| 307 | remote: Compressing objects: 100% (1322/1322), done. |
| 308 | remote: Total 2783 (delta 1526), reused 2587 (delta 1387) |
| 309 | Receiving objects: 100% (2783/2783), 1.23 MiB | 10 KiB/s, done. |
| 310 | Resolving deltas: 100% (1526/1526), completed with 387 local objects. |
| 311 | From github.com:schacon/hw |
| 312 | 8e29b09..c7c5a10 master -> github/master |
| 313 | 0709fdc..d4ccf73 c-langs -> github/c-langs |
| 314 | 6684f82..ae06d2b java -> github/java |
| 315 | * [new branch] ada -> github/ada |
| 316 | * [new branch] lisp -> github/lisp |
| 317 | </pre> |
| 318 | |
| 319 | <p>Here we can see that since we last synchronized with this remote, five branches |
| 320 | have been added or updated. The 'ada' and 'lisp' branches are new, where the |
| 321 | 'master', 'c-langs' and 'java' branches have been updated. In our example case, |
| 322 | other developers are pushing proposed updates to remote branches for review before |
| 323 | they're merged into 'master'. |
| 324 | </p> |
| 325 | |
| 326 | <p>You can see the mapping that Git makes. The 'master' branch on the remote |
| 327 | repository becomes a branch named 'github/master' locally. That way you can |
| 328 | merge the 'master' branch on that remote into the local 'master' branch by running |
| 329 | <code>git merge github/master</code>. Or, you can see what new commits are on that |
| 330 | branch by running <code>git log github/master ^master</code>. If your remote |
| 331 | is named 'origin' it would be <code>origin/master</code> instead. Almost any |
| 332 | command you would run using local branches you can use remote branches with too. |
| 333 | </p> |
| 334 | |
| 335 | <p>If you have more than one remote repository, you can either fetch from specific |
| 336 | ones by running <code>git fetch [alias]</code> or you can tell Git to synchronize |
| 337 | with all of your remotes by running <code>git fetch --all</code>. |
| 338 | </p> |
| 339 | |
| 340 | <p class="nutshell"> |
| 341 | <b>In a nutshell</b> you run <code>git fetch [alias]</code> to synchronize your |
| 342 | repository with a remote repository, fetching all the data it has that you do |
| 343 | not into branch references locally for merging and whatnot. |
| 344 | </p> |
| 345 | |
| 346 | </div> |
| 347 | |
| 348 | </div> |
| 349 | |
| 350 | <div class="box"> |
| 351 | <h2> |
| 352 | <span class="docs"> |
| 353 | <a target="new" href="http://git-scm.com/docs/git-push">docs</a> |
| 354 | <a target="new" href="http://git-scm.com/book/en/Git-Basics-Working-with-Remotes#Pushing-to-Your-Remotes">book</a> |
| 355 | </span> |
| 356 | <a name="push">git push</a> |
| 357 | <span class="desc">push your new branches and data to a remote repository</span> |
| 358 | </h2> |
| 359 | |
| 360 | <div class="block"> |
| 361 | <p>To share the cool commits you've done with others, you need to push your |
| 362 | changes to the remote repository. To do this, you run |
| 363 | <code>git push [alias] [branch]</code> which will attempt to make your [branch] |
| 364 | the new [branch] on the [alias] remote. Let's try it by initially pushing |
| 365 | our 'master' branch to the new 'github' remote we created earlier.</p> |
| 366 | |
| 367 | <pre> |
| 368 | <b>$ git push github master</b> |
| 369 | Counting objects: 25, done. |
| 370 | Delta compression using up to 2 threads. |
| 371 | Compressing objects: 100% (25/25), done. |
| 372 | Writing objects: 100% (25/25), 2.43 KiB, done. |
| 373 | Total 25 (delta 4), reused 0 (delta 0) |
| 374 | To git@github.com:schacon/hw.git |
| 375 | * [new branch] master -> master |
| 376 | </pre> |
| 377 | |
| 378 | <p>Pretty easy. Now if someone clones that repository they will get exactly |
| 379 | what we have committed and all of its history.</p> |
| 380 | |
| 381 | <p>What if you have a topic branch like the 'erlang' branch created earlier |
| 382 | and want to share just that? You can just push that branch instead.</p> |
| 383 | |
| 384 | <pre> |
| 385 | <b>$ git push github erlang</b> |
| 386 | Counting objects: 7, done. |
| 387 | Delta compression using up to 2 threads. |
| 388 | Compressing objects: 100% (6/6), done. |
| 389 | Writing objects: 100% (6/6), 652 bytes, done. |
| 390 | Total 6 (delta 1), reused 0 (delta 0) |
| 391 | To git@github.com:schacon/hw.git |
| 392 | * [new branch] erlang -> erlang |
| 393 | </pre> |
| 394 | |
| 395 | <p>Now when people clone or fetch from that repository, they'll get an 'erlang' |
| 396 | branch they can look at and merge from. You can push any branch to any |
| 397 | remote repository that you have write access to in this way. If your branch |
| 398 | is already on the server, it will try to update it, if it is not, Git will |
| 399 | add it.</p> |
| 400 | |
| 401 | <p>The last major issue you run into with pushing to remote branches is the |
| 402 | case of someone pushing in the meantime. If you and another developer clone |
| 403 | at the same time, you both do commits, then she pushes and then you try to |
| 404 | push, Git will by default not allow you to overwrite her changes. Instead, |
| 405 | it basically runs <code>git log</code> on the branch you're trying to push and |
| 406 | makes sure it can see the current tip of the server's branch in your push's |
| 407 | history. If it can't see what is on the server in your history, it concludes |
| 408 | that you are out of date and will reject your push. You will rightly have to |
| 409 | fetch, merge then push again - which makes sure you take her changes into |
| 410 | account.</p> |
| 411 | |
| 412 | <p>This is what happens when you try to push a branch to a remote branch |
| 413 | that has been updated in the meantime:</p> |
| 414 | |
| 415 | <pre> |
| 416 | <b>$ git push github master</b> |
| 417 | To git@github.com:schacon/hw.git |
| 418 | ! [rejected] master -> master (non-fast-forward) |
| 419 | error: failed to push some refs to 'git@github.com:schacon/hw.git' |
| 420 | To prevent you from losing history, non-fast-forward updates were rejected |
| 421 | Merge the remote changes before pushing again. See the 'Note about |
| 422 | fast-forwards' section of 'git push --help' for details. |
| 423 | </pre> |
| 424 | |
| 425 | <p>You can fix this by running <code>git fetch github; git merge github/master</code> |
| 426 | and then pushing again. |
| 427 | </p> |
| 428 | |
| 429 | <p class="nutshell"> |
| 430 | <b>In a nutshell</b> you run <code>git push [alias] [branch]</code> to update a |
| 431 | remote repository with the changes you've made locally. It will take what your |
| 432 | [branch] looks like and push it to be [branch] on the remote, if possible. If |
| 433 | someone else has pushed since you last fetched and merged, the Git server will |
| 434 | deny your push until you are up to date. |
| 435 | </p> |
| 436 | |
| 437 | </div> |
| 438 | </div> |
| 439 | |
| 440 | <p><a class="page-button next-page" href="/inspect">On to Inspection and Comparison »</a></p> |