Suppose that Alice has started a new project with a Git repository in
/home/alice/project, and that Bob, who has a home directory on the
same machine, wants to contribute.
bob$ git clone /home/alice/project myrepo
This creates a new directory myrepo containing a clone of Alice’s
repository. The clone is on an equal footing with the original
project, possessing its own copy of the original project’s history.
Bob then makes some changes and commits them:
(edit files)
bob$ git commit -a
(repeat as necessary)
When he’s ready, he tells Alice to pull changes from the repository
at /home/bob/myrepo. She does this with:
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.
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 reviews 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:
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:
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:
alice$ git remote add bob /home/bob/myrepo
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:
Unlike the longhand form, when Alice fetches from Bob using a
remote repository shorthand set up with git remote, what was
fetched is stored in a remote-tracking branch, in this case
bob/master. So after this:
alice$ git log -p master..bob/master
shows a list of all the changes that Bob made since he branched from
Alice’s master branch.
After examining those changes, Alice
could merge the changes into her master branch:
alice$ git merge bob/master
This merge can also be done by pulling from her own remote-tracking
branch, like this:
alice$ git pull . remotes/bob/master
Note that git pull always merges into the current branch,
regardless of what else is given on the command line.
Later, Bob can update his repo with Alice’s latest changes using
Note that he doesn’t need to give the path to Alice’s repository;
when Bob cloned Alice’s repository, Git stored the location of her
repository in the repository configuration, and that location is
used for pulls:
bob$ git config --get remote.origin.url
/home/alice/project
(The complete configuration created by git clone is visible using
git config -l, and the git-config(1) man page
explains the meaning of each option.)
Git also keeps a pristine copy of Alice’s master branch under the
name origin/master:
bob$ git branch -r
origin/master
If Bob later decides to work from a different host, he can still
perform clones and pulls using the ssh protocol:
bob$ git clone alice.org:/home/alice/project myrepo
Alternatively, Git has a native protocol, or can use http;
see git-pull(1) for details.