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
------------------------------
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
-------------------------------------------------
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
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
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
--------
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