summaryrefslogtreecommitdiffstats
path: root/Documentation/user-manual.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/user-manual.txt')
-rw-r--r--Documentation/user-manual.txt4606
1 files changed, 4606 insertions, 0 deletions
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
new file mode 100644
index 0000000..d8dbe6b
--- /dev/null
+++ b/Documentation/user-manual.txt
@@ -0,0 +1,4606 @@
+= Git User Manual
+
+[preface]
+== Introduction
+
+Git is a fast distributed revision control system.
+
+This manual is designed to be readable by someone with basic UNIX
+command-line skills, but no previous knowledge of Git.
+
+<<repositories-and-branches>> and <<exploring-git-history>> explain how
+to fetch and study a project using git--read these chapters to learn how
+to build and test a particular version of a software project, search for
+regressions, and so on.
+
+People needing to do actual development will also want to read
+<<Developing-With-git>> and <<sharing-development>>.
+
+Further chapters cover more specialized topics.
+
+Comprehensive reference documentation is available through the man
+pages, or linkgit:git-help[1] command. For example, for the command
+`git clone <repo>`, you can either use:
+
+------------------------------------------------
+$ man git-clone
+------------------------------------------------
+
+or:
+
+------------------------------------------------
+$ git help clone
+------------------------------------------------
+
+With the latter, you can use the manual viewer of your choice; see
+linkgit:git-help[1] for more information.
+
+See also <<git-quick-start>> for a brief overview of Git commands,
+without any explanation.
+
+Finally, see <<todo>> for ways that you can help make this manual more
+complete.
+
+
+[[repositories-and-branches]]
+== Repositories and Branches
+
+[[how-to-get-a-git-repository]]
+=== How to get a Git repository
+
+It will be useful to have a Git repository to experiment with as you
+read this manual.
+
+The best way to get one is by using the linkgit:git-clone[1] command to
+download a copy of an existing repository. If you don't already have a
+project in mind, here are some interesting examples:
+
+------------------------------------------------
+ # Git itself (approx. 40MB download):
+$ git clone git://git.kernel.org/pub/scm/git/git.git
+ # the Linux kernel (approx. 640MB download):
+$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
+------------------------------------------------
+
+The initial clone may be time-consuming for a large project, but you
+will only need to clone once.
+
+The clone command creates a new directory named after the project
+(`git` or `linux` in the examples above). After you cd into this
+directory, you will see that it contains a copy of the project files,
+called the <<def_working_tree,working tree>>, together with a special
+top-level directory named `.git`, which contains all the information
+about the history of the project.
+
+[[how-to-check-out]]
+=== How to check out a different version of a project
+
+Git is best thought of as a tool for storing the history of a collection
+of files. It stores the history as a compressed collection of
+interrelated snapshots of the project's contents. In Git each such
+version is called a <<def_commit,commit>>.
+
+Those snapshots aren't necessarily all arranged in a single line from
+oldest to newest; instead, work may simultaneously proceed along
+parallel lines of development, called <<def_branch,branches>>, which may
+merge and diverge.
+
+A single Git repository can track development on multiple branches. It
+does this by keeping a list of <<def_head,heads>> which reference the
+latest commit on each branch; the linkgit:git-branch[1] command shows
+you the list of branch heads:
+
+------------------------------------------------
+$ git branch
+* master
+------------------------------------------------
+
+A freshly cloned repository contains a single branch head, by default
+named "master", with the working directory initialized to the state of
+the project referred to by that branch head.
+
+Most projects also use <<def_tag,tags>>. Tags, like heads, are
+references into the project's history, and can be listed using the
+linkgit:git-tag[1] command:
+
+------------------------------------------------
+$ git tag -l
+v2.6.11
+v2.6.11-tree
+v2.6.12
+v2.6.12-rc2
+v2.6.12-rc3
+v2.6.12-rc4
+v2.6.12-rc5
+v2.6.12-rc6
+v2.6.13
+...
+------------------------------------------------
+
+Tags are expected to always point at the same version of a project,
+while heads are expected to advance as development progresses.
+
+Create a new branch head pointing to one of these versions and check it
+out using linkgit:git-switch[1]:
+
+------------------------------------------------
+$ git switch -c new v2.6.13
+------------------------------------------------
+
+The working directory then reflects the contents that the project had
+when it was tagged v2.6.13, and linkgit:git-branch[1] shows two
+branches, with an asterisk marking the currently checked-out branch:
+
+------------------------------------------------
+$ git branch
+ master
+* new
+------------------------------------------------
+
+If you decide that you'd rather see version 2.6.17, you can modify
+the current branch to point at v2.6.17 instead, with
+
+------------------------------------------------
+$ git reset --hard v2.6.17
+------------------------------------------------
+
+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.
+
+[[understanding-commits]]
+=== Understanding History: Commits
+
+Every change in the history of a project is represented by a commit.
+The linkgit:git-show[1] command shows the most recent commit on the
+current branch:
+
+------------------------------------------------
+$ git show
+commit 17cf781661e6d38f737f15f53ab552f1e95960d7
+Author: Linus Torvalds <torvalds@ppc970.osdl.org.(none)>
+Date: Tue Apr 19 14:11:06 2005 -0700
+
+ Remove duplicate getenv(DB_ENVIRONMENT) call
+
+ Noted by Tony Luck.
+
+diff --git a/init-db.c b/init-db.c
+index 65898fa..b002dc6 100644
+--- a/init-db.c
++++ b/init-db.c
+@@ -7,7 +7,7 @@
+
+ int main(int argc, char **argv)
+ {
+- char *sha1_dir = getenv(DB_ENVIRONMENT), *path;
++ char *sha1_dir, *path;
+ int len, i;
+
+ if (mkdir(".git", 0755) < 0) {
+------------------------------------------------
+
+As you can see, a commit shows who made the latest change, what they
+did, and why.
+
+Every commit has a 40-hexdigit id, sometimes called the "object name" or the
+"SHA-1 id", shown on the first line of the `git show` output. You can usually
+refer to a commit by a shorter name, such as a tag or a branch name, but this
+longer name can also be useful. Most 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 it does in yours (assuming their repository
+has that commit at all). Since the object name is computed as a hash over the
+contents of the commit, you are guaranteed that the commit can never change
+without its name also changing.
+
+In fact, in <<git-concepts>> we shall see that everything stored in Git
+history, including file data and directory contents, is stored in an object
+with a name that is a hash of its contents.
+
+[[understanding-reachability]]
+==== Understanding history: commits, parents, and reachability
+
+Every commit (except the very first commit in a project) also has a
+parent commit which shows what happened before this commit.
+Following the chain of parents will eventually take you back to the
+beginning of the project.
+
+However, the commits do not form a simple list; Git allows lines of
+development to diverge and then reconverge, and the point where two
+lines of development reconverge is called a "merge". The commit
+representing a merge can therefore have more than one parent, with
+each parent representing the most recent commit on one of the lines
+of development leading to that point.
+
+The best way to see how this works is using the linkgit:gitk[1]
+command; running gitk now on a Git repository and looking for merge
+commits will help understand how Git organizes history.
+
+In the following, we say that commit X is "reachable" from commit Y
+if commit X is an ancestor of commit Y. Equivalently, you could say
+that Y is a descendant of X, or that there is a chain of parents
+leading from commit Y to commit X.
+
+[[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
+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.
+
+[[what-is-a-branch]]
+==== Understanding history: What is a branch?
+
+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".
+
+However, when no confusion will result, we often just use the term
+"branch" both for branches and for branch heads.
+
+[[manipulating-branches]]
+=== Manipulating branches
+
+Creating, deleting, and modifying branches is quick and easy; here's
+a summary of the commands:
+
+`git branch`::
+ list all branches.
+`git branch <branch>`::
+ create a new branch named `<branch>`, referencing the same
+ point in history as the current branch.
+`git branch <branch> <start-point>`::
+ create a new branch named `<branch>`, referencing
+ `<start-point>`, which may be specified any way you like,
+ including using a branch name or a tag name.
+`git branch -d <branch>`::
+ delete the branch `<branch>`; if the branch is not fully
+ merged in its upstream branch or contained in the current branch,
+ this command will fail with a warning.
+`git branch -D <branch>`::
+ delete the branch `<branch>` irrespective of its merged status.
+`git switch <branch>`::
+ make the current branch `<branch>`, updating the working
+ directory to reflect the version referenced by `<branch>`.
+`git switch -c <new> <start-point>`::
+ create a new branch `<new>` referencing `<start-point>`, and
+ check it out.
+
+The special symbol "HEAD" can always be used to refer to the current
+branch. In fact, Git uses a file named `HEAD` in the `.git` directory
+to remember which branch is current:
+
+------------------------------------------------
+$ cat .git/HEAD
+ref: refs/heads/master
+------------------------------------------------
+
+[[detached-head]]
+=== Examining an old version without creating a new branch
+
+The `git switch` command normally expects a branch head, but will also
+accept an arbitrary commit when invoked with --detach; for example,
+you can check out the commit referenced by a tag:
+
+------------------------------------------------
+$ git switch --detach v2.6.17
+Note: checking out 'v2.6.17'.
+
+You are in 'detached HEAD' state. You can look around, make experimental
+changes and commit them, and you can discard any commits you make in this
+state without impacting any branches by performing another switch.
+
+If you want to create a new branch to retain commits you create, you may
+do so (now or later) by using -c with the switch command again. Example:
+
+ git switch -c new_branch_name
+
+HEAD is now at 427abfa Linux v2.6.17
+------------------------------------------------
+
+The HEAD then refers to the SHA-1 of the commit instead of to a branch,
+and git branch shows that you are no longer on a branch:
+
+------------------------------------------------
+$ cat .git/HEAD
+427abfa28afedffadfca9dd8b067eb6d36bac53f
+$ git branch
+* (detached from v2.6.17)
+ master
+------------------------------------------------
+
+In this case we say that the HEAD is "detached".
+
+This is an easy way to check out a particular version without having to
+make up a name for the new branch. You can still create a new branch
+(or tag) for this version later if you decide to.
+
+[[examining-remote-branches]]
+=== Examining branches from a remote repository
+
+The "master" branch that was created at the time you cloned is a copy
+of the HEAD in the repository that you cloned from. That repository
+may also have had other branches, though, and your local repository
+keeps branches which track each of those remote branches, called
+remote-tracking branches, which you
+can view using the `-r` option to linkgit:git-branch[1]:
+
+------------------------------------------------
+$ git branch -r
+ origin/HEAD
+ origin/html
+ origin/maint
+ origin/man
+ origin/master
+ origin/next
+ origin/seen
+ origin/todo
+------------------------------------------------
+
+In this example, "origin" is called a remote repository, or "remote"
+for short. The branches of this repository are called "remote
+branches" from our point of view. The remote-tracking branches listed
+above were created based on the remote branches at clone time and will
+be updated by `git fetch` (hence `git pull`) and `git push`. See
+<<Updating-a-repository-With-git-fetch>> for details.
+
+You might want to build on one of these remote-tracking branches
+on a branch of your own, just as you would for a tag:
+
+------------------------------------------------
+$ git switch -c my-todo-copy origin/todo
+------------------------------------------------
+
+You can also check out `origin/todo` directly to examine it or
+write a one-off patch. See <<detached-head,detached head>>.
+
+Note that the name "origin" is just the name that Git uses by default
+to refer to the repository that you cloned from.
+
+[[how-git-stores-references]]
+=== Naming branches, tags, and other references
+
+Branches, remote-tracking branches, and tags are all references to
+commits. All references are named with a slash-separated path name
+starting with `refs`; the names we've been using so far are actually
+shorthand:
+
+ - The branch `test` is short for `refs/heads/test`.
+ - The tag `v2.6.18` is short for `refs/tags/v2.6.18`.
+ - `origin/master` is short for `refs/remotes/origin/master`.
+
+The full name is occasionally useful if, for example, there ever
+exists a tag and a branch with the same name.
+
+(Newly created refs are actually stored in the `.git/refs` directory,
+under the path given by their name. However, for efficiency reasons
+they may also be packed together in a single file; see
+linkgit:git-pack-refs[1]).
+
+As another useful shortcut, the "HEAD" of a repository can be referred
+to just using the name of that repository. So, for example, "origin"
+is usually a shortcut for the HEAD branch in the repository "origin".
+
+For the complete list of paths which Git checks for references, and
+the order it uses to decide which to choose when there are multiple
+references with the same shorthand name, see the "SPECIFYING
+REVISIONS" section of linkgit:gitrevisions[7].
+
+[[Updating-a-repository-With-git-fetch]]
+=== Updating a repository with git fetch
+
+After you clone a repository and commit a few changes of your own, you
+may wish to check the original repository for updates.
+
+The `git-fetch` command, with no arguments, will update all of the
+remote-tracking branches to the latest version found in the original
+repository. It will not touch any of your own branches--not even the
+"master" branch that was created for you on clone.
+
+[[fetching-branches]]
+=== Fetching branches from other repositories
+
+You can also track branches from repositories other than the one you
+cloned from, using linkgit:git-remote[1]:
+
+-------------------------------------------------
+$ git remote add staging git://git.kernel.org/.../gregkh/staging.git
+$ git fetch staging
+...
+From git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/staging
+ * [new branch] master -> staging/master
+ * [new branch] staging-linus -> staging/staging-linus
+ * [new branch] staging-next -> staging/staging-next
+-------------------------------------------------
+
+New remote-tracking branches will be stored under the shorthand name
+that you gave `git remote add`, in this case `staging`:
+
+-------------------------------------------------
+$ git branch -r
+ origin/HEAD -> origin/master
+ origin/master
+ staging/master
+ staging/staging-linus
+ staging/staging-next
+-------------------------------------------------
+
+If you run `git fetch <remote>` later, the remote-tracking branches
+for the named `<remote>` will be updated.
+
+If you examine the file `.git/config`, you will see that Git has added
+a new stanza:
+
+-------------------------------------------------
+$ cat .git/config
+...
+[remote "staging"]
+ url = git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/staging.git
+ fetch = +refs/heads/*:refs/remotes/staging/*
+...
+-------------------------------------------------
+
+This is what causes Git to track the remote's branches; you may modify
+or delete these configuration options by editing `.git/config` with a
+text editor. (See the "CONFIGURATION FILE" section of
+linkgit:git-config[1] for details.)
+
+[[exploring-git-history]]
+== Exploring Git history
+
+Git is best thought of as a tool for storing the history of a
+collection of files. It does this by storing compressed snapshots of
+the contents of a file hierarchy, together with "commits" which show
+the relationships between these snapshots.
+
+Git provides extremely flexible and fast tools for exploring the
+history of a project.
+
+We start with one specialized tool that is useful for finding the
+commit that introduced a bug into a project.
+
+[[using-bisect]]
+=== How to use bisect to find a regression
+
+Suppose version 2.6.18 of your project worked, but the version at
+"master" crashes. Sometimes the best way to find the cause of such a
+regression is to perform a brute-force search through the project's
+history to find the particular commit that caused the problem. The
+linkgit:git-bisect[1] command can help you do this:
+
+-------------------------------------------------
+$ git bisect start
+$ git bisect good v2.6.18
+$ git bisect bad master
+Bisecting: 3537 revisions left to test after this
+[65934a9a028b88e83e2b0f8b36618fe503349f8e] BLOCK: Make USB storage depend on SCSI rather than selecting it [try #6]
+-------------------------------------------------
+
+If you run `git branch` at this point, you'll see that Git has
+temporarily moved you in "(no branch)". HEAD is now detached from any
+branch and points directly to a commit (with commit id 65934) that
+is reachable from "master" but not from v2.6.18. Compile and test it,
+and see whether it crashes. Assume it does crash. Then:
+
+-------------------------------------------------
+$ git bisect bad
+Bisecting: 1769 revisions left to test after this
+[7eff82c8b1511017ae605f0c99ac275a7e21b867] i2c-core: Drop useless bitmaskings
+-------------------------------------------------
+
+checks out an older version. Continue like this, telling Git at each
+stage whether the version it gives you is good or bad, and notice
+that the number of revisions left to test is cut approximately in
+half each time.
+
+After about 13 tests (in this case), it will output the commit id of
+the guilty commit. You can then examine the commit with
+linkgit:git-show[1], find out who wrote it, and mail them your bug
+report with the commit id. Finally, run
+
+-------------------------------------------------
+$ git bisect reset
+-------------------------------------------------
+
+to return you to the branch you were on before.
+
+Note that the version which `git bisect` checks out for you at each
+point is just a suggestion, and you're free to try a different
+version if you think it would be a good idea. For example,
+occasionally you may land on a commit that broke something unrelated;
+run
+
+-------------------------------------------------
+$ git bisect visualize
+-------------------------------------------------
+
+which will run gitk and label the commit it chose with a marker that
+says "bisect". Choose a safe-looking commit nearby, note its commit
+id, and check it out with:
+
+-------------------------------------------------
+$ git reset --hard fb47ddb2db
+-------------------------------------------------
+
+then test, run `bisect good` or `bisect bad` as appropriate, and
+continue.
+
+Instead of `git bisect visualize` and then `git reset --hard
+fb47ddb2db`, you might just want to tell Git that you want to skip
+the current commit:
+
+-------------------------------------------------
+$ git bisect skip
+-------------------------------------------------
+
+In this case, though, Git may not eventually be able to tell the first
+bad one between some first skipped commits and a later bad commit.
+
+There are also ways to automate the bisecting process if you have a
+test script that can tell a good from a bad commit. See
+linkgit:git-bisect[1] for more information about this and other `git
+bisect` features.
+
+[[naming-commits]]
+=== Naming commits
+
+We have seen several ways of naming commits already:
+
+ - 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
+ (we've seen branches and tags are special cases of
+ <<how-git-stores-references,references>>).
+ - HEAD: refers to the head of the current branch
+
+There are many more; see the "SPECIFYING REVISIONS" section of the
+linkgit:gitrevisions[7] man page for the complete list of ways to
+name revisions. Some examples:
+
+-------------------------------------------------
+$ 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
+$ git show HEAD~4 # the great-great-grandparent
+-------------------------------------------------
+
+Recall that merge commits may have more than one parent; by default,
+`^` and `~` follow the first parent listed in the commit, but you can
+also choose:
+
+-------------------------------------------------
+$ git show HEAD^1 # show the first parent of HEAD
+$ git show HEAD^2 # show the second parent of HEAD
+-------------------------------------------------
+
+In addition to HEAD, there are several other special names for
+commits:
+
+Merges (to be discussed later), as well as operations such as
+`git reset`, which change the currently checked-out commit, generally
+set ORIG_HEAD to the value HEAD had before the current operation.
+
+The `git fetch` operation always stores the head of the last fetched
+branch in FETCH_HEAD. For example, if you run `git fetch` without
+specifying a local branch as the target of the operation
+
+-------------------------------------------------
+$ git fetch git://example.com/proj.git theirbranch
+-------------------------------------------------
+
+the fetched commits will still be available from FETCH_HEAD.
+
+When we discuss merges we'll also see the special name MERGE_HEAD,
+which refers to the other branch that we're merging in to the current
+branch.
+
+The linkgit:git-rev-parse[1] command is a low-level command that is
+occasionally useful for translating some name for a commit to the object
+name for that commit:
+
+-------------------------------------------------
+$ git rev-parse origin
+e05db0fd4f31dde7005f075a84f96b360d05984b
+-------------------------------------------------
+
+[[creating-tags]]
+=== Creating tags
+
+We can also create a tag to refer to a particular commit; after
+running
+
+-------------------------------------------------
+$ git tag stable-1 1b2e1d63ff
+-------------------------------------------------
+
+You can use `stable-1` to refer to the commit 1b2e1d63ff.
+
+This creates a "lightweight" tag. If you would also like to include a
+comment with the tag, and possibly sign it cryptographically, then you
+should create a tag object instead; see the linkgit:git-tag[1] man page
+for details.
+
+[[browsing-revisions]]
+=== Browsing revisions
+
+The linkgit:git-log[1] command can show lists of commits. On its
+own, it shows all commits reachable from the parent commit; but you
+can also make more specific requests:
+
+-------------------------------------------------
+$ git log v2.5.. # commits since (not reachable from) v2.5
+$ git log test..master # commits reachable from master but not test
+$ git log master..test # ...reachable from test but not master
+$ git log master...test # ...reachable from either test or master,
+ # but not both
+$ git log --since="2 weeks ago" # commits from the last 2 weeks
+$ git log Makefile # commits which modify Makefile
+$ git log fs/ # ... which modify any file under fs/
+$ git log -S'foo()' # commits which add or remove any file data
+ # matching the string 'foo()'
+-------------------------------------------------
+
+And of course you can combine all of these; the following finds
+commits since v2.5 which touch the `Makefile` or any file under `fs`:
+
+-------------------------------------------------
+$ git log v2.5.. Makefile fs/
+-------------------------------------------------
+
+You can also ask git log to show patches:
+
+-------------------------------------------------
+$ git log -p
+-------------------------------------------------
+
+See the `--pretty` option in the linkgit:git-log[1] man page for more
+display options.
+
+Note that git log starts with the most recent commit and works
+backwards through the parents; however, since Git history can contain
+multiple independent lines of development, the particular order that
+commits are listed in may be somewhat arbitrary.
+
+[[generating-diffs]]
+=== Generating diffs
+
+You can generate diffs between any two versions using
+linkgit:git-diff[1]:
+
+-------------------------------------------------
+$ git diff master..test
+-------------------------------------------------
+
+That will produce the diff between the tips of the two branches. If
+you'd prefer to find the diff from their common ancestor to test, you
+can use three dots instead of two:
+
+-------------------------------------------------
+$ git diff master...test
+-------------------------------------------------
+
+Sometimes what you want instead is a set of patches; for this you can
+use linkgit:git-format-patch[1]:
+
+-------------------------------------------------
+$ git format-patch master..test
+-------------------------------------------------
+
+will generate a file with a patch for each commit reachable from test
+but not from master.
+
+[[viewing-old-file-versions]]
+=== Viewing old file versions
+
+You can always view an old version of a file by just checking out the
+correct revision first. But sometimes it is more convenient to be
+able to view an old version of a single file without checking
+anything out; this command does that:
+
+-------------------------------------------------
+$ git show v2.5:fs/locks.c
+-------------------------------------------------
+
+Before the colon may be anything that names a commit, and after it
+may be any path to a file tracked by Git.
+
+[[history-examples]]
+=== Examples
+
+[[counting-commits-on-a-branch]]
+==== Counting the number of commits on a branch
+
+Suppose you want to know how many commits you've made on `mybranch`
+since it diverged from `origin`:
+
+-------------------------------------------------
+$ git log --pretty=oneline origin..mybranch | wc -l
+-------------------------------------------------
+
+Alternatively, you may often see this sort of thing done with the
+lower-level command linkgit:git-rev-list[1], which just lists the SHA-1's
+of all the given commits:
+
+-------------------------------------------------
+$ git rev-list origin..mybranch | wc -l
+-------------------------------------------------
+
+[[checking-for-equal-branches]]
+==== Check whether two branches point at the same history
+
+Suppose you want to check whether two branches point at the same point
+in history.
+
+-------------------------------------------------
+$ git diff origin..master
+-------------------------------------------------
+
+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 object names:
+
+-------------------------------------------------
+$ git rev-list origin
+e05db0fd4f31dde7005f075a84f96b360d05984b
+$ git rev-list master
+e05db0fd4f31dde7005f075a84f96b360d05984b
+-------------------------------------------------
+
+Or you could recall that the `...` operator selects all commits
+reachable from either one reference or the other but not
+both; so
+
+-------------------------------------------------
+$ git log origin...master
+-------------------------------------------------
+
+will return no commits when the two branches are equal.
+
+[[finding-tagged-descendants]]
+==== Find first tagged version including a given fix
+
+Suppose you know that the commit e05db0fd fixed a certain problem.
+You'd like to find the earliest tagged release that contains that
+fix.
+
+Of course, there may be more than one answer--if the history branched
+after commit e05db0fd, then there could be multiple "earliest" tagged
+releases.
+
+You could just visually inspect the commits since e05db0fd:
+
+-------------------------------------------------
+$ gitk e05db0fd..
+-------------------------------------------------
+
+or you can use linkgit:git-name-rev[1], which will give the commit a
+name based on any tag it finds pointing to one of the commit's
+descendants:
+
+-------------------------------------------------
+$ git name-rev --tags e05db0fd
+e05db0fd tags/v1.5.0-rc1^0~23
+-------------------------------------------------
+
+The linkgit:git-describe[1] command does the opposite, naming the
+revision using a tag on which the given commit is based:
+
+-------------------------------------------------
+$ git describe e05db0fd
+v1.5.0-rc0-260-ge05db0f
+-------------------------------------------------
+
+but that may sometimes help you guess which tags might come after the
+given commit.
+
+If you just want to verify whether a given tagged version contains a
+given commit, you could use linkgit:git-merge-base[1]:
+
+-------------------------------------------------
+$ git merge-base e05db0fd v1.5.0-rc1
+e05db0fd4f31dde7005f075a84f96b360d05984b
+-------------------------------------------------
+
+The merge-base command finds a common ancestor of the given commits,
+and always returns one or the other in the case where one is a
+descendant of the other; so the above output shows that e05db0fd
+actually is an ancestor of v1.5.0-rc1.
+
+Alternatively, note that
+
+-------------------------------------------------
+$ git log v1.5.0-rc1..e05db0fd
+-------------------------------------------------
+
+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 linkgit: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, if you 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 a line like
+
+-------------------------------------------------
++ ++ [e05db0fd] Fix warnings in sha1_file.c - use C99 printf format if
+available
+-------------------------------------------------
+
+shows that e05db0fd is reachable from itself, from v1.5.0-rc1,
+and from v1.5.0-rc2, and not from v1.5.0-rc0.
+
+[[showing-commits-unique-to-a-branch]]
+==== Showing commits unique to a given branch
+
+Suppose you would like to see all the commits reachable from the branch
+head named `master` but not from any other head in your repository.
+
+We can list all the heads in this repository with
+linkgit:git-show-ref[1]:
+
+-------------------------------------------------
+$ git show-ref --heads
+bf62196b5e363d73353a9dcf094c59595f3153b7 refs/heads/core-tutorial
+db768d5504c1bb46f63ee9d6e1772bd047e05bf9 refs/heads/maint
+a07157ac624b2524a059a3414e99f6f44bebc1e7 refs/heads/master
+24dbc180ea14dc1aebe09f14c8ecf32010690627 refs/heads/tutorial-2
+1e87486ae06626c2f31eaa63d26fc0fd646c8af2 refs/heads/tutorial-fixes
+-------------------------------------------------
+
+We can get just the branch-head names, and remove `master`, with
+the help of the standard utilities cut and grep:
+
+-------------------------------------------------
+$ git show-ref --heads | cut -d' ' -f2 | grep -v '^refs/heads/master'
+refs/heads/core-tutorial
+refs/heads/maint
+refs/heads/tutorial-2
+refs/heads/tutorial-fixes
+-------------------------------------------------
+
+And then we can ask to see all the commits reachable from master
+but not from these other heads:
+
+-------------------------------------------------
+$ gitk master --not $( git show-ref --heads | cut -d' ' -f2 |
+ grep -v '^refs/heads/master' )
+-------------------------------------------------
+
+Obviously, endless variations are possible; for example, to see all
+commits reachable from some head but not from any tag in the repository:
+
+-------------------------------------------------
+$ gitk $( git show-ref --heads ) --not $( git show-ref --tags )
+-------------------------------------------------
+
+(See linkgit:gitrevisions[7] for explanations of commit-selecting
+syntax such as `--not`.)
+
+[[making-a-release]]
+==== Creating a changelog and tarball for a software release
+
+The linkgit:git-archive[1] command can create a tar or zip archive from
+any version of a project; for example:
+
+-------------------------------------------------
+$ git archive -o latest.tar.gz --prefix=project/ HEAD
+-------------------------------------------------
+
+will use HEAD to produce a gzipped tar archive in which each filename
+is preceded by `project/`. The output file format is inferred from
+the output file extension if possible, see linkgit:git-archive[1] for
+details.
+
+Versions of Git older than 1.7.7 don't know about the `tar.gz` format,
+you'll need to use gzip explicitly:
+
+-------------------------------------------------
+$ git archive --format=tar --prefix=project/ HEAD | gzip >latest.tar.gz
+-------------------------------------------------
+
+If you're releasing a new version of a software project, you may want
+to simultaneously make a changelog to include in the release
+announcement.
+
+Linus Torvalds, for example, makes new kernel releases by tagging them,
+then running:
+
+-------------------------------------------------
+$ release-script 2.6.12 2.6.13-rc6 2.6.13-rc7
+-------------------------------------------------
+
+where release-script is a shell script that looks like:
+
+-------------------------------------------------
+#!/bin/sh
+stable="$1"
+last="$2"
+new="$3"
+echo "# git tag v$new"
+echo "git archive --prefix=linux-$new/ v$new | gzip -9 > ../linux-$new.tar.gz"
+echo "git diff v$stable v$new | gzip -9 > ../patch-$new.gz"
+echo "git log --no-merges v$new ^v$last > ../ChangeLog-$new"
+echo "git shortlog --no-merges v$new ^v$last > ../ShortLog"
+echo "git diff --stat --summary -M v$last v$new > ../diffstat-$new"
+-------------------------------------------------
+
+and then he just cut-and-pastes the output commands after verifying that
+they look OK.
+
+[[Finding-commits-With-given-Content]]
+==== Finding commits referencing a file with given content
+
+Somebody hands you a copy of a file, and asks which commits modified a
+file such that it contained the given content either before or after the
+commit. You can find out with this:
+
+-------------------------------------------------
+$ git log --raw --abbrev=40 --pretty=oneline |
+ grep -B 1 `git hash-object filename`
+-------------------------------------------------
+
+Figuring out why this works is left as an exercise to the (advanced)
+student. The linkgit:git-log[1], linkgit:git-diff-tree[1], and
+linkgit:git-hash-object[1] man pages may prove helpful.
+
+[[Developing-With-git]]
+== Developing with Git
+
+[[telling-git-your-name]]
+=== Telling Git your name
+
+Before creating any commits, you should introduce yourself to Git.
+The easiest way to do so is to use linkgit:git-config[1]:
+
+------------------------------------------------
+$ git config --global user.name 'Your Name Comes Here'
+$ git config --global user.email 'you@yourdomain.example.com'
+------------------------------------------------
+
+Which will add the following to a file named `.gitconfig` in your
+home directory:
+
+------------------------------------------------
+[user]
+ name = Your Name Comes Here
+ email = you@yourdomain.example.com
+------------------------------------------------
+
+See the "CONFIGURATION FILE" section of linkgit:git-config[1] for
+details on the configuration file. The file is plain text, so you can
+also edit it with your favorite editor.
+
+
+[[creating-a-new-repository]]
+=== Creating a new repository
+
+Creating a new repository from scratch is very easy:
+
+-------------------------------------------------
+$ mkdir project
+$ cd project
+$ git init
+-------------------------------------------------
+
+If you have some initial content (say, a tarball):
+
+-------------------------------------------------
+$ tar xzvf project.tar.gz
+$ cd project
+$ git init
+$ git add . # include everything below ./ in the first commit:
+$ git commit
+-------------------------------------------------
+
+[[how-to-make-a-commit]]
+=== How to make a commit
+
+Creating a new commit takes three steps:
+
+ 1. Making some changes to the working directory using your
+ favorite editor.
+ 2. Telling Git about your changes.
+ 3. Creating the commit using the content you told Git about
+ in step 2.
+
+In practice, you can interleave and repeat steps 1 and 2 as many
+times as you want: in order to keep track of what you want committed
+at step 3, Git maintains a snapshot of the tree's contents in a
+special staging area called "the index."
+
+At the beginning, the content of the index will be identical to
+that of the HEAD. The command `git diff --cached`, which shows
+the difference between the HEAD and the index, should therefore
+produce no output at that point.
+
+Modifying the index is easy:
+
+To update the index with the contents of a new or modified file, use
+
+-------------------------------------------------
+$ git add path/to/file
+-------------------------------------------------
+
+To remove a file from the index and from the working tree, use
+
+-------------------------------------------------
+$ git rm path/to/file
+-------------------------------------------------
+
+After each step you can verify that
+
+-------------------------------------------------
+$ git diff --cached
+-------------------------------------------------
+
+always shows the difference between the HEAD and the index file--this
+is what you'd commit if you created the commit now--and that
+
+-------------------------------------------------
+$ git diff
+-------------------------------------------------
+
+shows the difference between the working tree and the index file.
+
+Note that `git add` always adds just the current contents of a file
+to the index; further changes to the same file will be ignored unless
+you run `git add` on the file again.
+
+When you're ready, just run
+
+-------------------------------------------------
+$ git commit
+-------------------------------------------------
+
+and Git will prompt you for a commit message and then create the new
+commit. Check to make sure it looks like what you expected with
+
+-------------------------------------------------
+$ git show
+-------------------------------------------------
+
+As a special shortcut,
+
+-------------------------------------------------
+$ git commit -a
+-------------------------------------------------
+
+will update the index with any files that you've modified or removed
+and create a commit, all in one step.
+
+A number of commands are useful for keeping track of what you're
+about to commit:
+
+-------------------------------------------------
+$ git diff --cached # difference between HEAD and the index; what
+ # would be committed if you ran "commit" now.
+$ git diff # difference between the index file and your
+ # working directory; changes that would not
+ # be included if you ran "commit" now.
+$ git diff HEAD # difference between HEAD and working tree; what
+ # would be committed if you ran "commit -a" now.
+$ git status # a brief per-file summary of the above.
+-------------------------------------------------
+
+You can also use linkgit:git-gui[1] to create commits, view changes in
+the index and the working tree files, and individually select diff hunks
+for inclusion in the index (by right-clicking on the diff hunk and
+choosing "Stage Hunk For Commit").
+
+[[creating-good-commit-messages]]
+=== Creating good commit messages
+
+Though not required, it's a good idea to begin the commit message
+with a single short (no more than 50 characters) line summarizing the
+change, followed by a blank line and then a more thorough
+description. The text up to the first blank line in a commit
+message is treated as the commit title, and that title is used
+throughout Git. For example, linkgit:git-format-patch[1] turns a
+commit into email, and it uses the title on the Subject line and the
+rest of the commit in the body.
+
+
+[[ignoring-files]]
+=== Ignoring files
+
+A project will often generate files that you do 'not' want to track with Git.
+This typically includes files generated by a build process or temporary
+backup files made by your editor. Of course, 'not' tracking files with Git
+is just a matter of 'not' calling `git add` on them. But it quickly becomes
+annoying to have these untracked files lying around; e.g. they make
+`git add .` practically useless, and they keep showing up in the output of
+`git status`.
+
+You can tell Git to ignore certain files by creating a file called
+`.gitignore` in the top level of your working directory, with contents
+such as:
+
+-------------------------------------------------
+# Lines starting with '#' are considered comments.
+# Ignore any file named foo.txt.
+foo.txt
+# Ignore (generated) html files,
+*.html
+# except foo.html which is maintained by hand.
+!foo.html
+# Ignore objects and archives.
+*.[oa]
+-------------------------------------------------
+
+See linkgit:gitignore[5] for a detailed explanation of the syntax. You can
+also place .gitignore files in other directories in your working tree, and they
+will apply to those directories and their subdirectories. The `.gitignore`
+files can be added to your repository like any other files (just run `git add
+.gitignore` and `git commit`, as usual), which is convenient when the exclude
+patterns (such as patterns matching build output files) would also make sense
+for other users who clone your repository.
+
+If you wish the exclude patterns to affect only certain repositories
+(instead of every repository for a given project), you may instead put
+them in a file in your repository named `.git/info/exclude`, or in any
+file specified by the `core.excludesFile` configuration variable.
+Some Git commands can also take exclude patterns directly on the
+command line. See linkgit:gitignore[5] for the details.
+
+[[how-to-merge]]
+=== How to merge
+
+You can rejoin two diverging branches of development using
+linkgit:git-merge[1]:
+
+-------------------------------------------------
+$ git merge branchname
+-------------------------------------------------
+
+merges the development in the branch `branchname` into the current
+branch.
+
+A merge is made by combining the changes made in `branchname` and the
+changes made up to the latest commit in your current branch since
+their histories forked. The work tree is overwritten by the result of
+the merge when this combining is done cleanly, or overwritten by a
+half-merged results when this combining results in conflicts.
+Therefore, if you have uncommitted changes touching the same files as
+the ones impacted by the merge, Git will refuse to proceed. Most of
+the time, you will want to commit your changes before you can merge,
+and if you don't, then linkgit:git-stash[1] can take these changes
+away while you're doing the merge, and reapply them afterwards.
+
+If the changes are independent enough, Git will automatically complete
+the merge and commit the result (or reuse an existing commit in case
+of <<fast-forwards,fast-forward>>, see below). On the other hand,
+if there are conflicts--for example, if the same file is
+modified in two different ways in the remote branch and the local
+branch--then you are warned; the output may look something like this:
+
+-------------------------------------------------
+$ 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.
+-------------------------------------------------
+
+Conflict markers are left in the problematic files, and after
+you resolve the conflicts manually, you can update the index
+with the contents and run Git commit, as you normally would when
+creating a new file.
+
+If you examine the resulting commit using gitk, you will see that it
+has two parents, one pointing to the top of the current branch, and
+one to the top of the other branch.
+
+[[resolving-a-merge]]
+=== Resolving a merge
+
+When a merge isn't resolved automatically, Git leaves the index and
+the working tree in a special state that gives you all the
+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, linkgit:git-commit[1] will
+fail:
+
+-------------------------------------------------
+$ git commit
+file.txt: needs merge
+-------------------------------------------------
+
+Also, linkgit: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:
+
+[[conflict-resolution]]
+==== 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 linkgit:git-diff[1] shows only
+the conflicts. It uses an unusual syntax:
+
+-------------------------------------------------
+$ git diff
+diff --cc file.txt
+index 802992c,2b60207..0000000
+--- a/file.txt
++++ b/file.txt
+@@@ -1,1 -1,1 +1,5 @@@
+++<<<<<<< HEAD:file.txt
+ +Hello world
+++=======
++ Goodbye
+++>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
+-------------------------------------------------
+
+Recall that the commit which will be committed after we resolve this
+conflict will have two parents instead of the usual one: one parent
+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.
+
+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.
+$ git show :3:file.txt # the version from MERGE_HEAD.
+-------------------------------------------------
+
+When you ask linkgit:git-diff[1] to show the conflicts, it runs a
+three-way diff between the conflicted merge results in the work tree with
+stages 2 and 3 to show only hunks whose contents come from both sides,
+mixed (in other words, when a hunk's merge results come only from stage 2,
+that part is not conflicting and is not shown. Same for stage 3).
+
+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 linkgit: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
+diff --cc file.txt
+index 802992c,2b60207..0000000
+--- a/file.txt
++++ b/file.txt
+@@@ -1,1 -1,1 +1,1 @@@
+- Hello world
+ -Goodbye
+++Goodbye world
+-------------------------------------------------
+
+This shows that our resolved version deleted "Hello world" from the
+first parent, deleted "Goodbye" from the second parent, and added
+"Goodbye world", which was previously absent from both.
+
+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.
+-------------------------------------------------
+
+When using the 'ort' merge strategy (the default), before updating the working
+tree with the result of the merge, Git writes a special ref named AUTO_MERGE
+reflecting the state of the tree it is about to write. Conflicted paths with
+textual conflicts that could not be automatically merged are written to this
+tree with conflict markers, just as in the working tree. AUTO_MERGE can thus be
+used with linkgit:git-diff[1] to show the changes you've made so far to resolve
+conflicts. Using the same example as above, after resolving the conflict we
+get:
+
+-------------------------------------------------
+$ git diff AUTO_MERGE
+diff --git a/file.txt b/file.txt
+index cd10406..8bf5ae7 100644
+--- a/file.txt
++++ b/file.txt
+@@ -1,5 +1 @@
+-<<<<<<< HEAD:file.txt
+-Hello world
+-=======
+-Goodbye
+->>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
++Goodbye world
+-------------------------------------------------
+
+Notice that the diff shows we deleted the conflict markers and both versions of
+the content line, and wrote "Goodbye world" instead.
+
+The linkgit:git-log[1] and linkgit:gitk[1] commands also provide special help
+for merges:
+
+-------------------------------------------------
+$ git log --merge
+$ gitk --merge
+-------------------------------------------------
+
+These will display all commits which exist only on HEAD or on
+MERGE_HEAD, and which touch an unmerged file.
+
+You may also use linkgit:git-mergetool[1], which lets you merge the
+unmerged files using external tools such as Emacs or kdiff3.
+
+Each time you resolve the conflicts in a file and update the index:
+
+-------------------------------------------------
+$ git add file.txt
+-------------------------------------------------
+
+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
+
+If you get stuck and decide to just give up and throw the whole mess
+away, you can always return to the pre-merge state with
+
+-------------------------------------------------
+$ git merge --abort
+-------------------------------------------------
+
+Or, if you've already committed the merge that you want to throw away,
+
+-------------------------------------------------
+$ git reset --hard ORIG_HEAD
+-------------------------------------------------
+
+However, this last command can be dangerous in some cases--never
+throw away a commit you have already committed if that commit may
+itself have been merged into another branch, as doing so may confuse
+further merges.
+
+[[fast-forwards]]
+=== Fast-forward merges
+
+There is one special case not mentioned above, which is treated
+differently. Normally, a merge results in a merge commit, with two
+parents, one pointing at each of the two lines of development that
+were merged.
+
+However, if the current branch is an ancestor of the other--so every commit
+present in the current branch is already contained in the other branch--then Git
+just performs a "fast-forward"; the head of the current branch is moved forward
+to point at the head of the merged-in branch, without any new commits being
+created.
+
+[[fixing-mistakes]]
+=== Fixing mistakes
+
+If you've messed up the working tree, but haven't yet committed your
+mistake, you can return the entire working tree to the last committed
+state with
+
+-------------------------------------------------
+$ git restore --staged --worktree :/
+-------------------------------------------------
+
+If you make a commit that you later wish you hadn't, there are two
+fundamentally different ways to fix the problem:
+
+ 1. You can create a new commit that undoes whatever was done
+ by the old commit. This is the correct thing if your
+ mistake has already been made public.
+
+ 2. You can go back and modify the old commit. You should
+ never do this if you have already made the history public;
+ Git does not normally expect the "history" of a project to
+ change, and cannot correctly perform repeated merges from
+ a branch that has had its history changed.
+
+[[reverting-a-commit]]
+==== Fixing a mistake with a new commit
+
+Creating a new commit that reverts an earlier change is very easy;
+just pass the linkgit:git-revert[1] command a reference to the bad
+commit; for example, to revert the most recent commit:
+
+-------------------------------------------------
+$ git revert HEAD
+-------------------------------------------------
+
+This will create a new commit which undoes the change in HEAD. You
+will be given a chance to edit the commit message for the new commit.
+
+You can also revert an earlier change, for example, the next-to-last:
+
+-------------------------------------------------
+$ git revert HEAD^
+-------------------------------------------------
+
+In this case Git will attempt to undo the old change while leaving
+intact any changes made since then. If more recent changes overlap
+with the changes to be reverted, then you will be asked to fix
+conflicts manually, just as in the case of <<resolving-a-merge,
+resolving a merge>>.
+
+[[fixing-a-mistake-by-rewriting-history]]
+==== Fixing a mistake by rewriting history
+
+If the problematic commit is the most recent commit, and you have not
+yet made that commit public, then you may just
+<<undoing-a-merge,destroy it using `git reset`>>.
+
+Alternatively, you
+can edit the working directory and update the index to fix your
+mistake, just as if you were going to <<how-to-make-a-commit,create a
+new commit>>, then run
+
+-------------------------------------------------
+$ git commit --amend
+-------------------------------------------------
+
+which will replace the old commit by a new commit incorporating your
+changes, giving you a chance to edit the old commit message first.
+
+Again, you should never do this to a commit that may already have
+been merged into another branch; use linkgit:git-revert[1] instead in
+that case.
+
+It is also possible to replace commits further back in the history, but
+this is an advanced topic to be left for
+<<cleaning-up-history,another chapter>>.
+
+[[checkout-of-path]]
+==== Checking out an old version of a file
+
+In the process of undoing a previous bad change, you may find it
+useful to check out an older version of a particular file using
+linkgit:git-restore[1]. The command
+
+-------------------------------------------------
+$ git restore --source=HEAD^ path/to/file
+-------------------------------------------------
+
+replaces path/to/file by the contents it had in the commit HEAD^, and
+also updates the index to match. It does not change branches.
+
+If you just want to look at an old version of the file, without
+modifying the working directory, you can do that with
+linkgit:git-show[1]:
+
+-------------------------------------------------
+$ git show HEAD^:path/to/file
+-------------------------------------------------
+
+which will display the given version of the file.
+
+[[interrupted-work]]
+==== Temporarily setting aside work in progress
+
+While you are in the middle of working on something complicated, you
+find an unrelated but obvious and trivial bug. You would like to fix it
+before continuing. You can use linkgit:git-stash[1] to save the current
+state of your work, and after fixing the bug (or, optionally after doing
+so on a different branch and then coming back), unstash the
+work-in-progress changes.
+
+------------------------------------------------
+$ git stash push -m "work in progress for foo feature"
+------------------------------------------------
+
+This command will save your changes away to the `stash`, and
+reset your working tree and the index to match the tip of your
+current branch. Then you can make your fix as usual.
+
+------------------------------------------------
+... edit and test ...
+$ git commit -a -m "blorpl: typofix"
+------------------------------------------------
+
+After that, you can go back to what you were working on with
+`git stash pop`:
+
+------------------------------------------------
+$ git stash pop
+------------------------------------------------
+
+
+[[ensuring-good-performance]]
+=== Ensuring good performance
+
+On large repositories, Git depends on compression to keep the history
+information from taking up too much space on disk or in memory. Some
+Git commands may automatically run linkgit:git-gc[1], so you don't
+have to worry about running it manually. However, compressing a large
+repository may take a while, so you may want to call `gc` explicitly
+to avoid automatic compression kicking in when it is not convenient.
+
+
+[[ensuring-reliability]]
+=== Ensuring reliability
+
+[[checking-for-corruption]]
+==== Checking the repository for corruption
+
+The linkgit:git-fsck[1] command runs a number of self-consistency checks
+on the repository, and reports on any problems. This may take some
+time.
+
+-------------------------------------------------
+$ git fsck
+dangling commit 7281251ddd2a61e38657c827739c57015671a6b3
+dangling commit 2706a059f258c6b245f298dc4ff2ccd30ec21a63
+dangling commit 13472b7c4b80851a1bc551779171dcb03655e9b5
+dangling blob 218761f9d90712d37a9c5e36f406f92202db07eb
+dangling commit bf093535a34a4d35731aa2bd90fe6b176302f14f
+dangling commit 8e4bec7f2ddaa268bef999853c25755452100f8e
+dangling tree d50bb86186bf27b681d25af89d3b5b68382e4085
+dangling tree b24c2473f1fd3d91352a624795be026d64c8841f
+...
+-------------------------------------------------
+
+You will see informational messages on dangling objects. They are objects
+that still exist in the repository but are no longer referenced by any of
+your branches, and can (and will) be removed after a while with `gc`.
+You can run `git fsck --no-dangling` to suppress these messages, and still
+view real errors.
+
+[[recovering-lost-changes]]
+==== Recovering lost changes
+
+[[reflogs]]
+===== Reflogs
+
+Say you modify a branch with <<fixing-mistakes,`git reset --hard`>>,
+and then realize that the branch was the only reference you had to
+that point in history.
+
+Fortunately, Git also keeps a log, called a "reflog", of all the
+previous values of each branch. So in this case you can still find the
+old history using, for example,
+
+-------------------------------------------------
+$ git log master@{1}
+-------------------------------------------------
+
+This lists the commits reachable from the previous version of the
+`master` branch head. This syntax can be used with any Git command
+that accepts a commit, not just with `git log`. Some other examples:
+
+-------------------------------------------------
+$ git show master@{2} # See where the branch pointed 2,
+$ git show master@{3} # 3, ... changes ago.
+$ gitk master@{yesterday} # See where it pointed yesterday,
+$ gitk master@{"1 week ago"} # ... or last week
+$ git log --walk-reflogs master # show reflog entries for master
+-------------------------------------------------
+
+A separate reflog is kept for the HEAD, so
+
+-------------------------------------------------
+$ git show HEAD@{"1 week ago"}
+-------------------------------------------------
+
+will show what HEAD pointed to one week ago, not what the current branch
+pointed to one week ago. This allows you to see the history of what
+you've checked out.
+
+The reflogs are kept by default for 30 days, after which they may be
+pruned. See linkgit:git-reflog[1] and linkgit:git-gc[1] to learn
+how to control this pruning, and see the "SPECIFYING REVISIONS"
+section of linkgit:gitrevisions[7] for details.
+
+Note that the reflog history is very different from normal Git history.
+While normal history is shared by every repository that works on the
+same project, the reflog history is not shared: it tells you only about
+how the branches in your local repository have changed over time.
+
+[[dangling-object-recovery]]
+===== Examining dangling objects
+
+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
+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 in the dangling objects that `git fsck` reports. See
+<<dangling-objects>> for the details.
+
+-------------------------------------------------
+$ git fsck
+dangling commit 7281251ddd2a61e38657c827739c57015671a6b3
+dangling commit 2706a059f258c6b245f298dc4ff2ccd30ec21a63
+dangling commit 13472b7c4b80851a1bc551779171dcb03655e9b5
+...
+-------------------------------------------------
+
+You can examine
+one of those dangling commits with, for example,
+
+------------------------------------------------
+$ gitk 7281251ddd --not --all
+------------------------------------------------
+
+which does what it sounds like: it says that you want to see the commit
+history that is described by the dangling commit(s), but not the
+history that is described by all your existing branches and tags. Thus
+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 dropped.)
+
+If you decide you want the history back, you can always create a new
+reference pointing to it, for example, a new branch:
+
+------------------------------------------------
+$ git branch recovered-branch 7281251ddd
+------------------------------------------------
+
+Other types of dangling objects (blobs and trees) are also possible, and
+dangling objects can arise in other situations.
+
+
+[[sharing-development]]
+== Sharing development with others
+
+[[getting-updates-With-git-pull]]
+=== Getting updates with git pull
+
+After you clone a repository and commit a few changes of your own, you
+may wish to check the original repository for updates and merge them
+into your own work.
+
+We have already seen <<Updating-a-repository-With-git-fetch,how to
+keep remote-tracking branches up to date>> with linkgit:git-fetch[1],
+and how to merge two branches. So you can merge in changes from the
+original repository's master branch with:
+
+-------------------------------------------------
+$ git fetch
+$ git merge origin/master
+-------------------------------------------------
+
+However, the linkgit:git-pull[1] command provides a way to do this in
+one step:
+
+-------------------------------------------------
+$ git pull origin master
+-------------------------------------------------
+
+In fact, if you have `master` checked out, then this branch has been
+configured by `git clone` to get changes from the HEAD branch of the
+origin repository. So often you can
+accomplish the above with just a simple
+
+-------------------------------------------------
+$ git pull
+-------------------------------------------------
+
+This command will fetch changes from the remote branches to your
+remote-tracking branches `origin/*`, and merge the default branch into
+the current branch.
+
+More generally, a branch that is created from a remote-tracking branch
+will pull
+by default from that branch. See the descriptions of the
+`branch.<name>.remote` and `branch.<name>.merge` options in
+linkgit:git-config[1], and the discussion of the `--track` option in
+linkgit:git-checkout[1], to learn how to control these defaults.
+
+In addition to saving you keystrokes, `git pull` also helps you by
+producing a default commit message documenting the branch and
+repository that you pulled from.
+
+(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.)
+
+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
+the commands
+
+-------------------------------------------------
+$ git pull . branch
+$ git merge branch
+-------------------------------------------------
+
+are roughly equivalent.
+
+[[submitting-patches]]
+=== Submitting patches to a project
+
+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 linkgit:git-format-patch[1]; for example:
+
+-------------------------------------------------
+$ git format-patch origin
+-------------------------------------------------
+
+will produce a numbered series of files in the current directory, one
+for each patch in the current branch but not in `origin/HEAD`.
+
+`git format-patch` can include an initial "cover letter". You can insert
+commentary on individual patches after the three dash line which
+`format-patch` places after the commit message but before the patch
+itself. If you use `git notes` to track your cover letter material,
+`git format-patch --notes` will include the commit's notes in a similar
+manner.
+
+You can then import these into your mail client and send them by
+hand. However, if you have a lot to send at once, you may prefer to
+use the linkgit:git-send-email[1] script to automate the process.
+Consult the mailing list for your project first to determine
+their requirements for submitting patches.
+
+[[importing-patches]]
+=== Importing patches to a project
+
+Git also provides a tool called linkgit:git-am[1] (am stands for
+"apply mailbox"), for importing such an emailed series of patches.
+Just save all of the patch-containing messages, in order, into a
+single mailbox file, say `patches.mbox`, then run
+
+-------------------------------------------------
+$ git am -3 patches.mbox
+-------------------------------------------------
+
+Git will apply each patch in order; if any conflicts are found, it
+will stop, and you can fix the conflicts as described in
+"<<resolving-a-merge,Resolving a merge>>". (The `-3` option tells
+Git to perform a merge; if you would prefer it just to abort and
+leave your tree and index untouched, you may omit that option.)
+
+Once the index is updated with the results of the conflict
+resolution, instead of creating a new commit, just run
+
+-------------------------------------------------
+$ git am --continue
+-------------------------------------------------
+
+and Git will create the commit for you and continue applying the
+remaining patches from the mailbox.
+
+The final result will be a series of commits, one for each patch in
+the original mailbox, with authorship and commit log message each
+taken from the message containing each patch.
+
+[[public-repositories]]
+=== Public Git repositories
+
+Another way to submit changes to a project is to tell the maintainer
+of that project to pull the changes from your repository using
+linkgit:git-pull[1]. In the section "<<getting-updates-With-git-pull,
+Getting updates with `git pull`>>" we described this as a way to get
+updates from the "main" repository, but it works just as well in the
+other direction.
+
+If you and the maintainer both have accounts on the same machine, then
+you can just pull changes from each other's repositories directly;
+commands that accept repository URLs as arguments will also accept a
+local directory name:
+
+-------------------------------------------------
+$ git clone /path/to/repository
+$ git pull /path/to/other/repository
+-------------------------------------------------
+
+or an ssh URL:
+
+-------------------------------------------------
+$ git clone ssh://yourhost/~you/repository
+-------------------------------------------------
+
+For projects with few developers, or for synchronizing a few private
+repositories, this may be all you need.
+
+However, the more common way to do this is to maintain a separate public
+repository (usually on a different host) for others to pull changes
+from. This is usually more convenient, and allows you to cleanly
+separate private work in progress from publicly visible work.
+
+You will continue to do your day-to-day work in your personal
+repository, but periodically "push" changes from your personal
+repository into your public repository, allowing other developers to
+pull from that repository. So the flow of changes, in a situation
+where there is one other developer with a public repository, looks
+like this:
+
+....
+ you push
+your personal repo ------------------> your public repo
+ ^ |
+ | |
+ | you pull | they pull
+ | |
+ | |
+ | they push V
+their public repo <------------------- their repo
+....
+
+We explain how to do this in the following sections.
+
+[[setting-up-a-public-repository]]
+==== Setting up a public repository
+
+Assume your personal repository is in the directory `~/proj`. We
+first create a new clone of the repository and tell `git daemon` that it
+is meant to be public:
+
+-------------------------------------------------
+$ git clone --bare ~/proj proj.git
+$ touch proj.git/git-daemon-export-ok
+-------------------------------------------------
+
+The resulting directory proj.git contains a "bare" git repository--it is
+just the contents of the `.git` directory, without any files checked out
+around it.
+
+Next, copy `proj.git` to the server where you plan to host the
+public repository. You can use scp, rsync, or whatever is most
+convenient.
+
+[[exporting-via-git]]
+==== Exporting a Git repository via the Git protocol
+
+This is the preferred method.
+
+If someone else administers the server, they should tell you what
+directory to put the repository in, and what `git://` URL it will
+appear at. You can then skip to the section
+"<<pushing-changes-to-a-public-repository,Pushing changes to a public
+repository>>", below.
+
+Otherwise, all you need to do is start linkgit:git-daemon[1]; it will
+listen on port 9418. By default, it will allow access to any directory
+that looks like a Git directory and contains the magic file
+git-daemon-export-ok. Passing some directory paths as `git daemon`
+arguments will further restrict the exports to those paths.
+
+You can also run `git daemon` as an inetd service; see the
+linkgit:git-daemon[1] man page for details. (See especially the
+examples section.)
+
+[[exporting-via-http]]
+==== Exporting a git repository via HTTP
+
+The Git protocol gives better performance and reliability, but on a
+host with a web server set up, HTTP exports may be simpler to set up.
+
+All you need to do is place the newly created bare Git repository in
+a directory that is exported by the web server, and make some
+adjustments to give web clients some extra information they need:
+
+-------------------------------------------------
+$ mv proj.git /home/you/public_html/proj.git
+$ cd proj.git
+$ git --bare update-server-info
+$ mv hooks/post-update.sample hooks/post-update
+-------------------------------------------------
+
+(For an explanation of the last two lines, see
+linkgit:git-update-server-info[1] and linkgit:githooks[5].)
+
+Advertise the URL of `proj.git`. Anybody else should then be able to
+clone or pull from that URL, for example with a command line like:
+
+-------------------------------------------------
+$ git clone http://yourserver.com/~you/proj.git
+-------------------------------------------------
+
+(See also
+link:howto/setup-git-server-over-http.html[setup-git-server-over-http]
+for a slightly more sophisticated setup using WebDAV which also
+allows pushing over HTTP.)
+
+[[pushing-changes-to-a-public-repository]]
+==== Pushing changes to a public repository
+
+Note that the two techniques outlined above (exporting via
+<<exporting-via-http,http>> or <<exporting-via-git,git>>) allow other
+maintainers to fetch your latest changes, but they do not allow write
+access, which you will need to update the public repository with the
+latest changes created in your private repository.
+
+The simplest way to do this is using linkgit:git-push[1] and ssh; to
+update the remote branch named `master` with the latest state of your
+branch named `master`, run
+
+-------------------------------------------------
+$ git push ssh://yourserver.com/~you/proj.git master:master
+-------------------------------------------------
+
+or just
+
+-------------------------------------------------
+$ git push ssh://yourserver.com/~you/proj.git master
+-------------------------------------------------
+
+As with `git fetch`, `git push` will complain if this does not result in a
+<<fast-forwards,fast-forward>>; see the following section for details on
+handling this case.
+
+Note that the target of a `push` is normally a
+<<def_bare_repository,bare>> repository. You can also push to a
+repository that has a checked-out working tree, but a push to update the
+currently checked-out branch is denied by default to prevent confusion.
+See the description of the receive.denyCurrentBranch option
+in linkgit:git-config[1] for details.
+
+As with `git fetch`, you may also set up configuration options to
+save typing; so, for example:
+
+-------------------------------------------------
+$ git remote add public-repo ssh://yourserver.com/~you/proj.git
+-------------------------------------------------
+
+adds the following to `.git/config`:
+
+-------------------------------------------------
+[remote "public-repo"]
+ url = yourserver.com:proj.git
+ fetch = +refs/heads/*:refs/remotes/example/*
+-------------------------------------------------
+
+which lets you do the same push with just
+
+-------------------------------------------------
+$ git push public-repo master
+-------------------------------------------------
+
+See the explanations of the `remote.<name>.url`,
+`branch.<name>.remote`, and `remote.<name>.push` options in
+linkgit:git-config[1] for details.
+
+[[forcing-push]]
+==== What to do when a push fails
+
+If a push would not result in a <<fast-forwards,fast-forward>> of the
+remote branch, then it will fail with an error like:
+
+-------------------------------------------------
+ ! [rejected] master -> master (non-fast-forward)
+error: failed to push some refs to '...'
+hint: Updates were rejected because the tip of your current branch is behind
+hint: its remote counterpart. Integrate the remote changes (e.g.
+hint: 'git pull ...') before pushing again.
+hint: See the 'Note about fast-forwards' in 'git push --help' for details.
+-------------------------------------------------
+
+This can happen, for example, if you:
+
+ - use `git reset --hard` to remove already-published commits, or
+ - use `git commit --amend` to replace already-published commits
+ (as in <<fixing-a-mistake-by-rewriting-history>>), or
+ - use `git rebase` to rebase any already-published commits (as
+ in <<using-git-rebase>>).
+
+You may force `git push` to perform the update anyway by preceding the
+branch name with a plus sign:
+
+-------------------------------------------------
+$ git push ssh://yourserver.com/~you/proj.git +master
+-------------------------------------------------
+
+Note the addition of the `+` sign. Alternatively, you can use the
+`-f` flag to force the remote update, as in:
+
+-------------------------------------------------
+$ git push -f ssh://yourserver.com/~you/proj.git master
+-------------------------------------------------
+
+Normally whenever a branch head in a public repository is modified, it
+is modified to point to a descendant of the commit that it pointed to
+before. By forcing a push in this situation, you break that convention.
+(See <<problems-With-rewriting-history>>.)
+
+Nevertheless, this is a common practice for people that need a simple
+way to publish a work-in-progress patch series, and it is an acceptable
+compromise as long as you warn other developers that this is how you
+intend to manage the branch.
+
+It's also possible for a push to fail in this way when other people have
+the right to push to the same repository. In that case, the correct
+solution is to retry the push after first updating your work: either by a
+pull, or by a fetch followed by a rebase; see the
+<<setting-up-a-shared-repository,next section>> and
+linkgit:gitcvs-migration[7] for more.
+
+[[setting-up-a-shared-repository]]
+==== Setting up a shared repository
+
+Another way to collaborate is by using a model similar to that
+commonly used in CVS, where several developers with special rights
+all push to and pull from a single shared repository. See
+linkgit:gitcvs-migration[7] for instructions on how to
+set this up.
+
+However, while there is nothing wrong with Git's support for shared
+repositories, this mode of operation is not generally recommended,
+simply because the mode of collaboration that Git supports--by
+exchanging patches and pulling from public repositories--has so many
+advantages over the central shared repository:
+
+ - Git's ability to quickly import and merge patches allows a
+ single maintainer to process incoming changes even at very
+ high rates. And when that becomes too much, `git pull` provides
+ an easy way for that maintainer to delegate this job to other
+ maintainers while still allowing optional review of incoming
+ changes.
+ - Since every developer's repository has the same complete copy
+ of the project history, no repository is special, and it is
+ trivial for another developer to take over maintenance of a
+ project, either by mutual agreement, or because a maintainer
+ becomes unresponsive or difficult to work with.
+ - The lack of a central group of "committers" means there is
+ less need for formal decisions about who is "in" and who is
+ "out".
+
+[[setting-up-gitweb]]
+==== Allowing web browsing of a repository
+
+The gitweb cgi script provides users an easy way to browse your
+project's revisions, file contents and logs without having to install
+Git. Features like RSS/Atom feeds and blame/annotation details may
+optionally be enabled.
+
+The linkgit:git-instaweb[1] command provides a simple way to start
+browsing the repository using gitweb. The default server when using
+instaweb is lighttpd.
+
+See the file gitweb/INSTALL in the Git source tree and
+linkgit:gitweb[1] for instructions on details setting up a permanent
+installation with a CGI or Perl capable server.
+
+[[how-to-get-a-git-repository-with-minimal-history]]
+=== How to get a Git repository with minimal history
+
+A <<def_shallow_clone,shallow clone>>, with its truncated
+history, is useful when one is interested only in recent history
+of a project and getting full history from the upstream is
+expensive.
+
+A <<def_shallow_clone,shallow clone>> is created by specifying
+the linkgit:git-clone[1] `--depth` switch. The depth can later be
+changed with the linkgit:git-fetch[1] `--depth` switch, or full
+history restored with `--unshallow`.
+
+Merging inside a <<def_shallow_clone,shallow clone>> will work as long
+as a merge base is in the recent history.
+Otherwise, it will be like merging unrelated histories and may
+have to result in huge conflicts. This limitation may make such
+a repository unsuitable to be used in merge based workflows.
+
+[[sharing-development-examples]]
+=== Examples
+
+[[maintaining-topic-branches]]
+==== Maintaining topic branches for a Linux subsystem maintainer
+
+This describes how Tony Luck uses Git in his role as maintainer of the
+IA64 architecture for the Linux kernel.
+
+He uses two public branches:
+
+ - A "test" tree into which patches are initially placed so that they
+ can get some exposure when integrated with other ongoing development.
+ This tree is available to Andrew for pulling into -mm whenever he
+ wants.
+
+ - A "release" tree into which tested patches are moved for final sanity
+ checking, and as a vehicle to send them upstream to Linus (by sending
+ him a "please pull" request.)
+
+He also uses a set of temporary branches ("topic branches"), each
+containing a logical grouping of patches.
+
+To set this up, first create your work tree by cloning Linus's public
+tree:
+
+-------------------------------------------------
+$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git work
+$ cd work
+-------------------------------------------------
+
+Linus's tree will be stored in the remote-tracking branch named origin/master,
+and can be updated using linkgit:git-fetch[1]; you can track other
+public trees using linkgit:git-remote[1] to set up a "remote" and
+linkgit:git-fetch[1] to keep them up to date; see
+<<repositories-and-branches>>.
+
+Now create the branches in which you are going to work; these start out
+at the current tip of origin/master branch, and should be set up (using
+the `--track` option to linkgit:git-branch[1]) to merge changes in from
+Linus by default.
+
+-------------------------------------------------
+$ git branch --track test origin/master
+$ git branch --track release origin/master
+-------------------------------------------------
+
+These can be easily kept up to date using linkgit:git-pull[1].
+
+-------------------------------------------------
+$ git switch test && git pull
+$ git switch release && git pull
+-------------------------------------------------
+
+Important note! If you have any local changes in these branches, then
+this merge will create a commit object in the history (with no local
+changes Git will simply do a "fast-forward" merge). Many people dislike
+the "noise" that this creates in the Linux history, so you should avoid
+doing this capriciously in the `release` branch, as these noisy commits
+will become part of the permanent history when you ask Linus to pull
+from the release branch.
+
+A few configuration variables (see linkgit:git-config[1]) can
+make it easy to push both branches to your public tree. (See
+<<setting-up-a-public-repository>>.)
+
+-------------------------------------------------
+$ cat >> .git/config <<EOF
+[remote "mytree"]
+ url = master.kernel.org:/pub/scm/linux/kernel/git/aegl/linux.git
+ push = release
+ push = test
+EOF
+-------------------------------------------------
+
+Then you can push both the test and release trees using
+linkgit:git-push[1]:
+
+-------------------------------------------------
+$ git push mytree
+-------------------------------------------------
+
+or push just one of the test and release branches using:
+
+-------------------------------------------------
+$ git push mytree test
+-------------------------------------------------
+
+or
+
+-------------------------------------------------
+$ git push mytree release
+-------------------------------------------------
+
+Now to apply some patches from the community. Think of a short
+snappy name for a branch to hold this patch (or related group of
+patches), and create a new branch from a recent stable tag of
+Linus's branch. Picking a stable base for your branch will:
+1) help you: by avoiding inclusion of unrelated and perhaps lightly
+tested changes
+2) help future bug hunters that use `git bisect` to find problems
+
+-------------------------------------------------
+$ git switch -c speed-up-spinlocks v2.6.35
+-------------------------------------------------
+
+Now you apply the patch(es), run some tests, and commit the change(s). If
+the patch is a multi-part series, then you should apply each as a separate
+commit to this branch.
+
+-------------------------------------------------
+$ ... patch ... test ... commit [ ... patch ... test ... commit ]*
+-------------------------------------------------
+
+When you are happy with the state of this change, you can merge it into the
+"test" branch in preparation to make it public:
+
+-------------------------------------------------
+$ git switch test && git merge speed-up-spinlocks
+-------------------------------------------------
+
+It is unlikely that you would have any conflicts here ... but you might if you
+spent a while on this step and had also pulled new versions from upstream.
+
+Sometime later when enough time has passed and testing done, you can pull the
+same branch into the `release` tree ready to go upstream. This is where you
+see the value of keeping each patch (or patch series) in its own branch. It
+means that the patches can be moved into the `release` tree in any order.
+
+-------------------------------------------------
+$ git switch release && git merge speed-up-spinlocks
+-------------------------------------------------
+
+After a while, you will have a number of branches, and despite the
+well chosen names you picked for each of them, you may forget what
+they are for, or what status they are in. To get a reminder of what
+changes are in a specific branch, use:
+
+-------------------------------------------------
+$ git log linux..branchname | git shortlog
+-------------------------------------------------
+
+To see whether it has already been merged into the test or release branches,
+use:
+
+-------------------------------------------------
+$ git log test..branchname
+-------------------------------------------------
+
+or
+
+-------------------------------------------------
+$ git log release..branchname
+-------------------------------------------------
+
+(If this branch has not yet been merged, you will see some log entries.
+If it has been merged, then there will be no output.)
+
+Once a patch completes the great cycle (moving from test to release,
+then pulled by Linus, and finally coming back into your local
+`origin/master` branch), the branch for this change is no longer needed.
+You detect this when the output from:
+
+-------------------------------------------------
+$ git log origin..branchname
+-------------------------------------------------
+
+is empty. At this point the branch can be deleted:
+
+-------------------------------------------------
+$ git branch -d branchname
+-------------------------------------------------
+
+Some changes are so trivial that it is not necessary to create a separate
+branch and then merge into each of the test and release branches. For
+these changes, just apply directly to the `release` branch, and then
+merge that into the `test` branch.
+
+After pushing your work to `mytree`, you can use
+linkgit:git-request-pull[1] to prepare a "please pull" request message
+to send to Linus:
+
+-------------------------------------------------
+$ git push mytree
+$ git request-pull origin mytree release
+-------------------------------------------------
+
+Here are some of the scripts that simplify all this even further.
+
+-------------------------------------------------
+==== update script ====
+# Update a branch in my Git tree. If the branch to be updated
+# is origin, then pull from kernel.org. Otherwise merge
+# origin/master branch into test|release branch
+
+case "$1" in
+test|release)
+ git checkout $1 && git pull . origin
+ ;;
+origin)
+ before=$(git rev-parse refs/remotes/origin/master)
+ git fetch origin
+ after=$(git rev-parse refs/remotes/origin/master)
+ if [ $before != $after ]
+ then
+ git log $before..$after | git shortlog
+ fi
+ ;;
+*)
+ echo "usage: $0 origin|test|release" 1>&2
+ exit 1
+ ;;
+esac
+-------------------------------------------------
+
+-------------------------------------------------
+==== merge script ====
+# Merge a branch into either the test or release branch
+
+pname=$0
+
+usage()
+{
+ echo "usage: $pname branch test|release" 1>&2
+ exit 1
+}
+
+git show-ref -q --verify -- refs/heads/"$1" || {
+ echo "Can't see branch <$1>" 1>&2
+ usage
+}
+
+case "$2" in
+test|release)
+ if [ $(git log $2..$1 | wc -c) -eq 0 ]
+ then
+ echo $1 already merged into $2 1>&2
+ exit 1
+ fi
+ git checkout $2 && git pull . $1
+ ;;
+*)
+ usage
+ ;;
+esac
+-------------------------------------------------
+
+-------------------------------------------------
+==== status script ====
+# report on status of my ia64 Git tree
+
+gb=$(tput setab 2)
+rb=$(tput setab 1)
+restore=$(tput setab 9)
+
+if [ `git rev-list test..release | wc -c` -gt 0 ]
+then
+ echo $rb Warning: commits in release that are not in test $restore
+ git log test..release
+fi
+
+for branch in `git show-ref --heads | sed 's|^.*/||'`
+do
+ if [ $branch = test -o $branch = release ]
+ then
+ continue
+ fi
+
+ echo -n $gb ======= $branch ====== $restore " "
+ status=
+ for ref in test release origin/master
+ do
+ if [ `git rev-list $ref..$branch | wc -c` -gt 0 ]
+ then
+ status=$status${ref:0:1}
+ fi
+ done
+ case $status in
+ trl)
+ echo $rb Need to pull into test $restore
+ ;;
+ rl)
+ echo "In test"
+ ;;
+ l)
+ echo "Waiting for linus"
+ ;;
+ "")
+ echo $rb All done $restore
+ ;;
+ *)
+ echo $rb "<$status>" $restore
+ ;;
+ esac
+ git log origin/master..$branch | git shortlog
+done
+-------------------------------------------------
+
+
+[[cleaning-up-history]]
+== Rewriting history and maintaining patch series
+
+Normally commits are only added to a project, never taken away or
+replaced. Git is designed with this assumption, and violating it will
+cause Git's merge machinery (for example) to do the wrong thing.
+
+However, there is a situation in which it can be useful to violate this
+assumption.
+
+[[patch-series]]
+=== Creating the perfect patch series
+
+Suppose you are a contributor to a large project, and you want to add a
+complicated feature, and to present it to the other developers in a way
+that makes it easy for them to read your changes, verify that they are
+correct, and understand why you made each change.
+
+If you present all of your changes as a single patch (or commit), they
+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.
+
+So the ideal is usually to produce a series of patches such that:
+
+ 1. Each patch can be applied in order.
+
+ 2. Each patch includes a single logical change, together with a
+ message explaining the change.
+
+ 3. No patch introduces a regression: after applying any initial
+ part of the series, the resulting project still compiles and
+ works, and has no bugs that it didn't have before.
+
+ 4. The complete series produces the same end result as your own
+ (probably much messier!) development process did.
+
+We will introduce some tools that can help you do this, explain how to
+use them, and then explain some of the problems that can arise because
+you are rewriting history.
+
+[[using-git-rebase]]
+=== Keeping a patch series up to date using git rebase
+
+Suppose that you create a branch `mywork` on a remote-tracking branch
+`origin`, and create some commits on top of it:
+
+-------------------------------------------------
+$ git switch -c mywork origin
+$ vi file.txt
+$ git commit
+$ vi otherfile.txt
+$ git commit
+...
+-------------------------------------------------
+
+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
+ \
+ a--b--c <-- 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
+linkgit:git-rebase[1]:
+
+-------------------------------------------------
+$ git switch mywork
+$ git rebase origin
+-------------------------------------------------
+
+This will remove each of your commits from mywork, temporarily saving
+them as patches (in a directory named `.git/rebase-apply`), update mywork to
+point at the latest version of origin, then apply each of the saved
+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 add`
+to update the index with those contents, and then, instead of
+running `git commit`, just run
+
+-------------------------------------------------
+$ git rebase --continue
+-------------------------------------------------
+
+and Git will continue applying the rest of the patches.
+
+At any point you may use the `--abort` option to abort this process and
+return mywork to the state it had before you started the rebase:
+
+-------------------------------------------------
+$ git rebase --abort
+-------------------------------------------------
+
+If you need to reorder or edit a number of commits in a branch, it may
+be easier to use `git rebase -i`, which allows you to reorder and
+squash commits, as well as marking them for individual editing during
+the rebase. See <<interactive-rebase>> for details, and
+<<reordering-patch-series>> for alternatives.
+
+[[rewriting-one-commit]]
+=== Rewriting a single commit
+
+We saw in <<fixing-a-mistake-by-rewriting-history>> that you can replace the
+most recent commit using
+
+-------------------------------------------------
+$ git commit --amend
+-------------------------------------------------
+
+which will replace the old commit by a new commit incorporating your
+changes, giving you a chance to edit the old commit message first.
+This is useful for fixing typos in your last commit, or for adjusting
+the patch contents of a poorly staged commit.
+
+If you need to amend commits from deeper in your history, you can
+use <<interactive-rebase,interactive rebase's `edit` instruction>>.
+
+[[reordering-patch-series]]
+=== Reordering or selecting from a patch series
+
+Sometimes you want to edit a commit deeper in your history. One
+approach is to use `git format-patch` to create a series of patches
+and then reset the state to before the patches:
+
+-------------------------------------------------
+$ git format-patch origin
+$ git reset --hard origin
+-------------------------------------------------
+
+Then modify, reorder, or eliminate patches as needed before applying
+them again with linkgit:git-am[1]:
+
+-------------------------------------------------
+$ git am *.patch
+-------------------------------------------------
+
+[[interactive-rebase]]
+=== Using interactive rebases
+
+You can also edit a patch series with an interactive rebase. This is
+the same as <<reordering-patch-series,reordering a patch series using
+`format-patch`>>, so use whichever interface you like best.
+
+Rebase your current HEAD on the last commit you want to retain as-is.
+For example, if you want to reorder the last 5 commits, use:
+
+-------------------------------------------------
+$ git rebase -i HEAD~5
+-------------------------------------------------
+
+This will open your editor with a list of steps to be taken to perform
+your rebase.
+
+-------------------------------------------------
+pick deadbee The oneline of this commit
+pick fa1afe1 The oneline of the next commit
+...
+
+# Rebase c0ffeee..deadbee onto c0ffeee
+#
+# Commands:
+# p, pick = use commit
+# r, reword = use commit, but edit the commit message
+# e, edit = use commit, but stop for amending
+# s, squash = use commit, but meld into previous commit
+# f, fixup = like "squash", but discard this commit's log message
+# x, exec = run command (the rest of the line) using shell
+#
+# These lines can be re-ordered; they are executed from top to bottom.
+#
+# If you remove a line here THAT COMMIT WILL BE LOST.
+#
+# However, if you remove everything, the rebase will be aborted.
+#
+# Note that empty commits are commented out
+-------------------------------------------------
+
+As explained in the comments, you can reorder commits, squash them
+together, edit commit messages, etc. by editing the list. Once you
+are satisfied, save the list and close your editor, and the rebase
+will begin.
+
+The rebase will stop where `pick` has been replaced with `edit` or
+when a step in the list fails to mechanically resolve conflicts and
+needs your help. When you are done editing and/or resolving conflicts
+you can continue with `git rebase --continue`. If you decide that
+things are getting too hairy, you can always bail out with `git rebase
+--abort`. Even after the rebase is complete, you can still recover
+the original branch by using the <<reflogs,reflog>>.
+
+For a more detailed discussion of the procedure and additional tips,
+see the "INTERACTIVE MODE" section of linkgit:git-rebase[1].
+
+[[patch-series-tools]]
+=== Other tools
+
+There are numerous other tools, such as StGit, which exist for the
+purpose of maintaining a patch series. These are outside of the scope of
+this manual.
+
+[[problems-With-rewriting-history]]
+=== Problems with rewriting history
+
+The primary problem with rewriting the history of a branch has to do
+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
+two developers had independently done the work on the old and new heads
+in parallel. At this point, if someone attempts to merge the new head
+in to their branch, Git will attempt to merge together the two (old and
+new) lines of development, instead of trying to replace the old by the
+new. The results are likely to be unexpected.
+
+You may still choose to publish branches whose history is rewritten,
+and it may be useful for others to be able to fetch those branches in
+order to examine or test them, but they should not attempt to pull such
+branches into their own work.
+
+For true distributed development that supports proper merging,
+published branches should never be rewritten.
+
+[[bisect-merges]]
+=== Why bisecting merge commits can be harder than bisecting linear history
+
+The linkgit:git-bisect[1] command correctly handles history that
+includes merge commits. However, when the commit that it finds is a
+merge commit, the user may need to work harder than usual to figure out
+why that commit introduced a problem.
+
+Imagine this history:
+
+................................................
+ ---Z---o---X---...---o---A---C---D
+ \ /
+ o---o---Y---...---o---B
+................................................
+
+Suppose that on the upper line of development, the meaning of one
+of the functions that exists at Z is changed at commit X. The
+commits from Z leading to A change both the function's
+implementation and all calling sites that exist at Z, as well
+as new calling sites they add, to be consistent. There is no
+bug at A.
+
+Suppose that in the meantime on the lower line of development somebody
+adds a new calling site for that function at commit Y. The
+commits from Z leading to B all assume the old semantics of that
+function and the callers and the callee are consistent with each
+other. There is no bug at B, either.
+
+Suppose further that the two development lines merge cleanly at C,
+so no conflict resolution is required.
+
+Nevertheless, the code at C is broken, because the callers added
+on the lower line of development have not been converted to the new
+semantics introduced on the upper line of development. So if all
+you know is that D is bad, that Z is good, and that
+linkgit:git-bisect[1] identifies C as the culprit, how will you
+figure out that the problem is due to this change in semantics?
+
+When the result of a `git bisect` is a non-merge commit, you should
+normally be able to discover the problem by examining just that commit.
+Developers can make this easy by breaking their changes into small
+self-contained commits. That won't help in the case above, however,
+because the problem isn't obvious from examination of any single
+commit; instead, a global view of the development is required. To
+make matters worse, the change in semantics in the problematic
+function may be just one small part of the changes in the upper
+line of development.
+
+On the other hand, if instead of merging at C you had rebased the
+history between Z to B on top of A, you would have gotten this
+linear history:
+
+................................................................
+ ---Z---o---X--...---o---A---o---o---Y*--...---o---B*--D*
+................................................................
+
+Bisecting between Z and D* would hit a single culprit commit Y*,
+and understanding why Y* was broken would probably be easier.
+
+Partly for this reason, many experienced Git users, even when
+working on an otherwise merge-heavy project, keep the history
+linear by rebasing against the latest upstream version before
+publishing.
+
+[[advanced-branch-management]]
+== Advanced branch management
+
+[[fetching-individual-branches]]
+=== Fetching individual branches
+
+Instead of using linkgit:git-remote[1], you can also choose just
+to update one branch at a time, and to store it locally under an
+arbitrary name:
+
+-------------------------------------------------
+$ git fetch origin todo:my-todo-work
+-------------------------------------------------
+
+The first argument, `origin`, just tells Git to fetch from the
+repository you originally cloned from. The second argument tells Git
+to fetch the branch named `todo` from the remote repository, and to
+store it locally under the name `refs/heads/my-todo-work`.
+
+You can also fetch branches from other repositories; so
+
+-------------------------------------------------
+$ git fetch git://example.com/proj.git master:example-master
+-------------------------------------------------
+
+will create a new branch named `example-master` and store in it the
+branch named `master` from the repository at the given URL. If you
+already have a branch named example-master, it will attempt to
+<<fast-forwards,fast-forward>> to the commit given by example.com's
+master branch. In more detail:
+
+[[fetch-fast-forwards]]
+=== git fetch and fast-forwards
+
+In the previous example, when updating an existing branch, `git fetch`
+checks to make sure that the most recent commit on the remote
+branch is a descendant of the most recent commit on your copy of the
+branch before updating your copy of the branch to point at the new
+commit. Git calls this process a <<fast-forwards,fast-forward>>.
+
+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
+a descendant of the old head. For example, the developer may have
+realized a serious mistake was made 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.
+
+In that case, you can still force Git to update to the new head, as
+described in the following section. However, note that in the
+situation above this may mean losing the commits labeled `a` and `b`,
+unless you've already created a reference of your own pointing to
+them.
+
+[[forcing-fetch]]
+=== Forcing git fetch to do non-fast-forward updates
+
+If git fetch fails because the new head of a branch is not a
+descendant of the old head, you may force the update with:
+
+-------------------------------------------------
+$ git fetch git://example.com/proj.git +master:refs/remotes/example/master
+-------------------------------------------------
+
+Note the addition of the `+` sign. Alternatively, you can use the `-f`
+flag to force updates of all the fetched branches, as in:
+
+-------------------------------------------------
+$ git fetch -f origin
+-------------------------------------------------
+
+Be aware that commits that the old version of example/master pointed at
+may be lost, as we saw in the previous section.
+
+[[remote-branch-configuration]]
+=== Configuring remote-tracking branches
+
+We saw above that `origin` is just a shortcut to refer to the
+repository that you originally cloned from. This information is
+stored in Git configuration variables, which you can see using
+linkgit:git-config[1]:
+
+-------------------------------------------------
+$ git config -l
+core.repositoryformatversion=0
+core.filemode=true
+core.logallrefupdates=true
+remote.origin.url=git://git.kernel.org/pub/scm/git/git.git
+remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
+branch.master.remote=origin
+branch.master.merge=refs/heads/master
+-------------------------------------------------
+
+If there are other repositories that you also use frequently, you can
+create similar configuration options to save typing; for example,
+
+-------------------------------------------------
+$ git remote add example git://example.com/proj.git
+-------------------------------------------------
+
+adds the following to `.git/config`:
+
+-------------------------------------------------
+[remote "example"]
+ url = git://example.com/proj.git
+ fetch = +refs/heads/*:refs/remotes/example/*
+-------------------------------------------------
+
+Also note that the above configuration can be performed by directly
+editing the file `.git/config` instead of using linkgit:git-remote[1].
+
+After configuring the remote, the following three commands will do the
+same thing:
+
+-------------------------------------------------
+$ git fetch git://example.com/proj.git +refs/heads/*:refs/remotes/example/*
+$ git fetch example +refs/heads/*:refs/remotes/example/*
+$ git fetch example
+-------------------------------------------------
+
+See linkgit:git-config[1] for more details on the configuration
+options mentioned above and linkgit:git-fetch[1] for more details on
+the refspec syntax.
+
+
+[[git-concepts]]
+== Git concepts
+
+Git is built on a small number of simple but powerful ideas. While it
+is possible to get things done without understanding them, you will find
+Git much more intuitive if you do.
+
+We start with the most important, the <<def_object_database,object
+database>> and the <<def_index,index>>.
+
+[[the-object-database]]
+=== The Object Database
+
+
+We already saw in <<understanding-commits>> that all commits are stored
+under a 40-digit "object name". In fact, all the information needed to
+represent the history of a project is stored in objects with such names.
+In each case the name is calculated by taking the SHA-1 hash of the
+contents of the object. The SHA-1 hash is a cryptographic hash function.
+What that means to us is that it is impossible to find two different
+objects with the same name. This has a number of advantages; among
+others:
+
+- Git can quickly determine whether two objects are identical or not,
+ just by comparing names.
+- Since object names are computed the same way in every repository, the
+ same content stored in two repositories will always be stored under
+ the same name.
+- Git can detect errors when it reads an object, by checking that the
+ object's name is still the SHA-1 hash of its contents.
+
+(See <<object-details>> for the details of the object formatting and
+SHA-1 calculation.)
+
+There are four different types of objects: "blob", "tree", "commit", and
+"tag".
+
+- A <<def_blob_object,"blob" object>> is used to store file data.
+- A <<def_tree_object,"tree" object>> ties one or more
+ "blob" objects into a directory structure. In addition, a tree object
+ can refer to other tree objects, thus creating a directory hierarchy.
+- A <<def_commit_object,"commit" object>> ties such directory hierarchies
+ together into a <<def_DAG,directed acyclic graph>> of revisions--each
+ commit contains the object name of exactly one tree designating the
+ directory hierarchy at the time of the commit. In addition, a commit
+ refers to "parent" commit objects that describe the history of how we
+ arrived at that directory hierarchy.
+- A <<def_tag_object,"tag" object>> symbolically identifies and can be
+ used to sign other objects. It contains the object name and type of
+ another object, a symbolic name (of course!) and, optionally, a
+ signature.
+
+The object types in some more detail:
+
+[[commit-object]]
+==== Commit Object
+
+The "commit" object links a physical state of a tree with a description
+of how we got there and why. Use the `--pretty=raw` option to
+linkgit:git-show[1] or linkgit:git-log[1] to examine your favorite
+commit:
+
+------------------------------------------------
+$ git show -s --pretty=raw 2be7fcb476
+commit 2be7fcb4764f2dbcee52635b91fedb1b3dcf7ab4
+tree fb3a8bdd0ceddd019615af4d57a53f43d8cee2bf
+parent 257a84d9d02e90447b149af58b271c19405edb6a
+author Dave Watson <dwatson@mimvista.com> 1187576872 -0400
+committer Junio C Hamano <gitster@pobox.com> 1187591163 -0700
+
+ Fix misspelling of 'suppress' in docs
+
+ Signed-off-by: Junio C Hamano <gitster@pobox.com>
+------------------------------------------------
+
+As you can see, a commit is defined by:
+
+- a tree: The SHA-1 name of a tree object (as defined below), representing
+ the contents of a directory at a certain point in time.
+- parent(s): The SHA-1 name(s) of some number of commits which represent the
+ immediately previous step(s) in the history of the project. The
+ example above has one parent; merge commits may have more than
+ one. A commit with no parents is called a "root" commit, and
+ represents the initial revision of a project. Each project must have
+ at least one root. A project can also have multiple roots, though
+ that isn't common (or necessarily a good idea).
+- an author: The name of the person responsible for this change, together
+ with its date.
+- a committer: The name of the person who actually created the commit,
+ with the date it was done. This may be different from the author, for
+ example, if the author was someone who wrote a patch and emailed it
+ to the person who used it to create the commit.
+- a comment describing this commit.
+
+Note that a commit does not itself contain any information about what
+actually changed; all changes are calculated by comparing the contents
+of the tree referred to by this commit with the trees associated with
+its parents. In particular, Git does not attempt to record file renames
+explicitly, though it can identify cases where the existence of the same
+file data at changing paths suggests a rename. (See, for example, the
+`-M` option to linkgit:git-diff[1]).
+
+A commit is usually created by linkgit:git-commit[1], which creates a
+commit whose parent is normally the current HEAD, and whose tree is
+taken from the content currently stored in the index.
+
+[[tree-object]]
+==== Tree Object
+
+The ever-versatile linkgit:git-show[1] command can also be used to
+examine tree objects, but linkgit:git-ls-tree[1] will give you more
+details:
+
+------------------------------------------------
+$ git ls-tree fb3a8bdd0ce
+100644 blob 63c918c667fa005ff12ad89437f2fdc80926e21c .gitignore
+100644 blob 5529b198e8d14decbe4ad99db3f7fb632de0439d .mailmap
+100644 blob 6ff87c4664981e4397625791c8ea3bbb5f2279a3 COPYING
+040000 tree 2fb783e477100ce076f6bf57e4a6f026013dc745 Documentation
+100755 blob 3c0032cec592a765692234f1cba47dfdcc3a9200 GIT-VERSION-GEN
+100644 blob 289b046a443c0647624607d471289b2c7dcd470b INSTALL
+100644 blob 4eb463797adc693dc168b926b6932ff53f17d0b1 Makefile
+100644 blob 548142c327a6790ff8821d67c2ee1eff7a656b52 README
+...
+------------------------------------------------
+
+As you can see, a tree object contains a list of entries, each with a
+mode, object type, SHA-1 name, and name, sorted by name. It represents
+the contents of a single directory tree.
+
+The object type may be a blob, representing the contents of a file, or
+another tree, representing the contents of a subdirectory. Since trees
+and blobs, like all other objects, are named by the SHA-1 hash of their
+contents, two trees have the same SHA-1 name if and only if their
+contents (including, recursively, the contents of all subdirectories)
+are identical. This allows Git to quickly determine the differences
+between two related tree objects, since it can ignore any entries with
+identical object names.
+
+(Note: in the presence of submodules, trees may also have commits as
+entries. See <<submodules>> for documentation.)
+
+Note that the files all have mode 644 or 755: Git actually only pays
+attention to the executable bit.
+
+[[blob-object]]
+==== Blob Object
+
+You can use linkgit:git-show[1] to examine the contents of a blob; take,
+for example, the blob in the entry for `COPYING` from the tree above:
+
+------------------------------------------------
+$ git show 6ff87c4664
+
+ Note that the only valid version of the GPL as far as this project
+ is concerned is _this_ particular version of the license (ie v2, not
+ v2.2 or v3.x or whatever), unless explicitly otherwise stated.
+...
+------------------------------------------------
+
+A "blob" object is nothing but a binary blob of data. It doesn't refer
+to anything else or have attributes of any kind.
+
+Since the blob is entirely defined by its data, if two files in a
+directory tree (or in multiple different versions of the repository)
+have the same contents, they will share the same blob object. The object
+is totally independent of its location in the directory tree, and
+renaming a file does not change the object that file is associated with.
+
+Note that any tree or blob object can be examined using
+linkgit:git-show[1] with the <revision>:<path> syntax. This can
+sometimes be useful for browsing the contents of a tree that is not
+currently checked out.
+
+[[trust]]
+==== Trust
+
+If you receive the SHA-1 name of a blob from one source, and its contents
+from another (possibly untrusted) source, you can still trust that those
+contents are correct as long as the SHA-1 name agrees. This is because
+the SHA-1 is designed so that it is infeasible to find different contents
+that produce the same hash.
+
+Similarly, you need only trust the SHA-1 name of a top-level tree object
+to trust the contents of the entire directory that it refers to, and if
+you receive the SHA-1 name of a commit from a trusted source, then you
+can easily verify the entire history of commits reachable through
+parents of that commit, and all of those contents of the trees referred
+to by those commits.
+
+So to introduce some real trust in the system, the only thing you need
+to do is to digitally sign just 'one' special note, which includes the
+name of a top-level commit. Your digital signature shows others
+that you trust that commit, and the immutability of the history of
+commits tells others that they can trust the whole history.
+
+In other words, you can easily validate a whole archive by just
+sending out a single email that tells the people the name (SHA-1 hash)
+of the top commit, and digitally sign that email using something
+like GPG/PGP.
+
+To assist in this, Git also provides the tag object...
+
+[[tag-object]]
+==== Tag Object
+
+A tag object contains an object, object type, tag name, the name of the
+person ("tagger") who created the tag, and a message, which may contain
+a signature, as can be seen using linkgit:git-cat-file[1]:
+
+------------------------------------------------
+$ git cat-file tag v1.5.0
+object 437b1b20df4b356c9342dac8d38849f24ef44f27
+type commit
+tag v1.5.0
+tagger Junio C Hamano <junkio@cox.net> 1171411200 +0000
+
+GIT 1.5.0
+-----BEGIN PGP SIGNATURE-----
+Version: GnuPG v1.4.6 (GNU/Linux)
+
+iD8DBQBF0lGqwMbZpPMRm5oRAuRiAJ9ohBLd7s2kqjkKlq1qqC57SbnmzQCdG4ui
+nLE/L9aUXdWeTFPron96DLA=
+=2E+0
+-----END PGP SIGNATURE-----
+------------------------------------------------
+
+See the linkgit:git-tag[1] command to learn how to create and verify tag
+objects. (Note that linkgit:git-tag[1] can also be used to create
+"lightweight tags", which are not tag objects at all, but just simple
+references whose names begin with `refs/tags/`).
+
+[[pack-files]]
+==== How Git stores objects efficiently: pack files
+
+Newly created objects are initially created in a file named after the
+object's SHA-1 hash (stored in `.git/objects`).
+
+Unfortunately this system becomes inefficient once a project has a
+lot of objects. Try this on an old project:
+
+------------------------------------------------
+$ git count-objects
+6930 objects, 47620 kilobytes
+------------------------------------------------
+
+The first number is the number of objects which are kept in
+individual files. The second is the amount of space taken up by
+those "loose" objects.
+
+You can save space and make Git faster by moving these loose objects in
+to a "pack file", which stores a group of objects in an efficient
+compressed format; the details of how pack files are formatted can be
+found in linkgit:gitformat-pack[5].
+
+To put the loose objects into a pack, just run git repack:
+
+------------------------------------------------
+$ git repack
+Counting objects: 6020, done.
+Delta compression using up to 4 threads.
+Compressing objects: 100% (6020/6020), done.
+Writing objects: 100% (6020/6020), done.
+Total 6020 (delta 4070), reused 0 (delta 0)
+------------------------------------------------
+
+This creates a single "pack file" in .git/objects/pack/
+containing all currently unpacked objects. You can then run
+
+------------------------------------------------
+$ git prune
+------------------------------------------------
+
+to remove any of the "loose" objects that are now contained in the
+pack. This will also remove any unreferenced objects (which may be
+created when, for example, you use `git reset` to remove a commit).
+You can verify that the loose objects are gone by looking at the
+`.git/objects` directory or by running
+
+------------------------------------------------
+$ git count-objects
+0 objects, 0 kilobytes
+------------------------------------------------
+
+Although the object files are gone, any commands that refer to those
+objects will work exactly as they did before.
+
+The linkgit:git-gc[1] command performs packing, pruning, and more for
+you, so is normally the only high-level command you need.
+
+[[dangling-objects]]
+==== Dangling objects
+
+The linkgit:git-fsck[1] command will sometimes complain about dangling
+objects. They are not a problem.
+
+The most common cause of dangling objects is that you've rebased a
+branch, or you have pulled from somebody else who rebased a branch--see
+<<cleaning-up-history>>. In that case, the old head of the original
+branch still exists, as does everything it pointed to. The branch
+pointer itself just doesn't, since you replaced it with another one.
+
+There are also other situations that cause dangling objects. For
+example, a "dangling blob" may arise because you did a `git add` of a
+file, but then, before you actually committed it and made it part of the
+bigger picture, you changed something else in that file and committed
+that *updated* thing--the old state that you added originally ends up
+not being pointed to by any commit or tree, so it's now a dangling blob
+object.
+
+Similarly, when the "ort" merge strategy runs, and finds that
+there are criss-cross merges and thus more than one merge base (which is
+fairly unusual, but it does happen), it will generate one temporary
+midway tree (or possibly even more, if you had lots of criss-crossing
+merges and more than two merge bases) as a temporary internal merge
+base, and again, those are real objects, but the end result will not end
+up pointing to them, so they end up "dangling" in your repository.
+
+Generally, dangling objects aren't anything to worry about. They can
+even be very useful: if you screw something up, the dangling objects can
+be how you recover your old tree (say, you did a rebase, and realized
+that you really didn't want to--you can look at what dangling objects
+you have, and decide to reset your head to some old dangling state).
+
+For commits, you can just use:
+
+------------------------------------------------
+$ gitk <dangling-commit-sha-goes-here> --not --all
+------------------------------------------------
+
+This asks for all the history reachable from the given commit but not
+from any branch, tag, or other reference. If you decide it's something
+you want, you can always create a new reference to it, e.g.,
+
+------------------------------------------------
+$ git branch recovered-branch <dangling-commit-sha-goes-here>
+------------------------------------------------
+
+For blobs and trees, you can't do the same, but you can still examine
+them. You can just do
+
+------------------------------------------------
+$ git show <dangling-blob/tree-sha-goes-here>
+------------------------------------------------
+
+to show what the contents of the blob were (or, for a tree, basically
+what the `ls` for that directory was), and that may give you some idea
+of what the operation was that left that dangling object.
+
+Usually, dangling blobs and trees aren't very interesting. They're
+almost always the result of either being a half-way mergebase (the blob
+will often even have the conflict markers from a merge in it, if you
+have had conflicting merges that you fixed up by hand), or simply
+because you interrupted a `git fetch` with ^C or something like that,
+leaving _some_ of the new objects in the object database, but just
+dangling and useless.
+
+Anyway, once you are sure that you're not interested in any dangling
+state, you can just prune all unreachable objects:
+
+------------------------------------------------
+$ git prune
+------------------------------------------------
+
+and they'll be gone. (You should only run `git prune` on a quiescent
+repository--it's kind of like doing a filesystem fsck recovery: you
+don't want to do that while the filesystem is mounted.
+`git prune` is designed not to cause any harm in such cases of concurrent
+accesses to a repository but you might receive confusing or scary messages.)
+
+[[recovering-from-repository-corruption]]
+==== Recovering from repository corruption
+
+By design, Git treats data trusted to it with caution. However, even in
+the absence of bugs in Git itself, it is still possible that hardware or
+operating system errors could corrupt data.
+
+The first defense against such problems is backups. You can back up a
+Git directory using clone, or just using cp, tar, or any other backup
+mechanism.
+
+As a last resort, you can search for the corrupted objects and attempt
+to replace them by hand. Back up your repository before attempting this
+in case you corrupt things even more in the process.
+
+We'll assume that the problem is a single missing or corrupted blob,
+which is sometimes a solvable problem. (Recovering missing trees and
+especially commits is *much* harder).
+
+Before starting, verify that there is corruption, and figure out where
+it is with linkgit:git-fsck[1]; this may be time-consuming.
+
+Assume the output looks like this:
+
+------------------------------------------------
+$ git fsck --full --no-dangling
+broken link from tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8
+ to blob 4b9458b3786228369c63936db65827de3cc06200
+missing blob 4b9458b3786228369c63936db65827de3cc06200
+------------------------------------------------
+
+Now you know that blob 4b9458b3 is missing, and that the tree 2d9263c6
+points to it. If you could find just one copy of that missing blob
+object, possibly in some other repository, you could move it into
+`.git/objects/4b/9458b3...` and be done. Suppose you can't. You can
+still examine the tree that pointed to it with linkgit:git-ls-tree[1],
+which might output something like:
+
+------------------------------------------------
+$ git ls-tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8
+100644 blob 8d14531846b95bfa3564b58ccfb7913a034323b8 .gitignore
+100644 blob ebf9bf84da0aab5ed944264a5db2a65fe3a3e883 .mailmap
+100644 blob ca442d313d86dc67e0a2e5d584b465bd382cbf5c COPYING
+...
+100644 blob 4b9458b3786228369c63936db65827de3cc06200 myfile
+...
+------------------------------------------------
+
+So now you know that the missing blob was the data for a file named
+`myfile`. And chances are you can also identify the directory--let's
+say it's in `somedirectory`. If you're lucky the missing copy might be
+the same as the copy you have checked out in your working tree at
+`somedirectory/myfile`; you can test whether that's right with
+linkgit:git-hash-object[1]:
+
+------------------------------------------------
+$ git hash-object -w somedirectory/myfile
+------------------------------------------------
+
+which will create and store a blob object with the contents of
+somedirectory/myfile, and output the SHA-1 of that object. if you're
+extremely lucky it might be 4b9458b3786228369c63936db65827de3cc06200, in
+which case you've guessed right, and the corruption is fixed!
+
+Otherwise, you need more information. How do you tell which version of
+the file has been lost?
+
+The easiest way to do this is with:
+
+------------------------------------------------
+$ git log --raw --all --full-history -- somedirectory/myfile
+------------------------------------------------
+
+Because you're asking for raw output, you'll now get something like
+
+------------------------------------------------
+commit abc
+Author:
+Date:
+...
+:100644 100644 4b9458b newsha M somedirectory/myfile
+
+
+commit xyz
+Author:
+Date:
+
+...
+:100644 100644 oldsha 4b9458b M somedirectory/myfile
+------------------------------------------------
+
+This tells you that the immediately following version of the file was
+"newsha", and that the immediately preceding version was "oldsha".
+You also know the commit messages that went with the change from oldsha
+to 4b9458b and with the change from 4b9458b to newsha.
+
+If you've been committing small enough changes, you may now have a good
+shot at reconstructing the contents of the in-between state 4b9458b.
+
+If you can do that, you can now recreate the missing object with
+
+------------------------------------------------
+$ git hash-object -w <recreated-file>
+------------------------------------------------
+
+and your repository is good again!
+
+(Btw, you could have ignored the `fsck`, and started with doing a
+
+------------------------------------------------
+$ git log --raw --all
+------------------------------------------------
+
+and just looked for the sha of the missing object (4b9458b) in that
+whole thing. It's up to you--Git does *have* a lot of information, it is
+just missing one particular blob version.
+
+[[the-index]]
+=== The index
+
+The index is a binary file (generally kept in `.git/index`) containing a
+sorted list of path names, each with permissions and the SHA-1 of a blob
+object; linkgit:git-ls-files[1] can show you the contents of the index:
+
+-------------------------------------------------
+$ git ls-files --stage
+100644 63c918c667fa005ff12ad89437f2fdc80926e21c 0 .gitignore
+100644 5529b198e8d14decbe4ad99db3f7fb632de0439d 0 .mailmap
+100644 6ff87c4664981e4397625791c8ea3bbb5f2279a3 0 COPYING
+100644 a37b2152bd26be2c2289e1f57a292534a51a93c7 0 Documentation/.gitignore
+100644 fbefe9a45b00a54b58d94d06eca48b03d40a50e0 0 Documentation/Makefile
+...
+100644 2511aef8d89ab52be5ec6a5e46236b4b6bcd07ea 0 xdiff/xtypes.h
+100644 2ade97b2574a9f77e7ae4002a4e07a6a38e46d07 0 xdiff/xutils.c
+100644 d5de8292e05e7c36c4b68857c1cf9855e3d2f70a 0 xdiff/xutils.h
+-------------------------------------------------
+
+Note that in older documentation you may see the index called the
+"current directory cache" or just the "cache". It has three important
+properties:
+
+1. The index contains all the information necessary to generate a single
+(uniquely determined) tree object.
++
+For example, running linkgit:git-commit[1] generates this tree object
+from the index, stores it in the object database, and uses it as the
+tree object associated with the new commit.
+
+2. The index enables fast comparisons between the tree object it defines
+and the working tree.
++
+It does this by storing some additional data for each entry (such as
+the last modified time). This data is not displayed above, and is not
+stored in the created tree object, but it can be used to determine
+quickly which files in the working directory differ from what was
+stored in the index, and thus save Git from having to read all of the
+data from such files to look for changes.
+
+3. It can efficiently represent information about merge conflicts
+between different tree objects, allowing each pathname to be
+associated with sufficient information about the trees involved that
+you can create a three-way merge between them.
++
+We saw in <<conflict-resolution>> that during a merge the index can
+store multiple versions of a single file (called "stages"). The third
+column in the linkgit:git-ls-files[1] output above is the stage
+number, and will take on values other than 0 for files with merge
+conflicts.
+
+The index is thus a sort of temporary staging area, which is filled with
+a tree which you are in the process of working on.
+
+If you blow the index away entirely, you generally haven't lost any
+information as long as you have the name of the tree that it described.
+
+[[submodules]]
+== Submodules
+
+Large projects are often composed of smaller, self-contained modules. For
+example, an embedded Linux distribution's source tree would include every
+piece of software in the distribution with some local modifications; a movie
+player might need to build against a specific, known-working version of a
+decompression library; several independent programs might all share the same
+build scripts.
+
+With centralized revision control systems this is often accomplished by
+including every module in one single repository. Developers can check out
+all modules or only the modules they need to work with. They can even modify
+files across several modules in a single commit while moving things around
+or updating APIs and translations.
+
+Git does not allow partial checkouts, so duplicating this approach in Git
+would force developers to keep a local copy of modules they are not
+interested in touching. Commits in an enormous checkout would be slower
+than you'd expect as Git would have to scan every directory for changes.
+If modules have a lot of local history, clones would take forever.
+
+On the plus side, distributed revision control systems can much better
+integrate with external sources. In a centralized model, a single arbitrary
+snapshot of the external project is exported from its own revision control
+and then imported into the local revision control on a vendor branch. All
+the history is hidden. With distributed revision control you can clone the
+entire external history and much more easily follow development and re-merge
+local changes.
+
+Git's submodule support allows a repository to contain, as a subdirectory, a
+checkout of an external project. Submodules maintain their own identity;
+the submodule support just stores the submodule repository location and
+commit ID, so other developers who clone the containing project
+("superproject") can easily clone all the submodules at the same revision.
+Partial checkouts of the superproject are possible: you can tell Git to
+clone none, some or all of the submodules.
+
+The linkgit:git-submodule[1] command is available since Git 1.5.3. Users
+with Git 1.5.2 can look up the submodule commits in the repository and
+manually check them out; earlier versions won't recognize the submodules at
+all.
+
+To see how submodule support works, create four example
+repositories that can be used later as a submodule:
+
+-------------------------------------------------
+$ mkdir ~/git
+$ cd ~/git
+$ for i in a b c d
+do
+ mkdir $i
+ cd $i
+ git init
+ echo "module $i" > $i.txt
+ git add $i.txt
+ git commit -m "Initial commit, submodule $i"
+ cd ..
+done
+-------------------------------------------------
+
+Now create the superproject and add all the submodules:
+
+-------------------------------------------------
+$ mkdir super
+$ cd super
+$ git init
+$ for i in a b c d
+do
+ git submodule add ~/git/$i $i
+done
+-------------------------------------------------
+
+NOTE: Do not use local URLs here if you plan to publish your superproject!
+
+See what files `git submodule` created:
+
+-------------------------------------------------
+$ ls -a
+. .. .git .gitmodules a b c d
+-------------------------------------------------
+
+The `git submodule add <repo> <path>` command does a couple of things:
+
+- It clones the submodule from `<repo>` to the given `<path>` under the
+ current directory and by default checks out the master branch.
+- It adds the submodule's clone path to the linkgit:gitmodules[5] file and
+ adds this file to the index, ready to be committed.
+- It adds the submodule's current commit ID to the index, ready to be
+ committed.
+
+Commit the superproject:
+
+-------------------------------------------------
+$ git commit -m "Add submodules a, b, c and d."
+-------------------------------------------------
+
+Now clone the superproject:
+
+-------------------------------------------------
+$ cd ..
+$ git clone super cloned
+$ cd cloned
+-------------------------------------------------
+
+The submodule directories are there, but they're empty:
+
+-------------------------------------------------
+$ ls -a a
+. ..
+$ git submodule status
+-d266b9873ad50488163457f025db7cdd9683d88b a
+-e81d457da15309b4fef4249aba9b50187999670d b
+-c1536a972b9affea0f16e0680ba87332dc059146 c
+-d96249ff5d57de5de093e6baff9e0aafa5276a74 d
+-------------------------------------------------
+
+NOTE: The commit object names shown above would be different for you, but they
+should match the HEAD commit object names of your repositories. You can check
+it by running `git ls-remote ../a`.
+
+Pulling down the submodules is a two-step process. First run `git submodule
+init` to add the submodule repository URLs to `.git/config`:
+
+-------------------------------------------------
+$ git submodule init
+-------------------------------------------------
+
+Now use `git submodule update` to clone the repositories and check out the
+commits specified in the superproject:
+
+-------------------------------------------------
+$ git submodule update
+$ cd a
+$ ls -a
+. .. .git a.txt
+-------------------------------------------------
+
+One major difference between `git submodule update` and `git submodule add` is
+that `git submodule update` checks out a specific commit, rather than the tip
+of a branch. It's like checking out a tag: the head is detached, so you're not
+working on a branch.
+
+-------------------------------------------------
+$ git branch
+* (detached from d266b98)
+ master
+-------------------------------------------------
+
+If you want to make a change within a submodule and you have a detached head,
+then you should create or checkout a branch, make your changes, publish the
+change within the submodule, and then update the superproject to reference the
+new commit:
+
+-------------------------------------------------
+$ git switch master
+-------------------------------------------------
+
+or
+
+-------------------------------------------------
+$ git switch -c fix-up
+-------------------------------------------------
+
+then
+
+-------------------------------------------------
+$ echo "adding a line again" >> a.txt
+$ git commit -a -m "Updated the submodule from within the superproject."
+$ git push
+$ cd ..
+$ git diff
+diff --git a/a b/a
+index d266b98..261dfac 160000
+--- a/a
++++ b/a
+@@ -1 +1 @@
+-Subproject commit d266b9873ad50488163457f025db7cdd9683d88b
++Subproject commit 261dfac35cb99d380eb966e102c1197139f7fa24
+$ git add a
+$ git commit -m "Updated submodule a."
+$ git push
+-------------------------------------------------
+
+You have to run `git submodule update` after `git pull` if you want to update
+submodules, too.
+
+[[pitfalls-with-submodules]]
+=== Pitfalls with submodules
+
+Always publish the submodule change before publishing the change to the
+superproject that references it. If you forget to publish the submodule change,
+others won't be able to clone the repository:
+
+-------------------------------------------------
+$ cd ~/git/super/a
+$ echo i added another line to this file >> a.txt
+$ git commit -a -m "doing it wrong this time"
+$ cd ..
+$ git add a
+$ git commit -m "Updated submodule a again."
+$ git push
+$ cd ~/git/cloned
+$ git pull
+$ git submodule update
+error: pathspec '261dfac35cb99d380eb966e102c1197139f7fa24' did not match any file(s) known to git.
+Did you forget to 'git add'?
+Unable to checkout '261dfac35cb99d380eb966e102c1197139f7fa24' in submodule path 'a'
+-------------------------------------------------
+
+In older Git versions it could be easily forgotten to commit new or modified
+files in a submodule, which silently leads to similar problems as not pushing
+the submodule changes. Starting with Git 1.7.0 both `git status` and `git diff`
+in the superproject show submodules as modified when they contain new or
+modified files to protect against accidentally committing such a state. `git
+diff` will also add a `-dirty` to the work tree side when generating patch
+output or used with the `--submodule` option:
+
+-------------------------------------------------
+$ git diff
+diff --git a/sub b/sub
+--- a/sub
++++ b/sub
+@@ -1 +1 @@
+-Subproject commit 3f356705649b5d566d97ff843cf193359229a453
++Subproject commit 3f356705649b5d566d97ff843cf193359229a453-dirty
+$ git diff --submodule
+Submodule sub 3f35670..3f35670-dirty:
+-------------------------------------------------
+
+You also should not rewind branches in a submodule beyond commits that were
+ever recorded in any superproject.
+
+It's not safe to run `git submodule update` if you've made and committed
+changes within a submodule without checking out a branch first. They will be
+silently overwritten:
+
+-------------------------------------------------
+$ cat a.txt
+module a
+$ echo line added from private2 >> a.txt
+$ git commit -a -m "line added inside private2"
+$ cd ..
+$ git submodule update
+Submodule path 'a': checked out 'd266b9873ad50488163457f025db7cdd9683d88b'
+$ cd a
+$ cat a.txt
+module a
+-------------------------------------------------
+
+NOTE: The changes are still visible in the submodule's reflog.
+
+If you have uncommitted changes in your submodule working tree, `git
+submodule update` will not overwrite them. Instead, you get the usual
+warning about not being able switch from a dirty branch.
+
+[[low-level-operations]]
+== Low-level Git operations
+
+Many of the higher-level commands were originally implemented as shell
+scripts using a smaller core of low-level Git commands. These can still
+be useful when doing unusual things with Git, or just as a way to
+understand its inner workings.
+
+[[object-manipulation]]
+=== Object access and manipulation
+
+The linkgit:git-cat-file[1] command can show the contents of any object,
+though the higher-level linkgit:git-show[1] is usually more useful.
+
+The linkgit:git-commit-tree[1] command allows constructing commits with
+arbitrary parents and trees.
+
+A tree can be created with linkgit:git-write-tree[1] and its data can be
+accessed by linkgit:git-ls-tree[1]. Two trees can be compared with
+linkgit:git-diff-tree[1].
+
+A tag is created with linkgit:git-mktag[1], and the signature can be
+verified by linkgit:git-verify-tag[1], though it is normally simpler to
+use linkgit:git-tag[1] for both.
+
+[[the-workflow]]
+=== The Workflow
+
+High-level operations such as linkgit:git-commit[1] and
+linkgit:git-restore[1] work by moving data
+between the working tree, the index, and the object database. Git
+provides low-level operations which perform each of these steps
+individually.
+
+Generally, all Git operations work on the index file. Some operations
+work *purely* on the index file (showing the current state of the
+index), but most operations move data between the index file and either
+the database or the working directory. Thus there are four main
+combinations:
+
+[[working-directory-to-index]]
+==== working directory -> index
+
+The linkgit:git-update-index[1] command updates the index with
+information from the working directory. You generally update the
+index information by just specifying the filename you want to update,
+like so:
+
+-------------------------------------------------
+$ git update-index filename
+-------------------------------------------------
+
+but to avoid common mistakes with filename globbing etc., the command
+will not normally add totally new entries or remove old entries,
+i.e. it will normally just update existing cache entries.
+
+To tell Git that yes, you really do realize that certain files no
+longer exist, or that new files should be added, you
+should use the `--remove` and `--add` flags respectively.
+
+NOTE! A `--remove` flag does 'not' mean that subsequent filenames will
+necessarily be removed: if the files still exist in your directory
+structure, the index will be updated with their new status, not
+removed. The only thing `--remove` means is that update-index will be
+considering a removed file to be a valid thing, and if the file really
+does not exist any more, it will update the index accordingly.
+
+As a special case, you can also do `git update-index --refresh`, which
+will refresh the "stat" information of each index to match the current
+stat information. It will 'not' update the object status itself, and
+it will only update the fields that are used to quickly test whether
+an object still matches its old backing store object.
+
+The previously introduced linkgit:git-add[1] is just a wrapper for
+linkgit:git-update-index[1].
+
+[[index-to-object-database]]
+==== index -> object database
+
+You write your current index file to a "tree" object with the program
+
+-------------------------------------------------
+$ git write-tree
+-------------------------------------------------
+
+that doesn't come with any options--it will just write out the
+current index into the set of tree objects that describe that state,
+and it will return the name of the resulting top-level tree. You can
+use that tree to re-generate the index at any time by going in the
+other direction:
+
+[[object-database-to-index]]
+==== object database -> index
+
+You read a "tree" file from the object database, and use that to
+populate (and overwrite--don't do this if your index contains any
+unsaved state that you might want to restore later!) your current
+index. Normal operation is just
+
+-------------------------------------------------
+$ git read-tree <SHA-1 of tree>
+-------------------------------------------------
+
+and your index file will now be equivalent to the tree that you saved
+earlier. However, that is only your 'index' file: your working
+directory contents have not been modified.
+
+[[index-to-working-directory]]
+==== index -> working directory
+
+You update your working directory from the index by "checking out"
+files. This is not a very common operation, since normally you'd just
+keep your files updated, and rather than write to your working
+directory, you'd tell the index files about the changes in your
+working directory (i.e. `git update-index`).
+
+However, if you decide to jump to a new version, or check out somebody
+else's version, or just restore a previous tree, you'd populate your
+index file with read-tree, and then you need to check out the result
+with
+
+-------------------------------------------------
+$ git checkout-index filename
+-------------------------------------------------
+
+or, if you want to check out all of the index, use `-a`.
+
+NOTE! `git checkout-index` normally refuses to overwrite old files, so
+if you have an old version of the tree already checked out, you will
+need to use the `-f` flag ('before' the `-a` flag or the filename) to
+'force' the checkout.
+
+
+Finally, there are a few odds and ends which are not purely moving
+from one representation to the other:
+
+[[tying-it-all-together]]
+==== Tying it all together
+
+To commit a tree you have instantiated with `git write-tree`, you'd
+create a "commit" object that refers to that tree and the history
+behind it--most notably the "parent" commits that preceded it in
+history.
+
+Normally a "commit" has one parent: the previous state of the tree
+before a certain change was made. However, sometimes it can have two
+or more parent commits, in which case we call it a "merge", due to the
+fact that such a commit brings together ("merges") two or more
+previous states represented by other commits.
+
+In other words, while a "tree" represents a particular directory state
+of a working directory, a "commit" represents that state in time,
+and explains how we got there.
+
+You create a commit object by giving it the tree that describes the
+state at the time of the commit, and a list of parents:
+
+-------------------------------------------------
+$ git commit-tree <tree> -p <parent> [(-p <parent2>)...]
+-------------------------------------------------
+
+and then giving the reason for the commit on stdin (either through
+redirection from a pipe or file, or by just typing it at the tty).
+
+`git commit-tree` will return the name of the object that represents
+that commit, and you should save it away for later use. Normally,
+you'd commit a new `HEAD` state, and while Git doesn't care where you
+save the note about that state, in practice we tend to just write the
+result to the file pointed at by `.git/HEAD`, so that we can always see
+what the last committed state was.
+
+Here is a picture that illustrates how various pieces fit together:
+
+------------
+
+ commit-tree
+ commit obj
+ +----+
+ | |
+ | |
+ V V
+ +-----------+
+ | Object DB |
+ | Backing |
+ | Store |
+ +-----------+
+ ^
+ write-tree | |
+ tree obj | |
+ | | read-tree
+ | | tree obj
+ V
+ +-----------+
+ | Index |
+ | "cache" |
+ +-----------+
+ update-index ^
+ blob obj | |
+ | |
+ checkout-index -u | | checkout-index
+ stat | | blob obj
+ V
+ +-----------+
+ | Working |
+ | Directory |
+ +-----------+
+
+------------
+
+
+[[examining-the-data]]
+=== Examining the data
+
+You can examine the data represented in the object database and the
+index with various helper tools. For every object, you can use
+linkgit:git-cat-file[1] to examine details about the
+object:
+
+-------------------------------------------------
+$ git cat-file -t <objectname>
+-------------------------------------------------
+
+shows the type of the object, and once you have the type (which is
+usually implicit in where you find the object), you can use
+
+-------------------------------------------------
+$ git cat-file blob|tree|commit|tag <objectname>
+-------------------------------------------------
+
+to show its contents. NOTE! Trees have binary content, and as a result
+there is a special helper for showing that content, called
+`git ls-tree`, which turns the binary content into a more easily
+readable form.
+
+It's especially instructive to look at "commit" objects, since those
+tend to be small and fairly self-explanatory. In particular, if you
+follow the convention of having the top commit name in `.git/HEAD`,
+you can do
+
+-------------------------------------------------
+$ git cat-file commit HEAD
+-------------------------------------------------
+
+to see what the top commit was.
+
+[[merging-multiple-trees]]
+=== Merging multiple trees
+
+Git can help you perform a three-way merge, which can in turn be
+used for a many-way merge by repeating the merge procedure several
+times. The usual situation is that you only do one three-way merge
+(reconciling two lines of history) and commit the result, but if
+you like to, you can merge several branches in one go.
+
+To perform a three-way merge, you start with the two commits you
+want to merge, find their closest common parent (a third commit),
+and compare the trees corresponding to these three commits.
+
+To get the "base" for the merge, look up the common parent of two
+commits:
+
+-------------------------------------------------
+$ git merge-base <commit1> <commit2>
+-------------------------------------------------
+
+This prints the name of a commit they are both based on. You should
+now look up the tree objects of those commits, which you can easily
+do with
+
+-------------------------------------------------
+$ git cat-file commit <commitname> | head -1
+-------------------------------------------------
+
+since the tree object information is always the first line in a commit
+object.
+
+Once you know the three trees you are going to merge (the one "original"
+tree, aka the common tree, and the two "result" trees, aka the branches
+you want to merge), you do a "merge" read into the index. This will
+complain if it has to throw away your old index contents, so you should
+make sure that you've committed those--in fact you would normally
+always do a merge against your last commit (which should thus match what
+you have in your current index anyway).
+
+To do the merge, do
+
+-------------------------------------------------
+$ git read-tree -m -u <origtree> <yourtree> <targettree>
+-------------------------------------------------
+
+which will do all trivial merge operations for you directly in the
+index file, and you can just write the result out with
+`git write-tree`.
+
+
+[[merging-multiple-trees-2]]
+=== Merging multiple trees, continued
+
+Sadly, many merges aren't trivial. If there are files that have
+been added, moved or removed, or if both branches have modified the
+same file, you will be left with an index tree that contains "merge
+entries" in it. Such an index tree can 'NOT' be written out to a tree
+object, and you will have to resolve any such merge clashes using
+other tools before you can write out the result.
+
+You can examine such index state with `git ls-files --unmerged`
+command. An example:
+
+------------------------------------------------
+$ git read-tree -m $orig HEAD $target
+$ git ls-files --unmerged
+100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello.c
+100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello.c
+100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello.c
+------------------------------------------------
+
+Each line of the `git ls-files --unmerged` output begins with
+the blob mode bits, blob SHA-1, 'stage number', and the
+filename. The 'stage number' is Git's way to say which tree it
+came from: stage 1 corresponds to the `$orig` tree, stage 2 to
+the `HEAD` tree, and stage 3 to the `$target` tree.
+
+Earlier we said that trivial merges are done inside
+`git read-tree -m`. For example, if the file did not change
+from `$orig` to `HEAD` or `$target`, or if the file changed
+from `$orig` to `HEAD` and `$orig` to `$target` the same way,
+obviously the final outcome is what is in `HEAD`. What the
+above example shows is that file `hello.c` was changed from
+`$orig` to `HEAD` and `$orig` to `$target` in a different way.
+You could resolve this by running your favorite 3-way merge
+program, e.g. `diff3`, `merge`, or Git's own merge-file, on
+the blob objects from these three stages yourself, like this:
+
+------------------------------------------------
+$ git cat-file blob 263414f >hello.c~1
+$ git cat-file blob 06fa6a2 >hello.c~2
+$ git cat-file blob cc44c73 >hello.c~3
+$ git merge-file hello.c~2 hello.c~1 hello.c~3
+------------------------------------------------
+
+This would leave the merge result in `hello.c~2` file, along
+with conflict markers if there are conflicts. After verifying
+the merge result makes sense, you can tell Git what the final
+merge result for this file is by:
+
+-------------------------------------------------
+$ mv -f hello.c~2 hello.c
+$ git update-index hello.c
+-------------------------------------------------
+
+When a path is in the "unmerged" state, running `git update-index` for
+that path tells Git to mark the path resolved.
+
+The above is the description of a Git merge at the lowest level,
+to help you understand what conceptually happens under the hood.
+In practice, nobody, not even Git itself, runs `git cat-file` three times
+for this. There is a `git merge-index` program that extracts the
+stages to temporary files and calls a "merge" script on it:
+
+-------------------------------------------------
+$ git merge-index git-merge-one-file hello.c
+-------------------------------------------------
+
+and that is what higher level `git merge -s resolve` is implemented with.
+
+[[hacking-git]]
+== Hacking Git
+
+This chapter covers internal details of the Git implementation which
+probably only Git developers need to understand.
+
+[[object-details]]
+=== Object storage format
+
+All objects have a statically determined "type" which identifies the
+format of the object (i.e. how it is used, and how it can refer to other
+objects). There are currently four different object types: "blob",
+"tree", "commit", and "tag".
+
+Regardless of object type, all objects share the following
+characteristics: they are all deflated with zlib, and have a header
+that not only specifies their type, but also provides size information
+about the data in the object. It's worth noting that the SHA-1 hash
+that is used to name the object is the hash of the original data
+plus this header, so `sha1sum` 'file' does not match the object name
+for 'file'.
+
+As a result, the general consistency of an object can always be tested
+independently of the contents or the type of the object: all objects can
+be validated by verifying that (a) their hashes match the content of the
+file and (b) the object successfully inflates to a stream of bytes that
+forms a sequence of
+`<ascii type without space> + <space> + <ascii decimal size> +
+<byte\0> + <binary object data>`.
+
+The structured objects can further have their structure and
+connectivity to other objects verified. This is generally done with
+the `git fsck` program, which generates a full dependency graph
+of all objects, and verifies their internal consistency (in addition
+to just verifying their superficial consistency through the hash).
+
+[[birdview-on-the-source-code]]
+=== A birds-eye view of Git's source code
+
+It is not always easy for new developers to find their way through Git's
+source code. This section gives you a little guidance to show where to
+start.
+
+A good place to start is with the contents of the initial commit, with:
+
+----------------------------------------------------
+$ git switch --detach e83c5163
+----------------------------------------------------
+
+The initial revision lays the foundation for almost everything Git has
+today, but is small enough to read in one sitting.
+
+Note that terminology has changed since that revision. For example, the
+README in that revision uses the word "changeset" to describe what we
+now call a <<def_commit_object,commit>>.
+
+Also, we do not call it "cache" any more, but rather "index"; however,
+the file is still called `read-cache.h`.
+
+If you grasp the ideas in that initial commit, you should check out a
+more recent version and skim `read-cache-ll.h`, `object.h` and `commit.h`.
+
+In the early days, Git (in the tradition of UNIX) was a bunch of programs
+which were extremely simple, and which you used in scripts, piping the
+output of one into another. This turned out to be good for initial
+development, since it was easier to test new things. However, recently
+many of these parts have become builtins, and some of the core has been
+"libified", i.e. put into libgit.a for performance, portability reasons,
+and to avoid code duplication.
+
+By now, you know what the index is (and find the corresponding data
+structures in `read-cache-ll.h`), and that there are just a couple of
+object types (blobs, trees, commits and tags) which inherit their
+common structure from `struct object`, which is their first member
+(and thus, you can cast e.g. `(struct object *)commit` to achieve the
+_same_ as `&commit->object`, i.e. get at the object name and flags).
+
+Now is a good point to take a break to let this information sink in.
+
+Next step: get familiar with the object naming. Read <<naming-commits>>.
+There are quite a few ways to name an object (and not only revisions!).
+All of these are handled in `sha1_name.c`. Just have a quick look at
+the function `get_sha1()`. A lot of the special handling is done by
+functions like `get_sha1_basic()` or the likes.
+
+This is just to get you into the groove for the most libified part of Git:
+the revision walker.
+
+Basically, the initial version of `git log` was a shell script:
+
+----------------------------------------------------------------
+$ git-rev-list --pretty $(git-rev-parse --default HEAD "$@") | \
+ LESS=-S ${PAGER:-less}
+----------------------------------------------------------------
+
+What does this mean?
+
+`git rev-list` is the original version of the revision walker, which
+_always_ printed a list of revisions to stdout. It is still functional,
+and needs to, since most new Git commands start out as scripts using
+`git rev-list`.
+
+`git rev-parse` is not as important any more; it was only used to filter out
+options that were relevant for the different plumbing commands that were
+called by the script.
+
+Most of what `git rev-list` did is contained in `revision.c` and
+`revision.h`. It wraps the options in a struct named `rev_info`, which
+controls how and what revisions are walked, and more.
+
+The original job of `git rev-parse` is now taken by the function
+`setup_revisions()`, which parses the revisions and the common command-line
+options for the revision walker. This information is stored in the struct
+`rev_info` for later consumption. You can do your own command-line option
+parsing after calling `setup_revisions()`. After that, you have to call
+`prepare_revision_walk()` for initialization, and then you can get the
+commits one by one with the function `get_revision()`.
+
+If you are interested in more details of the revision walking process,
+just have a look at the first implementation of `cmd_log()`; call
+`git show v1.3.0~155^2~4` and scroll down to that function (note that you
+no longer need to call `setup_pager()` directly).
+
+Nowadays, `git log` is a builtin, which means that it is _contained_ in the
+command `git`. The source side of a builtin is
+
+- a function called `cmd_<bla>`, typically defined in `builtin/<bla.c>`
+ (note that older versions of Git used to have it in `builtin-<bla>.c`
+ instead), and declared in `builtin.h`.
+
+- an entry in the `commands[]` array in `git.c`, and
+
+- an entry in `BUILTIN_OBJECTS` in the `Makefile`.
+
+Sometimes, more than one builtin is contained in one source file. For
+example, `cmd_whatchanged()` and `cmd_log()` both reside in `builtin/log.c`,
+since they share quite a bit of code. In that case, the commands which are
+_not_ named like the `.c` file in which they live have to be listed in
+`BUILT_INS` in the `Makefile`.
+
+`git log` looks more complicated in C than it does in the original script,
+but that allows for a much greater flexibility and performance.
+
+Here again it is a good point to take a pause.
+
+Lesson three is: study the code. Really, it is the best way to learn about
+the organization of Git (after you know the basic concepts).
+
+So, think about something which you are interested in, say, "how can I
+access a blob just knowing the object name of it?". The first step is to
+find a Git command with which you can do it. In this example, it is either
+`git show` or `git cat-file`.
+
+For the sake of clarity, let's stay with `git cat-file`, because it
+
+- is plumbing, and
+
+- was around even in the initial commit (it literally went only through
+ some 20 revisions as `cat-file.c`, was renamed to `builtin/cat-file.c`
+ when made a builtin, and then saw less than 10 versions).
+
+So, look into `builtin/cat-file.c`, search for `cmd_cat_file()` and look what
+it does.
+
+------------------------------------------------------------------
+ git_config(git_default_config);
+ if (argc != 3)
+ usage("git cat-file [-t|-s|-e|-p|<type>] <sha1>");
+ if (get_sha1(argv[2], sha1))
+ die("Not a valid object name %s", argv[2]);
+------------------------------------------------------------------
+
+Let's skip over the obvious details; the only really interesting part
+here is the call to `get_sha1()`. It tries to interpret `argv[2]` as an
+object name, and if it refers to an object which is present in the current
+repository, it writes the resulting SHA-1 into the variable `sha1`.
+
+Two things are interesting here:
+
+- `get_sha1()` returns 0 on _success_. This might surprise some new
+ Git hackers, but there is a long tradition in UNIX to return different
+ negative numbers in case of different errors--and 0 on success.
+
+- the variable `sha1` in the function signature of `get_sha1()` is `unsigned
+ char *`, but is actually expected to be a pointer to `unsigned
+ char[20]`. This variable will contain the 160-bit SHA-1 of the given
+ commit. Note that whenever a SHA-1 is passed as `unsigned char *`, it
+ is the binary representation, as opposed to the ASCII representation in
+ hex characters, which is passed as `char *`.
+
+You will see both of these things throughout the code.
+
+Now, for the meat:
+
+-----------------------------------------------------------------------------
+ case 0:
+ buf = read_object_with_reference(sha1, argv[1], &size, NULL);
+-----------------------------------------------------------------------------
+
+This is how you read a blob (actually, not only a blob, but any type of
+object). To know how the function `read_object_with_reference()` actually
+works, find the source code for it (something like `git grep
+read_object_with | grep ":[a-z]"` in the Git repository), and read
+the source.
+
+To find out how the result can be used, just read on in `cmd_cat_file()`:
+
+-----------------------------------
+ write_or_die(1, buf, size);
+-----------------------------------
+
+Sometimes, you do not know where to look for a feature. In many such cases,
+it helps to search through the output of `git log`, and then `git show` the
+corresponding commit.
+
+Example: If you know that there was some test case for `git bundle`, but
+do not remember where it was (yes, you _could_ `git grep bundle t/`, but that
+does not illustrate the point!):
+
+------------------------
+$ git log --no-merges t/
+------------------------
+
+In the pager (`less`), just search for "bundle", go a few lines back,
+and see that it is in commit 18449ab0. Now just copy this object name,
+and paste it into the command line
+
+-------------------
+$ git show 18449ab0
+-------------------
+
+Voila.
+
+Another example: Find out what to do in order to make some script a
+builtin:
+
+-------------------------------------------------
+$ git log --no-merges --diff-filter=A builtin/*.c
+-------------------------------------------------
+
+You see, Git is actually the best tool to find out about the source of Git
+itself!
+
+[[glossary]]
+== Git Glossary
+
+[[git-explained]]
+=== Git explained
+
+include::glossary-content.txt[]
+
+[[git-quick-start]]
+[appendix]
+== Git Quick Reference
+
+This is a quick summary of the major commands; the previous chapters
+explain how these work in more detail.
+
+[[quick-creating-a-new-repository]]
+=== Creating a new repository
+
+From a tarball:
+
+-----------------------------------------------
+$ tar xzf project.tar.gz
+$ cd project
+$ git init
+Initialized empty Git repository in .git/
+$ git add .
+$ git commit
+-----------------------------------------------
+
+From a remote repository:
+
+-----------------------------------------------
+$ git clone git://example.com/pub/project.git
+$ cd project
+-----------------------------------------------
+
+[[managing-branches]]
+=== Managing branches
+
+-----------------------------------------------
+$ git branch # list all local branches in this repo
+$ git switch test # switch working directory to branch "test"
+$ git branch new # create branch "new" starting at current HEAD
+$ git branch -d new # delete branch "new"
+-----------------------------------------------
+
+Instead of basing a new branch on current HEAD (the default), use:
+
+-----------------------------------------------
+$ git branch new test # branch named "test"
+$ git branch new v2.6.15 # tag named v2.6.15
+$ git branch new HEAD^ # commit before the most recent
+$ git branch new HEAD^^ # commit before that
+$ git branch new test~10 # ten commits before tip of branch "test"
+-----------------------------------------------
+
+Create and switch to a new branch at the same time:
+
+-----------------------------------------------
+$ git switch -c new v2.6.15
+-----------------------------------------------
+
+Update and examine branches from the repository you cloned from:
+
+-----------------------------------------------
+$ git fetch # update
+$ git branch -r # list
+ origin/master
+ origin/next
+ ...
+$ git switch -c masterwork origin/master
+-----------------------------------------------
+
+Fetch a branch from a different repository, and give it a new
+name in your repository:
+
+-----------------------------------------------
+$ git fetch git://example.com/project.git theirbranch:mybranch
+$ git fetch git://example.com/project.git v2.6.15:mybranch
+-----------------------------------------------
+
+Keep a list of repositories you work with regularly:
+
+-----------------------------------------------
+$ git remote add example git://example.com/project.git
+$ git remote # list remote repositories
+example
+origin
+$ git remote show example # get details
+* remote example
+ URL: git://example.com/project.git
+ Tracked remote branches
+ master
+ next
+ ...
+$ git fetch example # update branches from example
+$ git branch -r # list all remote branches
+-----------------------------------------------
+
+
+[[exploring-history]]
+=== Exploring history
+
+-----------------------------------------------
+$ gitk # visualize and browse history
+$ git log # list all commits
+$ git log src/ # ...modifying src/
+$ git log v2.6.15..v2.6.16 # ...in v2.6.16, not in v2.6.15
+$ git log master..test # ...in branch test, not in branch master
+$ git log test..master # ...in branch master, but not in test
+$ git log test...master # ...in one branch, not in both
+$ git log -S'foo()' # ...where difference contain "foo()"
+$ git log --since="2 weeks ago"
+$ git log -p # show patches as well
+$ git show # most recent commit
+$ git diff v2.6.15..v2.6.16 # diff between two tagged versions
+$ git diff v2.6.15..HEAD # diff with current head
+$ git grep "foo()" # search working directory for "foo()"
+$ git grep v2.6.15 "foo()" # search old tree for "foo()"
+$ git show v2.6.15:a.txt # look at old version of a.txt
+-----------------------------------------------
+
+Search for regressions:
+
+-----------------------------------------------
+$ git bisect start
+$ git bisect bad # current version is bad
+$ git bisect good v2.6.13-rc2 # last known good revision
+Bisecting: 675 revisions left to test after this
+ # test here, then:
+$ git bisect good # if this revision is good, or
+$ git bisect bad # if this revision is bad.
+ # repeat until done.
+-----------------------------------------------
+
+[[making-changes]]
+=== Making changes
+
+Make sure Git knows who to blame:
+
+------------------------------------------------
+$ cat >>~/.gitconfig <<\EOF
+[user]
+ name = Your Name Comes Here
+ email = you@yourdomain.example.com
+EOF
+------------------------------------------------
+
+Select file contents to include in the next commit, then make the
+commit:
+
+-----------------------------------------------
+$ git add a.txt # updated file
+$ git add b.txt # new file
+$ git rm c.txt # old file
+$ git commit
+-----------------------------------------------
+
+Or, prepare and create the commit in one step:
+
+-----------------------------------------------
+$ git commit d.txt # use latest content only of d.txt
+$ git commit -a # use latest content of all tracked files
+-----------------------------------------------
+
+[[merging]]
+=== Merging
+
+-----------------------------------------------
+$ git merge test # merge branch "test" into the current branch
+$ git pull git://example.com/project.git master
+ # fetch and merge in remote branch
+$ git pull . test # equivalent to git merge test
+-----------------------------------------------
+
+[[sharing-your-changes]]
+=== Sharing your changes
+
+Importing or exporting patches:
+
+-----------------------------------------------
+$ 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"
+-----------------------------------------------
+
+Fetch a branch in a different Git repository, then merge into the
+current branch:
+
+-----------------------------------------------
+$ git pull git://example.com/project.git theirbranch
+-----------------------------------------------
+
+Store the fetched branch into a local branch before merging into the
+current branch:
+
+-----------------------------------------------
+$ git pull git://example.com/project.git theirbranch:mybranch
+-----------------------------------------------
+
+After creating commits on a local branch, update the remote
+branch with your commits:
+
+-----------------------------------------------
+$ git push ssh://example.com/project.git mybranch:theirbranch
+-----------------------------------------------
+
+When remote and local branch are both named "test":
+
+-----------------------------------------------
+$ git push ssh://example.com/project.git test
+-----------------------------------------------
+
+Shortcut version for a frequently used remote repository:
+
+-----------------------------------------------
+$ git remote add example ssh://example.com/project.git
+$ git push example test
+-----------------------------------------------
+
+[[repository-maintenance]]
+=== Repository maintenance
+
+Check for corruption:
+
+-----------------------------------------------
+$ git fsck
+-----------------------------------------------
+
+Recompress, remove unused cruft:
+
+-----------------------------------------------
+$ git gc
+-----------------------------------------------
+
+
+[[todo]]
+[appendix]
+== Notes and todo list for this manual
+
+[[todo-list]]
+=== Todo list
+
+This is a work in progress.
+
+The basic requirements:
+
+- It must be readable in order, from beginning to end, by someone
+ intelligent with a basic grasp of the UNIX command line, but without
+ any special knowledge of Git. If necessary, any other prerequisites
+ should be specifically mentioned as they arise.
+- Whenever possible, section headings should clearly describe the task
+ they explain how to do, in language that requires no more knowledge
+ than necessary: for example, "importing patches into a project" rather
+ than "the `git am` command"
+
+Think about how to create a clear chapter dependency graph that will
+allow people to get to important topics without necessarily reading
+everything in between.
+
+Scan `Documentation/` for other stuff left out; in particular:
+
+- howto's
+- some of `technical/`?
+- hooks
+- list of commands in linkgit:git[1]
+
+Scan email archives for other stuff left out
+
+Scan man pages to see if any assume more background than this manual
+provides.
+
+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?
+
+Include cross-references to the glossary, where appropriate.
+
+Add a section on working with other version control systems, including
+CVS, Subversion, and just imports of series of release tarballs.
+
+Write a chapter on using plumbing and writing scripts.
+
+Alternates, clone -reference, etc.
+
+More on recovery from repository corruption. See:
+ https://lore.kernel.org/git/Pine.LNX.4.64.0702272039540.12485@woody.linux-foundation.org/
+ https://lore.kernel.org/git/Pine.LNX.4.64.0702141033400.3604@woody.linux-foundation.org/