Autogenerated HTML docs for v2.31.1-298-g54a39

22 files changed, 91 insertions, 18 deletions

diff --git a/RelNotes/2.32.0.txt b/RelNotes/2.32.0.txt
index 5c329d5a1..8670b7343 100644
--- a/RelNotes/2.32.0.txt
+++ b/RelNotes/2.32.0.txt
@@ -57,6 +57,11 @@ UI, Workflows & Features
  * "git clone --reject-shallow" option fails the clone as soon as we
    notice that we are cloning from a shallow repository.
 
+ * A configuration variable has been added to force tips of certain
+   refs to be given a reachability bitmap.
+
+ * "gitweb" learned "e-mail privacy" feature to redact strings that
+   look like e-mail addresses on various pages.
 
 
 Performance, Internal Implementation, Development Support etc.
@@ -98,6 +103,11 @@ Performance, Internal Implementation, Development Support etc.
 
  * Generate [ec]tags under $(QUIET_GEN).
 
+ * Clean-up codepaths that implements "git send-email --validate"
+   option and improves the message from it.
+
+ * The last remnant of gettext-poison has been removed.
+
 
 Fixes since v2.31
 -----------------
@@ -174,6 +184,19 @@ Fixes since v2.31
    as directory separator.
    (merge 9a7f1ce8b7 rs/daemon-sanitize-dir-sep later to maint).
 
+ * A NULL-dereference bug has been corrected in an error codepath in
+   "git for-each-ref", "git branch --list" etc.
+   (merge c685450880 jk/ref-filter-segfault-fix later to maint).
+
+ * Streamline the codepath to fix the UTF-8 encoding issues in the
+   argv[] and the prefix on macOS.
+   (merge c7d0e61016 tb/precompose-prefix-simplify later to maint).
+
+ * The command-line completion script (in contrib/) had a couple of
+   references that would have given a warning under the "-u" (nounset)
+   option.
+   (merge c5c0548d79 vs/completion-with-set-u later to maint).
+
  * Other code cleanup, docfix, build fix, etc.
    (merge f451960708 dl/cat-file-doc-cleanup later to maint).
    (merge 12604a8d0c sv/t9801-test-path-is-file-cleanup later to maint).
@@ -186,3 +209,5 @@ Fixes since v2.31
    (merge 2be927f3d1 ab/diff-no-index-tests later to maint).
    (merge 76593c09bb ab/detox-gettext-tests later to maint).
    (merge 28e29ee38b jc/doc-format-patch-clarify later to maint).
+   (merge fc12b6fdde fm/user-manual-use-preface later to maint).
+   (merge dba94e3a85 cc/test-helper-bloom-usage-fix later to maint).
diff --git a/git-config.html b/git-config.html
index 0fae21f63..9b29bc85a 100644
--- a/git-config.html
+++ b/git-config.html
@@ -8023,6 +8023,24 @@ pack.useSparse
 </p>

 </dd>

 <dt class="hdlist1">

+pack.preferBitmapTips

+</dt>

+<dd>

+<p>

+        When selecting which commits will receive bitmaps, prefer a

+        commit at the tip of any reference that is a suffix of any value

+        of this configuration over any other commits in the "selection

+        window".

+</p>

+<div class="paragraph"><p>Note that setting this configuration to <code>refs/foo</code> does not mean that

+the commits at the tips of <code>refs/foo/bar</code> and <code>refs/foo/baz</code> will

+necessarily be selected. This is because commits are selected for

+bitmaps from within a series of windows of variable length.</p></div>

+<div class="paragraph"><p>If a commit at the tip of any reference which is a suffix of any value

+of this configuration is seen in a window, it is immediately given

+preference over any other commit in that window.</p></div>

+</dd>

+<dt class="hdlist1">

 pack.writeBitmaps (deprecated)

 </dt>

 <dd>

diff --git a/gitweb.conf.html b/gitweb.conf.html
index 1de75df68..bdf9d94e8 100644
--- a/gitweb.conf.html
+++ b/gitweb.conf.html
@@ -1704,6 +1704,22 @@ CSS stylesheet in <code>@stylesheets</code>), it may be appropriate to change
 these values.</p></div>

 </dd>

 <dt class="hdlist1">

+email-privacy

+</dt>

+<dd>

+<p>

+        Redact e-mail addresses from the generated HTML, etc. content.

+        This obscures e-mail addresses retrieved from the author/committer

+        and comment sections of the Git log.

+        It is meant to hinder web crawlers that harvest and abuse addresses.

+        Such crawlers may not respect robots.txt.

+        Note that users and user tools also see the addresses as redacted.

+        If Gitweb is not the final step in a workflow then subsequent steps

+        may misbehave because of the redacted information they receive.

+        Disabled by default.

+</p>

+</dd>

+<dt class="hdlist1">

 highlight

 </dt>

 <dd>

@@ -1999,7 +2015,7 @@ gitweb_config.perl
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2020-03-10 08:03:13 PDT

+ 2021-04-13 17:34:18 PDT

 </div>

 </div>

 </body>

diff --git a/gitweb.conf.txt b/gitweb.conf.txt
index 7963a79ba..34b1d6e22 100644
--- a/gitweb.conf.txt
+++ b/gitweb.conf.txt
@@ -751,6 +751,17 @@ default font sizes or lineheights are changed (e.g. via adding extra
 CSS stylesheet in `@stylesheets`), it may be appropriate to change
 these values.
 
+email-privacy::
+	Redact e-mail addresses from the generated HTML, etc. content.
+	This obscures e-mail addresses retrieved from the author/committer
+	and comment sections of the Git log.
+	It is meant to hinder web crawlers that harvest and abuse addresses.
+	Such crawlers may not respect robots.txt.
+	Note that users and user tools also see the addresses as redacted.
+	If Gitweb is not the final step in a workflow then subsequent steps
+	may misbehave because of the redacted information they receive.
+	Disabled by default.
+
 highlight::
 	Server-side syntax highlight support in "blob" view.  It requires
 	`$highlight_bin` program to be available (see the description of
diff --git a/howto/coordinate-embargoed-releases.html b/howto/coordinate-embargoed-releases.html
index c0c4c5800..02dd18cdc 100644
--- a/howto/coordinate-embargoed-releases.html
+++ b/howto/coordinate-embargoed-releases.html
@@ -873,7 +873,7 @@ Thanks,
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2021-04-08 14:46:59 PDT

+ 2021-04-13 17:35:18 PDT

 </div>

 </div>

 </body>

diff --git a/howto/keep-canonical-history-correct.html b/howto/keep-canonical-history-correct.html
index c4bbc0a10..310efd5f9 100644
--- a/howto/keep-canonical-history-correct.html
+++ b/howto/keep-canonical-history-correct.html
@@ -938,7 +938,7 @@ tip of your <em>master</em> again and redo the two merges:</p></div>
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2021-04-08 14:46:58 PDT

+ 2021-04-13 17:35:17 PDT

 </div>

 </div>

 </body>

diff --git a/howto/maintain-git.html b/howto/maintain-git.html
index 03add9c10..b2013dc4d 100644
--- a/howto/maintain-git.html
+++ b/howto/maintain-git.html
@@ -1469,7 +1469,7 @@ $ git update-ref -d $mf/ai/topic</code></pre>
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2021-04-08 14:46:58 PDT

+ 2021-04-13 17:35:18 PDT

 </div>

 </div>

 </body>

diff --git a/howto/new-command.html b/howto/new-command.html
index 15e191bfd..ce3beff3c 100644
--- a/howto/new-command.html
+++ b/howto/new-command.html
@@ -863,7 +863,7 @@ letter [PATCH 0/n].
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2021-04-08 14:46:52 PDT

+ 2021-04-13 17:35:14 PDT

 </div>

 </div>

 </body>

diff --git a/howto/rebase-from-internal-branch.html b/howto/rebase-from-internal-branch.html
index 0023dbd9d..a16335e7d 100644
--- a/howto/rebase-from-internal-branch.html
+++ b/howto/rebase-from-internal-branch.html
@@ -895,7 +895,7 @@ the #1' commit.</p></div>
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2021-04-08 14:46:58 PDT

+ 2021-04-13 17:35:17 PDT

 </div>

 </div>

 </body>

diff --git a/howto/rebuild-from-update-hook.html b/howto/rebuild-from-update-hook.html
index bc623ca9e..3a0814923 100644
--- a/howto/rebuild-from-update-hook.html
+++ b/howto/rebuild-from-update-hook.html
@@ -847,7 +847,7 @@ This is still crude and does not protect against simultaneous
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2021-04-08 14:46:58 PDT

+ 2021-04-13 17:35:17 PDT

 </div>

 </div>

 </body>

diff --git a/howto/recover-corrupted-blob-object.html b/howto/recover-corrupted-blob-object.html
index 8a574112d..ba2ad9bc4 100644
--- a/howto/recover-corrupted-blob-object.html
+++ b/howto/recover-corrupted-blob-object.html
@@ -880,7 +880,7 @@ thing.</p></div>
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2021-04-08 14:46:57 PDT

+ 2021-04-13 17:35:17 PDT

 </div>

 </div>

 </body>

diff --git a/howto/recover-corrupted-object-harder.html b/howto/recover-corrupted-object-harder.html
index 106837cce..3873cb480 100644
--- a/howto/recover-corrupted-object-harder.html
+++ b/howto/recover-corrupted-object-harder.html
@@ -1189,7 +1189,7 @@ int main(int argc, char **argv)
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2021-04-08 14:46:57 PDT

+ 2021-04-13 17:35:17 PDT

 </div>

 </div>

 </body>

diff --git a/howto/revert-a-faulty-merge.html b/howto/revert-a-faulty-merge.html
index b54997cba..69d09a70c 100644
--- a/howto/revert-a-faulty-merge.html
+++ b/howto/revert-a-faulty-merge.html
@@ -1025,7 +1025,7 @@ P---o---o---M---x---x---W---x---M2
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2021-04-08 14:46:56 PDT

+ 2021-04-13 17:35:16 PDT

 </div>

 </div>

 </body>

diff --git a/howto/revert-branch-rebase.html b/howto/revert-branch-rebase.html
index 611838691..82f52a98f 100644
--- a/howto/revert-branch-rebase.html
+++ b/howto/revert-branch-rebase.html
@@ -907,7 +907,7 @@ Committed merge 7fb9b7262a1d1e0a47bbfdcbbcf50ce0635d3f8f
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2021-04-08 14:46:53 PDT

+ 2021-04-13 17:35:14 PDT

 </div>

 </div>

 </body>

diff --git a/howto/separating-topic-branches.html b/howto/separating-topic-branches.html
index 348449c93..6b2191edf 100644
--- a/howto/separating-topic-branches.html
+++ b/howto/separating-topic-branches.html
@@ -841,7 +841,7 @@ o---o"master"</code></pre>
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2021-04-08 14:46:56 PDT

+ 2021-04-13 17:35:16 PDT

 </div>

 </div>

 </body>

diff --git a/howto/setup-git-server-over-http.html b/howto/setup-git-server-over-http.html
index 68595e847..67a327f73 100644
--- a/howto/setup-git-server-over-http.html
+++ b/howto/setup-git-server-over-http.html
@@ -1071,7 +1071,7 @@ help diagnosing the problem, but removes security checks.</p></div>
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2021-04-08 14:46:55 PDT

+ 2021-04-13 17:35:15 PDT

 </div>

 </div>

 </body>

diff --git a/howto/update-hook-example.html b/howto/update-hook-example.html
index 171ffb6df..de14b8672 100644
--- a/howto/update-hook-example.html
+++ b/howto/update-hook-example.html
@@ -930,7 +930,7 @@ that JC can make non-fast-forward pushes on it.</p></div>
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2021-04-08 14:46:54 PDT

+ 2021-04-13 17:35:15 PDT

 </div>

 </div>

 </body>

diff --git a/howto/use-git-daemon.html b/howto/use-git-daemon.html
index 355caf871..74eb4f181 100644
--- a/howto/use-git-daemon.html
+++ b/howto/use-git-daemon.html
@@ -791,7 +791,7 @@ a good practice to put the paths after a "--" separator.</p></div>
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2021-04-08 14:46:54 PDT

+ 2021-04-13 17:35:15 PDT

 </div>

 </div>

 </body>

diff --git a/howto/using-merge-subtree.html b/howto/using-merge-subtree.html
index bf5df5260..4ef2e908a 100644
--- a/howto/using-merge-subtree.html
+++ b/howto/using-merge-subtree.html
@@ -848,7 +848,7 @@ Please note that if the other project merges from you, then it will
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2021-04-08 14:46:53 PDT

+ 2021-04-13 17:35:14 PDT

 </div>

 </div>

 </body>

diff --git a/howto/using-signed-tag-in-pull-request.html b/howto/using-signed-tag-in-pull-request.html
index edee97796..f6dbfefe2 100644
--- a/howto/using-signed-tag-in-pull-request.html
+++ b/howto/using-signed-tag-in-pull-request.html
@@ -952,7 +952,7 @@ as part of the merge commit.</p></div>
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2021-04-08 14:46:53 PDT

+ 2021-04-13 17:35:14 PDT

 </div>

 </div>

 </body>

diff --git a/user-manual.html b/user-manual.html
index c60f4e415..90da315bf 100644
--- a/user-manual.html
+++ b/user-manual.html
@@ -1,5 +1,5 @@
 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Git User Manual</title><link rel="stylesheet" type="text/css" href="docbook-xsl.css"><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div lang="en" class="book"><div class="titlepage"><div><div><h1 class="title"><a name="id-1"></a>Git User Manual</h1></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="preface"><a href="#id-1.2"></a></span></dt><dt><span class="chapter"><a href="#repositories-and-branches">1. Repositories and Branches</a></span></dt><dd><dl><dt><span class="section"><a href="#how-to-get-a-git-repository">How to get a Git repository</a></span></dt><dt><span class="section"><a href="#how-to-check-out">How to check out a different version of a project</a></span></dt><dt><span class="section"><a href="#understanding-commits">Understanding History: Commits</a></span></dt><dd><dl><dt><span class="section"><a href="#understanding-reachability">Understanding history: commits, parents, and reachability</a></span></dt><dt><span class="section"><a href="#history-diagrams">Understanding history: History diagrams</a></span></dt><dt><span class="section"><a href="#what-is-a-branch">Understanding history: What is a branch?</a></span></dt></dl></dd><dt><span class="section"><a href="#manipulating-branches">Manipulating branches</a></span></dt><dt><span class="section"><a href="#detached-head">Examining an old version without creating a new branch</a></span></dt><dt><span class="section"><a href="#examining-remote-branches">Examining branches from a remote repository</a></span></dt><dt><span class="section"><a href="#how-git-stores-references">Naming branches, tags, and other references</a></span></dt><dt><span class="section"><a href="#Updating-a-repository-With-git-fetch">Updating a repository with git fetch</a></span></dt><dt><span class="section"><a href="#fetching-branches">Fetching branches from other repositories</a></span></dt></dl></dd><dt><span class="chapter"><a href="#exploring-git-history">2. Exploring Git history</a></span></dt><dd><dl><dt><span class="section"><a href="#using-bisect">How to use bisect to find a regression</a></span></dt><dt><span class="section"><a href="#naming-commits">Naming commits</a></span></dt><dt><span class="section"><a href="#creating-tags">Creating tags</a></span></dt><dt><span class="section"><a href="#browsing-revisions">Browsing revisions</a></span></dt><dt><span class="section"><a href="#generating-diffs">Generating diffs</a></span></dt><dt><span class="section"><a href="#viewing-old-file-versions">Viewing old file versions</a></span></dt><dt><span class="section"><a href="#history-examples">Examples</a></span></dt><dd><dl><dt><span class="section"><a href="#counting-commits-on-a-branch">Counting the number of commits on a branch</a></span></dt><dt><span class="section"><a href="#checking-for-equal-branches">Check whether two branches point at the same history</a></span></dt><dt><span class="section"><a href="#finding-tagged-descendants">Find first tagged version including a given fix</a></span></dt><dt><span class="section"><a href="#showing-commits-unique-to-a-branch">Showing commits unique to a given branch</a></span></dt><dt><span class="section"><a href="#making-a-release">Creating a changelog and tarball for a software release</a></span></dt><dt><span class="section"><a href="#Finding-commits-With-given-Content">Finding commits referencing a file with given content</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#Developing-With-git">3. Developing with Git</a></span></dt><dd><dl><dt><span class="section"><a href="#telling-git-your-name">Telling Git your name</a></span></dt><dt><span class="section"><a href="#creating-a-new-repository">Creating a new repository</a></span></dt><dt><span class="section"><a href="#how-to-make-a-commit">How to make a commit</a></span></dt><dt><span class="section"><a href="#creating-good-commit-messages">Creating good commit messages</a></span></dt><dt><span class="section"><a href="#ignoring-files">Ignoring files</a></span></dt><dt><span class="section"><a href="#how-to-merge">How to merge</a></span></dt><dt><span class="section"><a href="#resolving-a-merge">Resolving a merge</a></span></dt><dd><dl><dt><span class="section"><a href="#conflict-resolution">Getting conflict-resolution help during a merge</a></span></dt></dl></dd><dt><span class="section"><a href="#undoing-a-merge">Undoing a merge</a></span></dt><dt><span class="section"><a href="#fast-forwards">Fast-forward merges</a></span></dt><dt><span class="section"><a href="#fixing-mistakes">Fixing mistakes</a></span></dt><dd><dl><dt><span class="section"><a href="#reverting-a-commit">Fixing a mistake with a new commit</a></span></dt><dt><span class="section"><a href="#fixing-a-mistake-by-rewriting-history">Fixing a mistake by rewriting history</a></span></dt><dt><span class="section"><a href="#checkout-of-path">Checking out an old version of a file</a></span></dt><dt><span class="section"><a href="#interrupted-work">Temporarily setting aside work in progress</a></span></dt></dl></dd><dt><span class="section"><a href="#ensuring-good-performance">Ensuring good performance</a></span></dt><dt><span class="section"><a href="#ensuring-reliability">Ensuring reliability</a></span></dt><dd><dl><dt><span class="section"><a href="#checking-for-corruption">Checking the repository for corruption</a></span></dt><dt><span class="section"><a href="#recovering-lost-changes">Recovering lost changes</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#sharing-development">4. Sharing development with others</a></span></dt><dd><dl><dt><span class="section"><a href="#getting-updates-With-git-pull">Getting updates with git pull</a></span></dt><dt><span class="section"><a href="#submitting-patches">Submitting patches to a project</a></span></dt><dt><span class="section"><a href="#importing-patches">Importing patches to a project</a></span></dt><dt><span class="section"><a href="#public-repositories">Public Git repositories</a></span></dt><dd><dl><dt><span class="section"><a href="#setting-up-a-public-repository">Setting up a public repository</a></span></dt><dt><span class="section"><a href="#exporting-via-git">Exporting a Git repository via the Git protocol</a></span></dt><dt><span class="section"><a href="#exporting-via-http">Exporting a git repository via HTTP</a></span></dt><dt><span class="section"><a href="#pushing-changes-to-a-public-repository">Pushing changes to a public repository</a></span></dt><dt><span class="section"><a href="#forcing-push">What to do when a push fails</a></span></dt><dt><span class="section"><a href="#setting-up-a-shared-repository">Setting up a shared repository</a></span></dt><dt><span class="section"><a href="#setting-up-gitweb">Allowing web browsing of a repository</a></span></dt></dl></dd><dt><span class="section"><a href="#how-to-get-a-git-repository-with-minimal-history">How to get a Git repository with minimal history</a></span></dt><dt><span class="section"><a href="#sharing-development-examples">Examples</a></span></dt><dd><dl><dt><span class="section"><a href="#maintaining-topic-branches">Maintaining topic branches for a Linux subsystem maintainer</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#cleaning-up-history">5. Rewriting history and maintaining patch series</a></span></dt><dd><dl><dt><span class="section"><a href="#patch-series">Creating the perfect patch series</a></span></dt><dt><span class="section"><a href="#using-git-rebase">Keeping a patch series up to date using git rebase</a></span></dt><dt><span class="section"><a href="#rewriting-one-commit">Rewriting a single commit</a></span></dt><dt><span class="section"><a href="#reordering-patch-series">Reordering or selecting from a patch series</a></span></dt><dt><span class="section"><a href="#interactive-rebase">Using interactive rebases</a></span></dt><dt><span class="section"><a href="#patch-series-tools">Other tools</a></span></dt><dt><span class="section"><a href="#problems-With-rewriting-history">Problems with rewriting history</a></span></dt><dt><span class="section"><a href="#bisect-merges">Why bisecting merge commits can be harder than bisecting linear history</a></span></dt></dl></dd><dt><span class="chapter"><a href="#advanced-branch-management">6. Advanced branch management</a></span></dt><dd><dl><dt><span class="section"><a href="#fetching-individual-branches">Fetching individual branches</a></span></dt><dt><span class="section"><a href="#fetch-fast-forwards">git fetch and fast-forwards</a></span></dt><dt><span class="section"><a href="#forcing-fetch">Forcing git fetch to do non-fast-forward updates</a></span></dt><dt><span class="section"><a href="#remote-branch-configuration">Configuring remote-tracking branches</a></span></dt></dl></dd><dt><span class="chapter"><a href="#git-concepts">7. Git concepts</a></span></dt><dd><dl><dt><span class="section"><a href="#the-object-database">The Object Database</a></span></dt><dd><dl><dt><span class="section"><a href="#commit-object">Commit Object</a></span></dt><dt><span class="section"><a href="#tree-object">Tree Object</a></span></dt><dt><span class="section"><a href="#blob-object">Blob Object</a></span></dt><dt><span class="section"><a href="#trust">Trust</a></span></dt><dt><span class="section"><a href="#tag-object">Tag Object</a></span></dt><dt><span class="section"><a href="#pack-files">How Git stores objects efficiently: pack files</a></span></dt><dt><span class="section"><a href="#dangling-objects">Dangling objects</a></span></dt><dt><span class="section"><a href="#recovering-from-repository-corruption">Recovering from repository corruption</a></span></dt></dl></dd><dt><span class="section"><a href="#the-index">The index</a></span></dt></dl></dd><dt><span class="chapter"><a href="#submodules">8. Submodules</a></span></dt><dd><dl><dt><span class="section"><a href="#pitfalls-with-submodules">Pitfalls with submodules</a></span></dt></dl></dd><dt><span class="chapter"><a href="#low-level-operations">9. Low-level Git operations</a></span></dt><dd><dl><dt><span class="section"><a href="#object-manipulation">Object access and manipulation</a></span></dt><dt><span class="section"><a href="#the-workflow">The Workflow</a></span></dt><dd><dl><dt><span class="section"><a href="#working-directory-to-index">working directory → index</a></span></dt><dt><span class="section"><a href="#index-to-object-database">index → object database</a></span></dt><dt><span class="section"><a href="#object-database-to-index">object database → index</a></span></dt><dt><span class="section"><a href="#index-to-working-directory">index → working directory</a></span></dt><dt><span class="section"><a href="#tying-it-all-together">Tying it all together</a></span></dt></dl></dd><dt><span class="section"><a href="#examining-the-data">Examining the data</a></span></dt><dt><span class="section"><a href="#merging-multiple-trees">Merging multiple trees</a></span></dt><dt><span class="section"><a href="#merging-multiple-trees-2">Merging multiple trees, continued</a></span></dt></dl></dd><dt><span class="chapter"><a href="#hacking-git">10. Hacking Git</a></span></dt><dd><dl><dt><span class="section"><a href="#object-details">Object storage format</a></span></dt><dt><span class="section"><a href="#birdview-on-the-source-code">A birds-eye view of Git’s source code</a></span></dt></dl></dd><dt><span class="chapter"><a href="#glossary">11. Git Glossary</a></span></dt><dd><dl><dt><span class="section"><a href="#git-explained">Git explained</a></span></dt></dl></dd><dt><span class="appendix"><a href="#git-quick-start">A. Git Quick Reference</a></span></dt><dd><dl><dt><span class="section"><a href="#quick-creating-a-new-repository">Creating a new repository</a></span></dt><dt><span class="section"><a href="#managing-branches">Managing branches</a></span></dt><dt><span class="section"><a href="#exploring-history">Exploring history</a></span></dt><dt><span class="section"><a href="#making-changes">Making changes</a></span></dt><dt><span class="section"><a href="#merging">Merging</a></span></dt><dt><span class="section"><a href="#sharing-your-changes">Sharing your changes</a></span></dt><dt><span class="section"><a href="#repository-maintenance">Repository maintenance</a></span></dt></dl></dd><dt><span class="appendix"><a href="#todo">B. Notes and todo list for this manual</a></span></dt><dd><dl><dt><span class="section"><a href="#todo-list">Todo list</a></span></dt></dl></dd></dl></div><div class="preface"><div class="titlepage"><div><div><h1 class="title"><a name="id-1.2"></a></h1></div></div></div><p>Git is a fast distributed revision control system.</p><p>This manual is designed to be readable by someone with basic UNIX
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Git User Manual</title><link rel="stylesheet" type="text/css" href="docbook-xsl.css"><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div lang="en" class="book"><div class="titlepage"><div><div><h1 class="title"><a name="id-1"></a>Git User Manual</h1></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="preface"><a href="#_introduction">Introduction</a></span></dt><dt><span class="chapter"><a href="#repositories-and-branches">1. Repositories and Branches</a></span></dt><dd><dl><dt><span class="section"><a href="#how-to-get-a-git-repository">How to get a Git repository</a></span></dt><dt><span class="section"><a href="#how-to-check-out">How to check out a different version of a project</a></span></dt><dt><span class="section"><a href="#understanding-commits">Understanding History: Commits</a></span></dt><dd><dl><dt><span class="section"><a href="#understanding-reachability">Understanding history: commits, parents, and reachability</a></span></dt><dt><span class="section"><a href="#history-diagrams">Understanding history: History diagrams</a></span></dt><dt><span class="section"><a href="#what-is-a-branch">Understanding history: What is a branch?</a></span></dt></dl></dd><dt><span class="section"><a href="#manipulating-branches">Manipulating branches</a></span></dt><dt><span class="section"><a href="#detached-head">Examining an old version without creating a new branch</a></span></dt><dt><span class="section"><a href="#examining-remote-branches">Examining branches from a remote repository</a></span></dt><dt><span class="section"><a href="#how-git-stores-references">Naming branches, tags, and other references</a></span></dt><dt><span class="section"><a href="#Updating-a-repository-With-git-fetch">Updating a repository with git fetch</a></span></dt><dt><span class="section"><a href="#fetching-branches">Fetching branches from other repositories</a></span></dt></dl></dd><dt><span class="chapter"><a href="#exploring-git-history">2. Exploring Git history</a></span></dt><dd><dl><dt><span class="section"><a href="#using-bisect">How to use bisect to find a regression</a></span></dt><dt><span class="section"><a href="#naming-commits">Naming commits</a></span></dt><dt><span class="section"><a href="#creating-tags">Creating tags</a></span></dt><dt><span class="section"><a href="#browsing-revisions">Browsing revisions</a></span></dt><dt><span class="section"><a href="#generating-diffs">Generating diffs</a></span></dt><dt><span class="section"><a href="#viewing-old-file-versions">Viewing old file versions</a></span></dt><dt><span class="section"><a href="#history-examples">Examples</a></span></dt><dd><dl><dt><span class="section"><a href="#counting-commits-on-a-branch">Counting the number of commits on a branch</a></span></dt><dt><span class="section"><a href="#checking-for-equal-branches">Check whether two branches point at the same history</a></span></dt><dt><span class="section"><a href="#finding-tagged-descendants">Find first tagged version including a given fix</a></span></dt><dt><span class="section"><a href="#showing-commits-unique-to-a-branch">Showing commits unique to a given branch</a></span></dt><dt><span class="section"><a href="#making-a-release">Creating a changelog and tarball for a software release</a></span></dt><dt><span class="section"><a href="#Finding-commits-With-given-Content">Finding commits referencing a file with given content</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#Developing-With-git">3. Developing with Git</a></span></dt><dd><dl><dt><span class="section"><a href="#telling-git-your-name">Telling Git your name</a></span></dt><dt><span class="section"><a href="#creating-a-new-repository">Creating a new repository</a></span></dt><dt><span class="section"><a href="#how-to-make-a-commit">How to make a commit</a></span></dt><dt><span class="section"><a href="#creating-good-commit-messages">Creating good commit messages</a></span></dt><dt><span class="section"><a href="#ignoring-files">Ignoring files</a></span></dt><dt><span class="section"><a href="#how-to-merge">How to merge</a></span></dt><dt><span class="section"><a href="#resolving-a-merge">Resolving a merge</a></span></dt><dd><dl><dt><span class="section"><a href="#conflict-resolution">Getting conflict-resolution help during a merge</a></span></dt></dl></dd><dt><span class="section"><a href="#undoing-a-merge">Undoing a merge</a></span></dt><dt><span class="section"><a href="#fast-forwards">Fast-forward merges</a></span></dt><dt><span class="section"><a href="#fixing-mistakes">Fixing mistakes</a></span></dt><dd><dl><dt><span class="section"><a href="#reverting-a-commit">Fixing a mistake with a new commit</a></span></dt><dt><span class="section"><a href="#fixing-a-mistake-by-rewriting-history">Fixing a mistake by rewriting history</a></span></dt><dt><span class="section"><a href="#checkout-of-path">Checking out an old version of a file</a></span></dt><dt><span class="section"><a href="#interrupted-work">Temporarily setting aside work in progress</a></span></dt></dl></dd><dt><span class="section"><a href="#ensuring-good-performance">Ensuring good performance</a></span></dt><dt><span class="section"><a href="#ensuring-reliability">Ensuring reliability</a></span></dt><dd><dl><dt><span class="section"><a href="#checking-for-corruption">Checking the repository for corruption</a></span></dt><dt><span class="section"><a href="#recovering-lost-changes">Recovering lost changes</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#sharing-development">4. Sharing development with others</a></span></dt><dd><dl><dt><span class="section"><a href="#getting-updates-With-git-pull">Getting updates with git pull</a></span></dt><dt><span class="section"><a href="#submitting-patches">Submitting patches to a project</a></span></dt><dt><span class="section"><a href="#importing-patches">Importing patches to a project</a></span></dt><dt><span class="section"><a href="#public-repositories">Public Git repositories</a></span></dt><dd><dl><dt><span class="section"><a href="#setting-up-a-public-repository">Setting up a public repository</a></span></dt><dt><span class="section"><a href="#exporting-via-git">Exporting a Git repository via the Git protocol</a></span></dt><dt><span class="section"><a href="#exporting-via-http">Exporting a git repository via HTTP</a></span></dt><dt><span class="section"><a href="#pushing-changes-to-a-public-repository">Pushing changes to a public repository</a></span></dt><dt><span class="section"><a href="#forcing-push">What to do when a push fails</a></span></dt><dt><span class="section"><a href="#setting-up-a-shared-repository">Setting up a shared repository</a></span></dt><dt><span class="section"><a href="#setting-up-gitweb">Allowing web browsing of a repository</a></span></dt></dl></dd><dt><span class="section"><a href="#how-to-get-a-git-repository-with-minimal-history">How to get a Git repository with minimal history</a></span></dt><dt><span class="section"><a href="#sharing-development-examples">Examples</a></span></dt><dd><dl><dt><span class="section"><a href="#maintaining-topic-branches">Maintaining topic branches for a Linux subsystem maintainer</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#cleaning-up-history">5. Rewriting history and maintaining patch series</a></span></dt><dd><dl><dt><span class="section"><a href="#patch-series">Creating the perfect patch series</a></span></dt><dt><span class="section"><a href="#using-git-rebase">Keeping a patch series up to date using git rebase</a></span></dt><dt><span class="section"><a href="#rewriting-one-commit">Rewriting a single commit</a></span></dt><dt><span class="section"><a href="#reordering-patch-series">Reordering or selecting from a patch series</a></span></dt><dt><span class="section"><a href="#interactive-rebase">Using interactive rebases</a></span></dt><dt><span class="section"><a href="#patch-series-tools">Other tools</a></span></dt><dt><span class="section"><a href="#problems-With-rewriting-history">Problems with rewriting history</a></span></dt><dt><span class="section"><a href="#bisect-merges">Why bisecting merge commits can be harder than bisecting linear history</a></span></dt></dl></dd><dt><span class="chapter"><a href="#advanced-branch-management">6. Advanced branch management</a></span></dt><dd><dl><dt><span class="section"><a href="#fetching-individual-branches">Fetching individual branches</a></span></dt><dt><span class="section"><a href="#fetch-fast-forwards">git fetch and fast-forwards</a></span></dt><dt><span class="section"><a href="#forcing-fetch">Forcing git fetch to do non-fast-forward updates</a></span></dt><dt><span class="section"><a href="#remote-branch-configuration">Configuring remote-tracking branches</a></span></dt></dl></dd><dt><span class="chapter"><a href="#git-concepts">7. Git concepts</a></span></dt><dd><dl><dt><span class="section"><a href="#the-object-database">The Object Database</a></span></dt><dd><dl><dt><span class="section"><a href="#commit-object">Commit Object</a></span></dt><dt><span class="section"><a href="#tree-object">Tree Object</a></span></dt><dt><span class="section"><a href="#blob-object">Blob Object</a></span></dt><dt><span class="section"><a href="#trust">Trust</a></span></dt><dt><span class="section"><a href="#tag-object">Tag Object</a></span></dt><dt><span class="section"><a href="#pack-files">How Git stores objects efficiently: pack files</a></span></dt><dt><span class="section"><a href="#dangling-objects">Dangling objects</a></span></dt><dt><span class="section"><a href="#recovering-from-repository-corruption">Recovering from repository corruption</a></span></dt></dl></dd><dt><span class="section"><a href="#the-index">The index</a></span></dt></dl></dd><dt><span class="chapter"><a href="#submodules">8. Submodules</a></span></dt><dd><dl><dt><span class="section"><a href="#pitfalls-with-submodules">Pitfalls with submodules</a></span></dt></dl></dd><dt><span class="chapter"><a href="#low-level-operations">9. Low-level Git operations</a></span></dt><dd><dl><dt><span class="section"><a href="#object-manipulation">Object access and manipulation</a></span></dt><dt><span class="section"><a href="#the-workflow">The Workflow</a></span></dt><dd><dl><dt><span class="section"><a href="#working-directory-to-index">working directory → index</a></span></dt><dt><span class="section"><a href="#index-to-object-database">index → object database</a></span></dt><dt><span class="section"><a href="#object-database-to-index">object database → index</a></span></dt><dt><span class="section"><a href="#index-to-working-directory">index → working directory</a></span></dt><dt><span class="section"><a href="#tying-it-all-together">Tying it all together</a></span></dt></dl></dd><dt><span class="section"><a href="#examining-the-data">Examining the data</a></span></dt><dt><span class="section"><a href="#merging-multiple-trees">Merging multiple trees</a></span></dt><dt><span class="section"><a href="#merging-multiple-trees-2">Merging multiple trees, continued</a></span></dt></dl></dd><dt><span class="chapter"><a href="#hacking-git">10. Hacking Git</a></span></dt><dd><dl><dt><span class="section"><a href="#object-details">Object storage format</a></span></dt><dt><span class="section"><a href="#birdview-on-the-source-code">A birds-eye view of Git’s source code</a></span></dt></dl></dd><dt><span class="chapter"><a href="#glossary">11. Git Glossary</a></span></dt><dd><dl><dt><span class="section"><a href="#git-explained">Git explained</a></span></dt></dl></dd><dt><span class="appendix"><a href="#git-quick-start">A. Git Quick Reference</a></span></dt><dd><dl><dt><span class="section"><a href="#quick-creating-a-new-repository">Creating a new repository</a></span></dt><dt><span class="section"><a href="#managing-branches">Managing branches</a></span></dt><dt><span class="section"><a href="#exploring-history">Exploring history</a></span></dt><dt><span class="section"><a href="#making-changes">Making changes</a></span></dt><dt><span class="section"><a href="#merging">Merging</a></span></dt><dt><span class="section"><a href="#sharing-your-changes">Sharing your changes</a></span></dt><dt><span class="section"><a href="#repository-maintenance">Repository maintenance</a></span></dt></dl></dd><dt><span class="appendix"><a href="#todo">B. Notes and todo list for this manual</a></span></dt><dd><dl><dt><span class="section"><a href="#todo-list">Todo list</a></span></dt></dl></dd></dl></div><div class="preface"><div class="titlepage"><div><div><h1 class="title"><a name="_introduction"></a>Introduction</h1></div></div></div><p>Git is a fast distributed revision control system.</p><p>This manual is designed to be readable by someone with basic UNIX
 command-line skills, but no previous knowledge of Git.</p><p><a class="xref" href="#repositories-and-branches" title="Chapter 1. Repositories and Branches">Chapter 1, <i>Repositories and Branches</i></a> and <a class="xref" href="#exploring-git-history" title="Chapter 2. Exploring Git history">Chapter 2, <i>Exploring Git history</i></a> 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
diff --git a/user-manual.txt b/user-manual.txt
index fd480b864..f9e54b867 100644
--- a/user-manual.txt
+++ b/user-manual.txt
@@ -1,5 +1,8 @@
 = 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