X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=Documentation%2Fgittutorial.txt;h=7892244ef19d507379489de0cc81ad18b936c6af;hb=ed56049058284d7df2ede1ce5f494a2a9a109479;hp=e71b561172030bbd4c524891f6525fadd160b54b;hpb=69b060c84e25c2cb90b16bd0ba602bc14102e1ae;p=git.git diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt index e71b56117..7892244ef 100644 --- a/Documentation/gittutorial.txt +++ b/Documentation/gittutorial.txt @@ -26,6 +26,15 @@ First, note that you can get documentation for a command such as $ man git-log ------------------------------------------------ +or: + +------------------------------------------------ +$ git help log +------------------------------------------------ + +With the latter, you can use the manual viewer of your choice; see +linkgit:git-help[1] for more information. + It is a good idea to introduce yourself to git with your name and public email address before doing any operation. The easiest way to do so is: @@ -274,7 +283,7 @@ same machine, wants to contribute. Bob begins with: ------------------------------------------------ -$ git clone /home/alice/project myrepo +bob$ git clone /home/alice/project myrepo ------------------------------------------------ This creates a new directory "myrepo" containing a clone of Alice's @@ -285,7 +294,7 @@ Bob then makes some changes and commits them: ------------------------------------------------ (edit files) -$ git commit -a +bob$ git commit -a (repeat as necessary) ------------------------------------------------ @@ -293,8 +302,8 @@ When he's ready, he tells Alice to pull changes from the repository at /home/bob/myrepo. She does this with: ------------------------------------------------ -$ cd /home/alice/project -$ git pull /home/bob/myrepo master +alice$ cd /home/alice/project +alice$ git pull /home/bob/myrepo master ------------------------------------------------ This merges the changes from Bob's "master" branch into Alice's @@ -306,21 +315,74 @@ is the default.) The "pull" command thus performs two operations: it fetches changes from a remote branch, then merges them into the current branch. +Note that in general, Alice would want her local changes committed before +initiating this "pull". If Bob's work conflicts with what Alice did since +their histories forked, Alice will use her working tree and the index to +resolve conflicts, and existing local changes will interfere with the +conflict resolution process (git will still perform the fetch but will +refuse to merge --- Alice will have to get rid of her local changes in +some way and pull again when this happens). + +Alice can peek at what Bob did without merging first, using the "fetch" +command; this allows Alice to inspect what Bob did, using a special +symbol "FETCH_HEAD", in order to determine if he has anything worth +pulling, like this: + +------------------------------------------------ +alice$ git fetch /home/bob/myrepo master +alice$ git log -p HEAD..FETCH_HEAD +------------------------------------------------ + +This operation is safe even if Alice has uncommitted local changes. +The range notation HEAD..FETCH_HEAD" means "show everything that is reachable +from the FETCH_HEAD but exclude anything that is reachable from HEAD. +Alice already knows everything that leads to her current state (HEAD), +and reviewing what Bob has in his state (FETCH_HEAD) that she has not +seen with this command + +If Alice wants to visualize what Bob did since their histories forked +she can issue the following command: + +------------------------------------------------ +$ gitk HEAD..FETCH_HEAD +------------------------------------------------ + +This uses the same two-dot range notation we saw earlier with 'git log'. + +Alice may want to view what both of them did since they forked. +She can use three-dot form instead of the two-dot form: + +------------------------------------------------ +$ gitk HEAD...FETCH_HEAD +------------------------------------------------ + +This means "show everything that is reachable from either one, but +exclude anything that is reachable from both of them". + +Please note that these range notation can be used with both gitk +and "git log". + +After inspecting what Bob did, if there is nothing urgent, Alice may +decide to continue working without pulling from Bob. If Bob's history +does have something Alice would immediately need, Alice may choose to +stash her work-in-progress first, do a "pull", and then finally unstash +her work-in-progress on top of the resulting history. + When you are working in a small closely knit group, it is not unusual to interact with the same repository over and over again. By defining 'remote' repository shorthand, you can make it easier: ------------------------------------------------ -$ git remote add bob /home/bob/myrepo +alice$ git remote add bob /home/bob/myrepo ------------------------------------------------ -With this, Alice can perform the first operation alone using the +With this, Alice can perform the first part of the "pull" operation alone using the 'git-fetch' command without merging them with her own branch, using: ------------------------------------- -$ git fetch bob +alice$ git fetch bob ------------------------------------- Unlike the longhand form, when Alice fetches from Bob using a @@ -329,7 +391,7 @@ fetched is stored in a remote tracking branch, in this case `bob/master`. So after this: ------------------------------------- -$ git log -p master..bob/master +alice$ git log -p master..bob/master ------------------------------------- shows a list of all the changes that Bob made since he branched from @@ -339,14 +401,14 @@ After examining those changes, Alice could merge the changes into her master branch: ------------------------------------- -$ git merge bob/master +alice$ git merge bob/master ------------------------------------- This `merge` can also be done by 'pulling from her own remote tracking branch', like this: ------------------------------------- -$ git pull . remotes/bob/master +alice$ git pull . remotes/bob/master ------------------------------------- Note that git pull always merges into the current branch, @@ -355,7 +417,7 @@ regardless of what else is given on the command line. Later, Bob can update his repo with Alice's latest changes using ------------------------------------- -$ git pull +bob$ git pull ------------------------------------- Note that he doesn't need to give the path to Alice's repository; @@ -364,7 +426,7 @@ repository in the repository configuration, and that location is used for pulls: ------------------------------------- -$ git config --get remote.origin.url +bob$ git config --get remote.origin.url /home/alice/project ------------------------------------- @@ -376,7 +438,7 @@ Git also keeps a pristine copy of Alice's master branch under the name "origin/master": ------------------------------------- -$ git branch -r +bob$ git branch -r origin/master ------------------------------------- @@ -384,7 +446,7 @@ If Bob later decides to work from a different host, he can still perform clones and pulls using the ssh protocol: ------------------------------------- -$ git clone alice.org:/home/alice/project myrepo +bob$ git clone alice.org:/home/alice/project myrepo ------------------------------------- Alternatively, git has a native protocol, or can use rsync or http; @@ -600,6 +662,7 @@ linkgit:gittutorial-2[7], linkgit:gitcvs-migration[7], linkgit:gitcore-tutorial[7], linkgit:gitglossary[7], +linkgit:git-help[1], link:everyday.html[Everyday git], link:user-manual.html[The Git User's Manual]