origin/master
origin/next
...
-$ git branch checkout -b masterwork origin/master
+$ git checkout -b masterwork origin/master
-----------------------------------------------
Fetch a branch from a different repository, and give it a new
------------------------------------------------
$ cat >~/.gitconfig <<\EOF
[user]
-name = Your Name Comes Here
-email = you@yourdomain.example.com
+ name = Your Name Comes Here
+ email = you@yourdomain.example.com
EOF
------------------------------------------------
-----------------------------------------------
$ git format-patch origin..HEAD # format a patch for each commit
# in HEAD but not in origin
-$ git-am mbox # import patches from the mailbox "mbox"
+$ git am mbox # import patches from the mailbox "mbox"
-----------------------------------------------
Fetch a branch in a different git repository, then merge into the
collection of interrelated snapshots (versions) of the project's
contents.
-A single git repository may contain multiple branches. Each branch
-is a bookmark referencing a particular point in the project history.
-The gitlink:git-branch[1] command shows you the list of branches:
+A single git repository may contain multiple branches. It keeps track
+of them by keeping a list of <<def_head,heads>> which reference the
+latest version on each branch; the gitlink:git-branch[1] command shows
+you the list of branch heads:
------------------------------------------------
$ git branch
* master
------------------------------------------------
-A freshly cloned repository contains a single branch, named "master",
-and the working directory contains the version of the project
-referred to by the master branch.
+A freshly cloned repository contains a single branch head, named
+"master", and working directory is initialized to the state of
+the project referred to by "master".
-Most projects also use tags. Tags, like branches, are references
-into the project's history, and can be listed using the
+Most projects also use <<def_tag,tags>>. Tags, like heads, are
+references into the project's history, and can be listed using the
gitlink:git-tag[1] command:
------------------------------------------------
------------------------------------------------
Tags are expected to always point at the same version of a project,
-while branches are expected to advance as development progresses.
+while heads are expected to advance as development progresses.
-Create a new branch pointing to one of these versions and check it
+Create a new branch head pointing to one of these versions and check it
out using gitlink:git-checkout[1]:
------------------------------------------------
$ git reset --hard v2.6.17
------------------------------------------------
-Note that if the current branch was your only reference to a
+Note that if the current branch head was your only reference to a
particular point in history, then resetting that branch may leave you
-with no way to find the history it used to point to; so use this
-command carefully.
+with no way to find the history it used to point to; so use this command
+carefully.
Understanding History: Commits
------------------------------
below. Commits are shown as "o", and the links between them with
lines drawn with - / and \. Time goes left to right:
+
+................................................
o--o--o <-- Branch A
/
o--o--o <-- master
\
o--o--o <-- Branch B
+................................................
If we need to talk about a particular commit, the character "o" may
be replaced with another letter or number.
Understanding history: What is a branch?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Though we've been using the word "branch" to mean a kind of reference
-to a particular commit, the word branch is also commonly used to
-refer to the line of commits leading up to that point. In the
-example above, git may think of the branch named "A" as just a
-pointer to one particular commit, but we may refer informally to the
-line of three commits leading up to that point as all being part of
+When we need to be precise, we will use the word "branch" to mean a line
+of development, and "branch head" (or just "head") to mean a reference
+to the most recent commit on a branch. In the example above, the branch
+head named "A" is a pointer to one particular commit, but we refer to
+the line of three commits leading up to that point as all being part of
"branch A".
-If we need to make it clear that we're just talking about the most
-recent commit on the branch, we may refer to that commit as the
-"head" of the branch.
+However, when no confusion will result, we often just use the term
+"branch" both for branches and for branch heads.
Manipulating branches
---------------------
-------------------------------------------------
$ git remote add linux-nfs git://linux-nfs.org/pub/nfs-2.6.git
-$ git fetch
+$ git fetch linux-nfs
* refs/remotes/linux-nfs/master: storing branch 'master' ...
commit: bf81b46
-------------------------------------------------
$ cat .git/config
...
[remote "linux-nfs"]
- url = git://linux-nfs.org/~bfields/git.git
- fetch = +refs/heads/*:refs/remotes/linux-nfs-read/*
+ url = git://linux-nfs.org/pub/nfs-2.6.git
+ fetch = +refs/heads/*:refs/remotes/linux-nfs/*
...
-------------------------------------------------
run
-------------------------------------------------
-$ git bisect-visualize
+$ git bisect visualize
-------------------------------------------------
which will run gitk and label the commit it chose with a marker that
running
-------------------------------------------------
-$ git-tag stable-1 1b2e1d63ff
+$ git tag stable-1 1b2e1d63ff
-------------------------------------------------
You can use stable-1 to refer to the commit 1b2e1d63ff.
descendants:
-------------------------------------------------
-$ git name-rev e05db0fd
+$ git name-rev --tags e05db0fd
e05db0fd tags/v1.5.0-rc1^0~23
-------------------------------------------------
-------------------------------------------------
$ git describe e05db0fd
-v1.5.0-rc0-ge05db0f
+v1.5.0-rc0-260-ge05db0f
-------------------------------------------------
but that may sometimes help you guess which tags might come after the
-------------------------------------------------
[[how-to-make-a-commit]]
-how to make a commit
+How to make a commit
--------------------
Creating a new commit takes three steps:
$ git status # a brief per-file summary of the above.
-------------------------------------------------
-creating good commit messages
+Creating good commit messages
-----------------------------
Though not required, it's a good idea to begin the commit message
the first line on the Subject line and the rest of the commit in the
body.
-how to merge
+How to merge
------------
You can rejoin two diverging branches of development using
branch--then you are warned; the output may look something like this:
-------------------------------------------------
-$ git pull . next
-Trying really trivial in-index merge...
-fatal: Merge requires file-level merging
-Nope.
-Merging HEAD with 77976da35a11db4580b80ae27e8d65caf5208086
-Merging:
-15e2162 world
-77976da goodbye
-found 1 common ancestor(s):
-d122ed4 initial
-Auto-merging file.txt
+$ git merge next
+ 100% (4/4) done
+Auto-merged file.txt
CONFLICT (content): Merge conflict in file.txt
Automatic merge failed; fix conflicts and then commit the result.
-------------------------------------------------
information you need to help resolve the merge.
Files with conflicts are marked specially in the index, so until you
-resolve the problem and update the index, git commit will fail:
+resolve the problem and update the index, gitlink:git-commit[1] will
+fail:
-------------------------------------------------
$ git commit
file.txt: needs merge
-------------------------------------------------
-Also, git status will list those files as "unmerged".
+Also, gitlink:git-status[1] will list those files as "unmerged", and the
+files with conflicts will have conflict markers added, like this:
+
+-------------------------------------------------
+<<<<<<< HEAD:file.txt
+Hello world
+=======
+Goodbye
+>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
+-------------------------------------------------
+
+All you need to do is edit the files to resolve the conflicts, and then
+
+-------------------------------------------------
+$ git add file.txt
+$ git commit
+-------------------------------------------------
+
+Note that the commit message will already be filled in for you with
+some information about the merge. Normally you can just use this
+default message unchanged, but you may add additional commentary of
+your own if desired.
+
+The above is all you need to know to resolve a simple merge. But git
+also provides more information to help resolve conflicts:
+
+Getting conflict-resolution help during a merge
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
All of the changes that git was able to merge automatically are
already added to the index file, so gitlink:git-diff[1] shows only
-the conflicts. Also, it uses a somewhat unusual syntax:
+the conflicts. It uses an unusual syntax:
-------------------------------------------------
$ git diff
will be HEAD, the tip of the current branch; the other will be the
tip of the other branch, which is stored temporarily in MERGE_HEAD.
-The diff above shows the differences between the working-tree version
-of file.txt and two previous versions: one version from HEAD, and one
-from MERGE_HEAD. So instead of preceding each line by a single "+"
-or "-", it now uses two columns: the first column is used for
-differences between the first parent and the working directory copy,
-and the second for differences between the second parent and the
-working directory copy. Thus after resolving the conflict in the
-obvious way, the diff will look like:
+During the merge, the index holds three versions of each file. Each of
+these three "file stages" represents a different version of the file:
+
+-------------------------------------------------
+$ git show :1:file.txt # the file in a common ancestor of both branches
+$ git show :2:file.txt # the version from HEAD, but including any
+ # nonconflicting changes from MERGE_HEAD
+$ git show :3:file.txt # the version from MERGE_HEAD, but including any
+ # nonconflicting changes from HEAD.
+-------------------------------------------------
+
+Since the stage 2 and stage 3 versions have already been updated with
+nonconflicting changes, the only remaining differences between them are
+the important ones; thus gitlink:git-diff[1] can use the information in
+the index to show only those conflicts.
+
+The diff above shows the differences between the working-tree version of
+file.txt and the stage 2 and stage 3 versions. So instead of preceding
+each line by a single "+" or "-", it now uses two columns: the first
+column is used for differences between the first parent and the working
+directory copy, and the second for differences between the second parent
+and the working directory copy. (See the "COMBINED DIFF FORMAT" section
+of gitlink:git-diff-files[1] for a details of the format.)
+
+After resolving the conflict in the obvious way (but before updating the
+index), the diff will look like:
-------------------------------------------------
$ git diff
first parent, deleted "Goodbye" from the second parent, and added
"Goodbye world", which was previously absent from both.
-The gitlink:git-log[1] command also provides special help for merges:
+Some special diff options allow diffing the working directory against
+any of these stages:
+
+-------------------------------------------------
+$ git diff -1 file.txt # diff against stage 1
+$ git diff --base file.txt # same as the above
+$ git diff -2 file.txt # diff against stage 2
+$ git diff --ours file.txt # same as the above
+$ git diff -3 file.txt # diff against stage 3
+$ git diff --theirs file.txt # same as the above.
+-------------------------------------------------
+
+The gitlink:git-log[1] and gitk[1] commands also provide special help
+for merges:
-------------------------------------------------
$ git log --merge
+$ gitk --merge
-------------------------------------------------
-This will list all commits which exist only on HEAD or on MERGE_HEAD,
-and which touch an unmerged file.
+These will display all commits which exist only on HEAD or on
+MERGE_HEAD, and which touch an unmerged file.
-We can now add the resolved version to the index and commit:
+Each time you resolve the conflicts in a file and update the index:
-------------------------------------------------
$ git add file.txt
-$ git commit
-------------------------------------------------
-Note that the commit message will already be filled in for you with
-some information about the merge. Normally you can just use this
-default message unchanged, but you may add additional commentary of
-your own if desired.
+the different stages of that file will be "collapsed", after which
+git-diff will (by default) no longer show diffs for that file.
[[undoing-a-merge]]
-undoing a merge
+Undoing a merge
---------------
If you get stuck and decide to just give up and throw the whole mess
gitlink:git-show[1]:
-------------------------------------------------
-$ git show HEAD^ path/to/file
+$ git show HEAD^:path/to/file
-------------------------------------------------
which will display the given version of the file.
then you can just pull changes from each other's repositories
directly; note that all of the commands (gitlink:git-clone[1],
git-fetch[1], git-pull[1], etc.) that accept a URL as an argument
-will also accept a local file patch; so, for example, you can
+will also accept a local directory name; so, for example, you can
use
-------------------------------------------------
The gitweb cgi script provides users an easy way to browse your
project's files and history without having to install git; see the file
-gitweb/README in the git source tree for instructions on setting it up.
+gitweb/INSTALL in the git source tree for instructions on setting it up.
Examples
--------
You have performed no merges into mywork, so it is just a simple linear
sequence of patches on top of "origin":
-
+................................................
o--o--o <-- origin
\
o--o--o <-- mywork
+................................................
Some more interesting work has been done in the upstream project, and
"origin" has advanced:
+................................................
o--o--O--o--o--o <-- origin
\
a--b--c <-- mywork
+................................................
At this point, you could use "pull" to merge your changes back in;
the result would create a new merge commit, like this:
-
+................................................
o--o--O--o--o--o <-- origin
\ \
a--b--c--m <-- mywork
+................................................
However, if you prefer to keep the history in mywork a simple series of
commits without any merges, you may instead choose to use
patches to the new mywork. The result will look like:
+................................................
o--o--O--o--o--o <-- origin
\
a'--b'--c' <-- mywork
+................................................
In the process, it may discover conflicts. In that case it will stop
and allow you to fix the conflicts; after fixing conflicts, use "git
with merging. Suppose somebody fetches your branch and merges it into
their branch, with a result something like this:
+................................................
o--o--O--o--o--o <-- origin
\ \
t--t--t--m <-- their branch:
+................................................
Then suppose you modify the last three commits:
+................................................
o--o--o <-- new head of origin
/
o--o--O--o--o--o <-- old head of origin
+................................................
If we examined all this history together in one repository, it will
look like:
+................................................
o--o--o <-- new head of origin
/
o--o--O--o--o--o <-- old head of origin
\ \
t--t--t--m <-- their branch:
+................................................
Git has no way of knowing that the new head is an updated version of
the old head; it treats this situation exactly the same as it would if
A fast forward looks something like this:
+................................................
o--o--o--o <-- old head of the branch
\
o--o--o <-- new head of the branch
+................................................
In some cases it is possible that the new head will *not* actually be
realized she made a serious mistake, and decided to backtrack,
resulting in a situation like:
+................................................
o--o--o--o--a--b <-- old head of the branch
\
o--o--o <-- new head of the branch
-
-
+................................................
In this case, "git fetch" will fail, and print out a warning.
$ git-merge-index git-merge-one-file hello.c
-------------------------------------------------
-and that is what higher level `git resolve` is implemented with.
+and that is what higher level `git merge -s resolve` is implemented with.
How git stores objects efficiently: pack files
----------------------------------------------
contrast, running "git prune" while somebody is actively changing the
repository is a *BAD* idea).
-Glossary of git terms
-=====================
-
include::glossary.txt[]
Notes and todo list for this manual
Simplify beginning by suggesting disconnected head instead of
temporary branch creation?
-Explain how to refer to file stages in the "how to resolve a merge"
-section: diff -1, -2, -3, --ours, --theirs :1:/path notation. The
-"git ls-files --unmerged --stage" thing is sorta useful too,
-actually. And note gitk --merge.
-
Add more good examples. Entire sections of just cookbook examples
might be a good idea; maybe make an "advanced examples" section a
standard end-of-chapter section?