Documentation: clarify tutorial pull/merge discussion
Attempt to clarify somewhat the difference between pull and merge, and give a little more details on the pull syntax. I'm still not happy with this section: the explanation of the origin branch isn't great, but maybe that should be left alone pending the use-separate-remotes change; and we need to explain how to set up a public repository and push to it. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu> Signed-off-by: Junio C Hamano <junkio@cox.net>
J. Bruce Fields committed
Nov 25, 2006 at 22:45 UTC
93ee7823c0a48b7a51ac0e145b5bcc450c805ea4
1 file changed
+26
-15
Documentation/tutorial.txt
+26
-15
@@ -209,29 +209,28 @@ at /home/bob/myrepo. She does this with:
209
210
------------------------------------------------
211
$ cd /home/alice/project
212
-$ git pull /home/bob/myrepo
212
+$ git pull /home/bob/myrepo master
213
------------------------------------------------
214
215
-This actually pulls changes from the branch in Bob's repository named
216
-"master". Alice could request a different branch by adding the name
217
-of the branch to the end of the git pull command line.
215
+This merges the changes from Bob's "master" branch into Alice's
216
+current branch. If Alice has made her own changes in the meantime,
217
+then she may need to manually fix any conflicts. (Note that the
218
+"master" argument in the above command is actually unnecessary, as it
219
+is the default.)
220
219
-This merges Bob's changes into her repository; "git log" will
220
-now show the new commits. If Alice has made her own changes in the
221
-meantime, then Bob's changes will be merged in, and she will need to
222
-manually fix any conflicts.
221
+The "pull" command thus performs two operations: it fetches changes
222
+from a remote branch, then merges them into the current branch.
223
224
-A more cautious Alice might wish to examine Bob's changes before
225
-pulling them. She can do this by creating a temporary branch just
226
-for the purpose of studying Bob's changes:
224
+You can perform the first operation alone using the "git fetch"
225
+command. For example, Alice could create a temporary branch just to
226
+track Bob's changes, without merging them with her own, using:
227
228
-------------------------------------
229
$ git fetch /home/bob/myrepo master:bob-incoming
230
-------------------------------------
231
232
which fetches the changes from Bob's master branch into a new branch
233
-named bob-incoming. (Unlike git pull, git fetch just fetches a copy
234
-of Bob's line of development without doing any merging). Then
233
+named bob-incoming. Then
234
235
-------------------------------------
236
$ git log -p master..bob-incoming
@@ -240,8 +239,8 @@ $ git log -p master..bob-incoming
239
shows a list of all the changes that Bob made since he branched from
240
Alice's master branch.
241
243
-After examining those changes, and possibly fixing things, Alice can
244
-pull the changes into her master branch:
242
+After examining those changes, and possibly fixing things, Alice
243
+could pull the changes into her master branch:
244
245
-------------------------------------
246
$ git checkout master
@@ -251,6 +250,18 @@ $ git pull . bob-incoming
250
The last command is a pull from the "bob-incoming" branch in Alice's
251
own repository.
252
253
+Alice could also perform both steps at once with:
254
+
255
+-------------------------------------
256
+$ git pull /home/bob/myrepo master:bob-incoming
257
+-------------------------------------
258
+
259
+This is just like the "git pull /home/bob/myrepo master" that we saw
260
+before, except that it also stores the unmerged changes from bob's
261
+master branch in bob-incoming before merging them into Alice's
262
+current branch. Note that git pull always merges into the current
263
+branch, regardless of what else is given on the commandline.
264
+
265
Later, Bob can update his repo with Alice's latest changes using
266
267
-------------------------------------