_________________
This manual is designed to be readable by someone with basic unix
-commandline skills, but no previous knowledge of git.
+command-line skills, but no previous knowledge of git.
Chapter 1 gives a brief overview of git commands, without any
explanation; you may prefer to skip to chapter 2 on a first reading.
importantly, it is a globally unique name for this commit: so if you
tell somebody else the object name (for example in email), then you are
guaranteed that name will refer to the same commit in their repository
-that you it does in yours (assuming their repository has that commit at
+that it does in yours (assuming their repository has that commit at
all).
Understanding history: commits, parents, and reachability
that Y is a descendent of X, or that there is a chain of parents
leading from commit Y to commit X.
-Undestanding history: History diagrams
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Understanding history: History diagrams
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
We will sometimes represent git history using diagrams like the one
below. Commits are shown as "o", and the links between them with
Git provides extremely flexible and fast tools for exploring the
history of a project.
-We start with one specialized tool which is useful for finding the
+We start with one specialized tool that is useful for finding the
commit that introduced a bug into a project.
How to use bisect to find a regression
We have seen several ways of naming commits already:
- - 40-hexdigit SHA1 id
+ - 40-hexdigit object name
- branch name: refers to the commit at the head of the given
branch
- tag name: refers to the commit pointed to by the given tag
name revisions. Some examples:
-------------------------------------------------
-$ git show fb47ddb2 # the first few characters of the SHA1 id
+$ git show fb47ddb2 # the first few characters of the object name
# are usually enough to specify it uniquely
$ git show HEAD^ # the parent of the HEAD commit
$ git show HEAD^^ # the grandparent
branch.
The gitlink:git-rev-parse[1] command is a low-level command that is
-occasionally useful for translating some name for a commit to the SHA1 id for
-that commit:
+occasionally useful for translating some name for a commit to the object
+name for that commit:
-------------------------------------------------
$ git rev-parse origin
Note that git log starts with the most recent commit and works
backwards through the parents; however, since git history can contain
-multiple independant lines of development, the particular order that
+multiple independent lines of development, the particular order that
commits are listed in may be somewhat arbitrary.
Generating diffs
will tell you whether the contents of the project are the same at the
two branches; in theory, however, it's possible that the same project
contents could have been arrived at by two different historical
-routes. You could compare the SHA1 id's:
+routes. You could compare the object names:
-------------------------------------------------
$ git rev-list origin
Alternatively, note that
-------------------------------------------------
-$ git log v1.5.0-rc1..305db0fd
+$ git log v1.5.0-rc1..e05db0fd
-------------------------------------------------
-will produce empty output if and only if v1.5.0-rc1 includes 305db0fd,
+will produce empty output if and only if v1.5.0-rc1 includes e05db0fd,
because it outputs only commits that are not reachable from v1.5.0-rc1.
+As yet another alternative, the gitlink:git-show-branch[1] command lists
+the commits reachable from its arguments with a display on the left-hand
+side that indicates which arguments that commit is reachable from. So,
+you can run something like
+
+-------------------------------------------------
+$ git show-branch e05db0fd v1.5.0-rc0 v1.5.0-rc1 v1.5.0-rc2
+! [e05db0fd] Fix warnings in sha1_file.c - use C99 printf format if
+available
+ ! [v1.5.0-rc0] GIT v1.5.0 preview
+ ! [v1.5.0-rc1] GIT v1.5.0-rc1
+ ! [v1.5.0-rc2] GIT v1.5.0-rc2
+...
+-------------------------------------------------
+
+then search for a line that looks like
+
+-------------------------------------------------
++ ++ [e05db0fd] Fix warnings in sha1_file.c - use C99 printf format if
+available
+-------------------------------------------------
+
+Which shows that e05db0fd is reachable from itself, from v1.5.0-rc1, and
+from v1.5.0-rc2, but not from v1.5.0-rc0.
+
+
Developing with git
===================
-------------------------------------------------
and git will prompt you for a commit message and then create the new
-commmit. Check to make sure it looks like what you expected with
+commit. Check to make sure it looks like what you expected with
-------------------------------------------------
$ git show
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 version: one version from HEAD, and one
+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,
-------------------------------------------------
The reflogs are kept by default for 30 days, after which they may be
-pruned. See gitlink:git-reflink[1] and gitlink:git-gc[1] to learn
+pruned. See gitlink:git-reflog[1] and gitlink:git-gc[1] to learn
how to control this pruning, and see the "SPECIFYING REVISIONS"
section of gitlink:git-rev-parse[1] for details.
In some situations the reflog may not be able to save you. For
example, suppose you delete a branch, then realize you need the history
-it pointed you. The reflog is also deleted; however, if you have not
+it contained. The reflog is also deleted; however, if you have not
yet pruned the repository, then you may still be able to find
the lost commits; run git-fsck and watch for output that mentions
"dangling commits":
...
-------------------------------------------------
-and watch for output that mentions "dangling commits". You can examine
+You can examine
one of those dangling commits with, for example,
------------------------------------------------
you get exactly the history reachable from that commit that is lost.
(And notice that it might not be just one commit: we only report the
"tip of the line" as being dangling, but there might be a whole deep
-and complex commit history that was gotten dropped.)
+and complex commit history that was dropped.)
If you decide you want the history back, you can always create a new
reference pointing to it, for example, a new branch:
(But note that no such commit will be created in the case of a
<<fast-forwards,fast forward>>; instead, your branch will just be
-updated to point to the latest commit from the upstream branch).
+updated to point to the latest commit from the upstream branch.)
The git-pull command can also be given "." as the "remote" repository,
in which case it just merges in a branch from the current repository; so
If you just have a few changes, the simplest way to submit them may
just be to send them as patches in email:
-First, use gitlink:git-format-patches[1]; for example:
+First, use gitlink:git-format-patch[1]; for example:
-------------------------------------------------
$ git format-patch origin
If you and maintainer both have accounts on the same machine, then
then you can just pull changes from each other's repositories
-directly; note that all of the command (gitlink:git-clone[1],
-git-fetch[1], git-pull[1], etc.) which accept a URL as an argument
+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
use
Allow web browsing of a repository
----------------------------------
-TODO: Brief setup-instructions for gitweb
+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.
Examples
--------
TODO: topic branches, typical roles as in everyday.txt, ?
-Working with other version control systems
-==========================================
-
-TODO: CVS, Subversion, series-of-release-tarballs, etc.
-
[[cleaning-up-history]]
Rewriting history and maintaining patch series
==============================================
correct, and understand why you made each change.
If you present all of your changes as a single patch (or commit), they
-may find it is too much to digest all at once.
+may find that it is too much to digest all at once.
If you present them with the entire history of your work, complete with
mistakes, corrections, and dead ends, they may be overwhelmed.
Keeping a patch series up to date using git-rebase
--------------------------------------------------
-Suppose you have a series of commits in a branch "mywork", which
-originally branched off from "origin".
-
-Suppose you create a branch "mywork" on a remote-tracking branch
-"origin", and created some commits on top of it:
+Suppose that you create a branch "mywork" on a remote-tracking branch
+"origin", and create some commits on top of it:
-------------------------------------------------
$ git checkout -b mywork origin
-----------
There are numerous other tools, such as stgit, which exist for the
-purpose of maintaining a patch series. These are out of the scope of
+purpose of maintaining a patch series. These are outside of the scope of
this manual.
Problems with rewriting history
$ git fetch git://example.com/proj.git +master:refs/remotes/example/master
-------------------------------------------------
-Note the addition of the "+" sign. Be aware that commits which the
+Note the addition of the "+" sign. Be aware that commits that the
old version of example/master pointed at may be lost, as we saw in
the previous section.
---------------------------
We saw above that "origin" is just a shortcut to refer to the
-repository which you originally cloned from. This information is
+repository that you originally cloned from. This information is
stored in git configuration variables, which you can see using
gitlink:git-config[1]:
associated with sufficient information about the trees involved that
you can create a three-way merge between them.'
-Those are the three ONLY things that the directory cache does. It's a
+Those are the ONLY three things that the directory cache does. It's a
cache, and the normal operation is to re-generate it completely from a
known tree object, or update/compare it with a live tree that is being
developed. If you blow the directory cache away entirely, you generally
$ 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
----------------------------------------------
allow people to get to important topics without necessarily reading
everything in between.
+Say something about .gitignore.
+
Scan Documentation/ for other stuff left out; in particular:
howto's
- README
some of technical/?
hooks
- etc.
+ list of commands in gitlink:git[1]
Scan email archives for other stuff left out
Include cross-references to the glossary, where appropriate.
-To document:
- reflogs, git reflog expire
- shallow clones?? See draft 1.5.0 release notes for some documentation.
+Document shallow clones? See draft 1.5.0 release notes for some
+documentation.
+
+Add a section on working with other version control systems, including
+CVS, Subversion, and just imports of series of release tarballs.
+
+More details on gitweb?
+
+Write a chapter on using plumbing and writing scripts.