about summary refs log tree commit diff
path: root/third_party/git/Documentation/user-manual.txt
diff options
context:
space:
mode:
authorVincent Ambo <tazjin@google.com>2020-05-25T23·06+0100
committerVincent Ambo <tazjin@google.com>2020-05-25T23·06+0100
commit93ba78d6f4632ef1c5228965e3edc8c0faf88c1e (patch)
tree85730c182a9f5f492ade8e8ccdb1c2356f9900bd /third_party/git/Documentation/user-manual.txt
parent6f8fbf4aa4b1654ab27d4829e114538761817de0 (diff)
revert(3p/git): Revert merge of git upstream at v2.26.2 r/852
This causes cgit to serve error pages, which is undesirable.

This reverts commit 5229c9b232de5bfa959ad6ebbb4c8192ac513352, reversing
changes made to f2b211131f2347342dde63975b09cf603149f1a3.
Diffstat (limited to 'third_party/git/Documentation/user-manual.txt')
-rw-r--r--third_party/git/Documentation/user-manual.txt381
1 files changed, 247 insertions, 134 deletions
diff --git a/third_party/git/Documentation/user-manual.txt b/third_party/git/Documentation/user-manual.txt
index 833652983fa6..8bce75b2cf2b 100644
--- a/third_party/git/Documentation/user-manual.txt
+++ b/third_party/git/Documentation/user-manual.txt
@@ -1,4 +1,5 @@
-= Git User Manual
+Git User Manual
+===============
 
 Git is a fast distributed revision control system.
 
@@ -40,10 +41,12 @@ complete.
 
 
 [[repositories-and-branches]]
-== Repositories and Branches
+Repositories and Branches
+=========================
 
 [[how-to-get-a-git-repository]]
-=== 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.
@@ -70,7 +73,8 @@ 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
+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
@@ -147,7 +151,8 @@ with no way to find the history it used to point to; so use this command
 carefully.
 
 [[understanding-commits]]
-=== Understanding History: 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
@@ -197,7 +202,8 @@ 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
+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.
@@ -221,7 +227,8 @@ 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
+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
@@ -240,7 +247,8 @@ 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?
+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
@@ -253,7 +261,8 @@ However, when no confusion will result, we often just use the term
 "branch" both for branches and for branch heads.
 
 [[manipulating-branches]]
-=== Manipulating branches
+Manipulating branches
+---------------------
 
 Creating, deleting, and modifying branches is quick and easy; here's
 a summary of the commands:
@@ -290,7 +299,8 @@ ref: refs/heads/master
 ------------------------------------------------
 
 [[detached-head]]
-=== Examining an old version without creating a new branch
+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,
@@ -330,7 +340,8 @@ 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
+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
@@ -372,7 +383,8 @@ 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
+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
@@ -401,7 +413,8 @@ 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
+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.
@@ -412,7 +425,8 @@ 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
+Fetching branches from other repositories
+-----------------------------------------
 
 You can also track branches from repositories other than the one you
 cloned from, using linkgit:git-remote[1]:
@@ -460,7 +474,8 @@ text editor.  (See the "CONFIGURATION FILE" section of
 linkgit:git-config[1] for details.)
 
 [[exploring-git-history]]
-== 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
@@ -474,7 +489,8 @@ 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
+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
@@ -556,7 +572,8 @@ linkgit:git-bisect[1] for more information about this and other `git
 bisect` features.
 
 [[naming-commits]]
-=== Naming commits
+Naming commits
+--------------
 
 We have seen several ways of naming commits already:
 
@@ -620,7 +637,8 @@ e05db0fd4f31dde7005f075a84f96b360d05984b
 -------------------------------------------------
 
 [[creating-tags]]
-=== Creating tags
+Creating tags
+-------------
 
 We can also create a tag to refer to a particular commit; after
 running
@@ -637,7 +655,8 @@ should create a tag object instead; see the linkgit:git-tag[1] man page
 for details.
 
 [[browsing-revisions]]
-=== 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
@@ -678,7 +697,8 @@ multiple independent lines of development, the particular order that
 commits are listed in may be somewhat arbitrary.
 
 [[generating-diffs]]
-=== Generating diffs
+Generating diffs
+----------------
 
 You can generate diffs between any two versions using
 linkgit:git-diff[1]:
@@ -706,7 +726,8 @@ 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
+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
@@ -721,10 +742,12 @@ 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
+Examples
+--------
 
 [[counting-commits-on-a-branch]]
-==== Counting the number of 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`:
@@ -742,7 +765,8 @@ $ git rev-list origin..mybranch | wc -l
 -------------------------------------------------
 
 [[checking-for-equal-branches]]
-==== Check whether two branches point at the same history
+Check whether two branches point at the same history
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Suppose you want to check whether two branches point at the same point
 in history.
@@ -774,7 +798,8 @@ $ 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
+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
@@ -858,7 +883,8 @@ 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
+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.
@@ -905,7 +931,8 @@ $ gitk $( git show-ref --heads ) --not  $( git show-ref --tags )
 syntax such as `--not`.)
 
 [[making-a-release]]
-==== Creating a changelog and tarball for a software 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:
@@ -956,7 +983,8 @@ 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
+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
@@ -972,10 +1000,12 @@ 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
+Developing with Git
+===================
 
 [[telling-git-your-name]]
-=== 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]:
@@ -1000,7 +1030,8 @@ also edit it with your favorite editor.
 
 
 [[creating-a-new-repository]]
-=== Creating a new repository
+Creating a new repository
+-------------------------
 
 Creating a new repository from scratch is very easy:
 
@@ -1021,7 +1052,8 @@ $ git commit
 -------------------------------------------------
 
 [[how-to-make-a-commit]]
-=== How to make a commit
+How to make a commit
+--------------------
 
 Creating a new commit takes three steps:
 
@@ -1116,7 +1148,8 @@ 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
+Creating good commit messages
+-----------------------------
 
 Though not required, it's a good idea to begin the commit message
 with a single short (less than 50 character) line summarizing the
@@ -1129,7 +1162,8 @@ rest of the commit in the body.
 
 
 [[ignoring-files]]
-=== 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
@@ -1171,7 +1205,8 @@ 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
+How to merge
+------------
 
 You can rejoin two diverging branches of development using
 linkgit:git-merge[1]:
@@ -1219,7 +1254,8 @@ 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
+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
@@ -1261,7 +1297,8 @@ 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
+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
@@ -1364,7 +1401,8 @@ the different stages of that file will be "collapsed", after which
 `git diff` will (by default) no longer show diffs for that file.
 
 [[undoing-a-merge]]
-=== Undoing a merge
+Undoing a merge
+---------------
 
 If you get stuck and decide to just give up and throw the whole mess
 away, you can always return to the pre-merge state with
@@ -1385,7 +1423,8 @@ itself have been merged into another branch, as doing so may confuse
 further merges.
 
 [[fast-forwards]]
-=== Fast-forward merges
+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
@@ -1399,7 +1438,8 @@ to point at the head of the merged-in branch, without any new commits being
 created.
 
 [[fixing-mistakes]]
-=== 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
@@ -1423,7 +1463,8 @@ fundamentally different ways to fix the problem:
 	a branch that has had its history changed.
 
 [[reverting-a-commit]]
-==== Fixing a mistake with a new 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
@@ -1449,7 +1490,8 @@ 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
+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
@@ -1476,7 +1518,8 @@ 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
+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
@@ -1500,7 +1543,8 @@ $ git show HEAD^:path/to/file
 which will display the given version of the file.
 
 [[interrupted-work]]
-==== Temporarily setting aside work in progress
+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
@@ -1531,7 +1575,8 @@ $ git stash pop
 
 
 [[ensuring-good-performance]]
-=== 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
@@ -1542,10 +1587,12 @@ to avoid automatic compression kicking in when it is not convenient.
 
 
 [[ensuring-reliability]]
-=== Ensuring reliability
+Ensuring reliability
+--------------------
 
 [[checking-for-corruption]]
-==== Checking the repository 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
@@ -1571,10 +1618,12 @@ You can run `git fsck --no-dangling` to suppress these messages, and still
 view real errors.
 
 [[recovering-lost-changes]]
-==== Recovering lost changes
+Recovering lost changes
+~~~~~~~~~~~~~~~~~~~~~~~
 
 [[reflogs]]
-===== 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
@@ -1621,7 +1670,8 @@ 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
+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
@@ -1665,10 +1715,12 @@ dangling objects can arise in other situations.
 
 
 [[sharing-development]]
-== Sharing development with others
+Sharing development with others
+===============================
 
 [[getting-updates-With-git-pull]]
-=== 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
@@ -1731,7 +1783,8 @@ $ git merge branch
 are roughly equivalent.
 
 [[submitting-patches]]
-=== Submitting patches to a project
+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:
@@ -1759,7 +1812,8 @@ Consult the mailing list for your project first to determine
 their requirements for submitting patches.
 
 [[importing-patches]]
-=== Importing patches to a project
+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.
@@ -1791,7 +1845,8 @@ the original mailbox, with authorship and commit log message each
 taken from the message containing each patch.
 
 [[public-repositories]]
-=== Public Git 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
@@ -1831,22 +1886,21 @@ 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
-....
+                        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
+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
@@ -1866,7 +1920,8 @@ public repository.  You can use scp, rsync, or whatever is most
 convenient.
 
 [[exporting-via-git]]
-==== Exporting a Git repository via the Git protocol
+Exporting a Git repository via the Git protocol
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This is the preferred method.
 
@@ -1887,7 +1942,8 @@ linkgit:git-daemon[1] man page for details.  (See especially the
 examples section.)
 
 [[exporting-via-http]]
-==== Exporting a git repository 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.
@@ -1919,7 +1975,8 @@ 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
+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
@@ -1978,7 +2035,8 @@ See the explanations of the `remote.<name>.url`,
 linkgit:git-config[1] for details.
 
 [[forcing-push]]
-==== What to do when a push fails
+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:
@@ -2032,7 +2090,8 @@ pull, or by a fetch followed by a rebase; see the
 linkgit:gitcvs-migration[7] for more.
 
 [[setting-up-a-shared-repository]]
-==== 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
@@ -2062,7 +2121,8 @@ advantages over the central shared repository:
 	  "out".
 
 [[setting-up-gitweb]]
-==== Allowing web browsing of a repository
+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
@@ -2078,7 +2138,8 @@ 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
+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
@@ -2097,10 +2158,12 @@ 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
+Examples
+--------
 
 [[maintaining-topic-branches]]
-==== Maintaining topic branches for a Linux subsystem maintainer
+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.
@@ -2396,7 +2459,8 @@ done
 
 
 [[cleaning-up-history]]
-== Rewriting history and maintaining patch series
+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
@@ -2406,7 +2470,8 @@ However, there is a situation in which it can be useful to violate this
 assumption.
 
 [[patch-series]]
-=== Creating the perfect 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
@@ -2438,7 +2503,8 @@ 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
+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:
@@ -2525,7 +2591,8 @@ the rebase.  See <<interactive-rebase>> for details, and
 <<reordering-patch-series>> for alternatives.
 
 [[rewriting-one-commit]]
-=== Rewriting a single commit
+Rewriting a single commit
+-------------------------
 
 We saw in <<fixing-a-mistake-by-rewriting-history>> that you can replace the
 most recent commit using
@@ -2543,7 +2610,8 @@ 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
+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
@@ -2562,7 +2630,8 @@ $ git am *.patch
 -------------------------------------------------
 
 [[interactive-rebase]]
-=== Using interactive rebases
+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
@@ -2619,14 +2688,16 @@ 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
+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
+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
@@ -2674,7 +2745,8 @@ 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
+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
@@ -2739,10 +2811,12 @@ linear by rebasing against the latest upstream version before
 publishing.
 
 [[advanced-branch-management]]
-== Advanced branch management
+Advanced branch management
+==========================
 
 [[fetching-individual-branches]]
-=== 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
@@ -2770,7 +2844,8 @@ already have a branch named example-master, it will attempt to
 master branch.  In more detail:
 
 [[fetch-fast-forwards]]
-=== git fetch and 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
@@ -2807,7 +2882,8 @@ unless you've already created a reference of your own pointing to
 them.
 
 [[forcing-fetch]]
-=== Forcing git fetch to do non-fast-forward updates
+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:
@@ -2827,7 +2903,8 @@ 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
+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
@@ -2878,7 +2955,8 @@ the refspec syntax.
 
 
 [[git-concepts]]
-== 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
@@ -2888,7 +2966,8 @@ We start with the most important, the  <<def_object_database,object
 database>> and the <<def_index,index>>.
 
 [[the-object-database]]
-=== The Object Database
+The Object Database
+-------------------
 
 
 We already saw in <<understanding-commits>> that all commits are stored
@@ -2932,7 +3011,8 @@ There are four different types of objects: "blob", "tree", "commit", and
 The object types in some more detail:
 
 [[commit-object]]
-==== 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
@@ -2984,7 +3064,8 @@ 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
+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
@@ -3023,7 +3104,8 @@ Note that the files all have mode 644 or 755: Git actually only pays
 attention to the executable bit.
 
 [[blob-object]]
-==== 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:
@@ -3052,7 +3134,8 @@ sometimes be useful for browsing the contents of a tree that is not
 currently checked out.
 
 [[trust]]
-==== 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
@@ -3081,7 +3164,8 @@ like GPG/PGP.
 To assist in this, Git also provides the tag object...
 
 [[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
@@ -3110,7 +3194,8 @@ objects.  (Note that linkgit:git-tag[1] can also be used to create
 references whose names begin with `refs/tags/`).
 
 [[pack-files]]
-==== How Git stores objects efficiently: 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`).
@@ -3168,7 +3253,8 @@ 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
+Dangling objects
+~~~~~~~~~~~~~~~~
 
 The linkgit:git-fsck[1] command will sometimes complain about dangling
 objects.  They are not a problem.
@@ -3248,7 +3334,8 @@ don't want to do that while the filesystem is mounted.
 accesses to a repository but you might receive confusing or scary messages.)
 
 [[recovering-from-repository-corruption]]
-==== 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
@@ -3365,7 +3452,8 @@ 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
+---------
 
 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
@@ -3423,7 +3511,8 @@ 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
+Submodules
+==========
 
 Large projects are often composed of smaller, self-contained modules.  For
 example, an embedded Linux distribution's source tree would include every
@@ -3609,8 +3698,8 @@ $ 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
+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,
@@ -3679,7 +3768,8 @@ 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
+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
@@ -3687,7 +3777,8 @@ be useful when doing unusual things with Git, or just as a way to
 understand its inner workings.
 
 [[object-manipulation]]
-=== Object access and 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.
@@ -3704,7 +3795,8 @@ verified by linkgit:git-verify-tag[1], though it is normally simpler to
 use linkgit:git-tag[1] for both.
 
 [[the-workflow]]
-=== The Workflow
+The Workflow
+------------
 
 High-level operations such as linkgit:git-commit[1] and
 linkgit:git-restore[1] work by moving data
@@ -3719,7 +3811,8 @@ the database or the working directory. Thus there are four main
 combinations:
 
 [[working-directory-to-index]]
-==== working directory -> index
+working directory -> index
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The linkgit:git-update-index[1] command updates the index with
 information from the working directory.  You generally update the
@@ -3755,7 +3848,8 @@ The previously introduced linkgit:git-add[1] is just a wrapper for
 linkgit:git-update-index[1].
 
 [[index-to-object-database]]
-==== index -> object database
+index -> object database
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 You write your current index file to a "tree" object with the program
 
@@ -3770,7 +3864,8 @@ use that tree to re-generate the index at any time by going in the
 other direction:
 
 [[object-database-to-index]]
-==== object database -> 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
@@ -3786,7 +3881,8 @@ earlier. However, that is only your 'index' file: your working
 directory contents have not been modified.
 
 [[index-to-working-directory]]
-==== index -> 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
@@ -3815,7 +3911,8 @@ 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
+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
@@ -3889,7 +3986,8 @@ Here is a picture that illustrates how various pieces fit together:
 
 
 [[examining-the-data]]
-=== 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
@@ -3924,7 +4022,8 @@ $ git cat-file commit HEAD
 to see what the top commit was.
 
 [[merging-multiple-trees]]
-=== 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
@@ -3974,7 +4073,8 @@ index file, and you can just write the result out with
 
 
 [[merging-multiple-trees-2]]
-=== Merging multiple trees, continued
+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
@@ -4044,13 +4144,15 @@ $ 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
+Hacking Git
+===========
 
 This chapter covers internal details of the Git implementation which
 probably only Git developers need to understand.
 
 [[object-details]]
-=== Object storage format
+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
@@ -4080,7 +4182,8 @@ 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
+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
@@ -4289,22 +4392,25 @@ You see, Git is actually the best tool to find out about the source of Git
 itself!
 
 [[glossary]]
-== Git Glossary
+Git Glossary
+============
 
 [[git-explained]]
-=== Git explained
+Git explained
+-------------
 
 include::glossary-content.txt[]
 
 [[git-quick-start]]
-[appendix]
-== Git Quick Reference
+Appendix A: 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
+Creating a new repository
+-------------------------
 
 From a tarball:
 
@@ -4325,7 +4431,8 @@ $ cd project
 -----------------------------------------------
 
 [[managing-branches]]
-=== Managing branches
+Managing branches
+-----------------
 
 -----------------------------------------------
 $ git branch			# list all local branches in this repo
@@ -4389,7 +4496,8 @@ $ git branch -r			# list all remote branches
 
 
 [[exploring-history]]
-=== Exploring history
+Exploring history
+-----------------
 
 -----------------------------------------------
 $ gitk			    # visualize and browse history
@@ -4424,7 +4532,8 @@ $ git bisect bad		# if this revision is bad.
 -----------------------------------------------
 
 [[making-changes]]
-=== Making changes
+Making changes
+--------------
 
 Make sure Git knows who to blame:
 
@@ -4454,7 +4563,8 @@ $ git commit -a	   # use latest content of all tracked files
 -----------------------------------------------
 
 [[merging]]
-=== Merging
+Merging
+-------
 
 -----------------------------------------------
 $ git merge test   # merge branch "test" into the current branch
@@ -4464,7 +4574,8 @@ $ git pull . test  # equivalent to git merge test
 -----------------------------------------------
 
 [[sharing-your-changes]]
-=== Sharing your changes
+Sharing your changes
+--------------------
 
 Importing or exporting patches:
 
@@ -4509,7 +4620,8 @@ $ git push example test
 -----------------------------------------------
 
 [[repository-maintenance]]
-=== Repository maintenance
+Repository maintenance
+----------------------
 
 Check for corruption:
 
@@ -4525,11 +4637,12 @@ $ git gc
 
 
 [[todo]]
-[appendix]
-== Notes and todo list for this manual
+Appendix B: Notes and todo list for this manual
+===============================================
 
 [[todo-list]]
-=== Todo list
+Todo list
+---------
 
 This is a work in progress.
 
@@ -4574,5 +4687,5 @@ 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/
+	http://marc.info/?l=git&m=117263864820799&w=2
+	http://marc.info/?l=git&m=117147855503798&w=2