$ 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:
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
------------------------------------------------
(edit files)
-$ git commit -a
+bob$ git commit -a
(repeat as necessary)
------------------------------------------------
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
current branch. If Alice has made her own changes in the meantime,
-then she may need to manually fix any conflicts. (Note that the
-"master" argument in the above command is actually unnecessary, as it
-is the default.)
+then she may need to manually fix any conflicts.
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
`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
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,
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;
used for pulls:
-------------------------------------
-$ git config --get remote.origin.url
+bob$ git config --get remote.origin.url
/home/alice/project
-------------------------------------
name "origin/master":
-------------------------------------
-$ git branch -r
+bob$ git branch -r
origin/master
-------------------------------------
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;
then merged back together, the order in which 'git-log' presents
those commits is meaningless.
-Most projects with multiple contributors (such as the linux kernel,
-or git itself) have frequent merges, and `gitk` does a better job of
+Most projects with multiple contributors (such as the Linux kernel,
+or git itself) have frequent merges, and 'gitk' does a better job of
visualizing their history. For example,
-------------------------------------
* linkgit:git-format-patch[1], linkgit:git-am[1]: These convert
series of git commits into emailed patches, and vice versa,
- useful for projects such as the linux kernel which rely heavily
+ useful for projects such as the Linux kernel which rely heavily
on emailed patches.
* linkgit:git-bisect[1]: When there is a regression in your
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]