[PATCH][GSoC] user-manual.txt: fix empty heading of introduction

[PATCH][GSoC] user-manual.txt: fix empty heading of introduction

[Firmin Martin]

Two among the three warnings raised by "make git.info" are related to the fact
that the introductory heading being empty in user-manual.txt.

    user-manual.texi:15: warning: empty menu entry name in `* : idm4.'
    user-manual.texi:141: warning: @unnumbered missing argument

Recall that the dependencies chain is as follows:

    user-manual.txt => user-manual.xml => user-manual.texi => git.info

Asciidoc creates an empty title tag in user-manual.xml which turns to be an
empty node in user-manual.texi and git.info. This is not negligible in those
files as docbook2x-texi creates a node "idm4" in the menu and the navigation
bar, which can be confusing for the average user: in Emacs, the first entry of
the menu in the git info page is even displayed as empty.

Note that this fix will create an "Introduction" section in the files:
user-manual.{xml, texi, html, pdf} and git.info.

For future reference, here are the content of the relevant & auto-generated files
before this commit.

user-manual.xml:

    l07|<bookinfo>
    l08|<title>Git User Manual</title>
    l09|</bookinfo>
    l10|<preface>
    l11|<title></title>
    l12|<simpara>Git is a fast distributed revision control system.</simpara>

user-manual.texi:

    l10 |@node Top, idm4, , (dir)
    ... |
    l14 |@menu
    l15 |* : idm4.
    ... |
    l140|@node idm4, Repositories and Branches, Top, Top
    l141|@unnumbered
    ... | ...
    l181|@node Repositories and Branches, Exploring Git history, idm4, Top

git.info:

    l10  |File: git.info,  Node: Top,  Next: idm4,  Up: (dir)
    ...  | ...
    l15  |* Menu:
    l16  |
    l17  |* : idm4.
    ...  | ...
    l140 |File: git.info,  Node: idm4,  Next: Repositories and Branches,  Prev: Top,  Up: Top
    ...  | ...
    l177 |File: git.info,  Node: Repositories and Branches,  Next: Exploring Git history,  Prev: idm4,  Up: Top
    ...  | ...
    l5474|Node: idm4\x7f3164

Signed-off-by: Firmin Martin <firminmartin24@gmail.com>
---
 Documentation/user-manual.txt | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index fd480b8645..d708612da2 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1,5 +1,8 @@
 = Git User Manual
 
+[[introduction]]
+== Introduction
+
 Git is a fast distributed revision control system.
 
 This manual is designed to be readable by someone with basic UNIX
-- 
2.31.1.133.g84d06cdc06

Re: [PATCH][GSoC] user-manual.txt: fix empty heading of introduction

[Junio C Hamano]

Firmin Martin <firminmartin24@gmail.com> writes:

> For future reference, here are the content of the relevant & auto-generated files
> before this commit.

I would have expected to see "before and after".  Is it too obvious
what the postimage would be?  Otherwise, a better presentation would
be to show (an excerpt from) diff between preimage and postimage
output.

Thanks.

Re: [PATCH][GSoC] user-manual.txt: fix empty heading of introduction

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> Firmin Martin <firminmartin24@gmail.com> writes:
>
>> For future reference, here are the content of the relevant & auto-generated files
>> before this commit.
>
> I would have expected to see "before and after".  Is it too obvious
> what the postimage would be?  Otherwise, a better presentation would
> be to show (an excerpt from) diff between preimage and postimage
> output.
>
> Thanks.

Another thing to look out for.  I do not think git.info is the only
consumer of user-manual.txt.  Does this change affect the other
consumer, user-manual.html, and if so how?

Re: [PATCH][GSoC] user-manual.txt: fix empty heading of introduction

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> Junio C Hamano <gitster@pobox.com> writes:
>
>> Firmin Martin <firminmartin24@gmail.com> writes:
>>
>>> For future reference, here are the content of the relevant & auto-generated files
>>> before this commit.
>>
>> I would have expected to see "before and after".  Is it too obvious
>> what the postimage would be?  Otherwise, a better presentation would
>> be to show (an excerpt from) diff between preimage and postimage
>> output.
>>
>> Thanks.
>
> Another thing to look out for.  I do not think git.info is the only
> consumer of user-manual.txt.  Does this change affect the other
> consumer, user-manual.html, and if so how?

So, here is what "before and after" of the user-manual.xml output
file looks like.  It shows that the standalone document loses its
Preface and all the chapters have been renumbered (because what was
in the Preface has become the first chapter).

To pages like http://git-scm.com/docs/user-manual that take our
source material and show them in preformatted, this change will
cascade through.  Hopefully these places won't be upset for not
having the Preface (e.g. this particular site does not even refer
to the chapters as "chapter 1", "chapter 2", etc.) but we'd never
know until we try and break them ;-)


--- user-manual-without-patch.xml
+++ user-manual.xml
@@ -7,8 +7,8 @@
 <bookinfo>
     <title>Git User Manual</title>
 </bookinfo>
-<preface>
-<title></title>
+<chapter id="introduction">
+<title>Introduction</title>
 <simpara>Git is a fast distributed revision control system.</simpara>
 <simpara>This manual is designed to be readable by someone with basic UNIX
 command-line skills, but no previous knowledge of Git.</simpara>
@@ -31,7 +31,7 @@ pages, or <ulink url="git-help.html">git-help(1)
 without any explanation.</simpara>
 <simpara>Finally, see <xref linkend="todo"/> for ways that you can help make this manual more
 complete.</simpara>
-</preface>
+</chapter>
 <chapter id="repositories-and-branches">
 <title>Repositories and Branches</title>
 <section id="how-to-get-a-git-repository">

Re: [PATCH][GSoC] user-manual.txt: fix empty heading of introduction

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 645 bytes --]

On 03/04/21 04.22, Junio C Hamano wrote:
> I would have expected to see "before and after".  Is it too obvious
> what the postimage would be?  Otherwise, a better presentation would
> be to show (an excerpt from) diff between preimage and postimage
> output.
> 
> Thanks.
> 
Attached is `diff -u` of generated HTML output, before and after this
patch. The HTML is generated using Asciidoctor.

It seems like from the output, this patch actually add missing header
for intro chapter (in line with title of this patch).

Anyway, thanks.

Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: before-after.diff --]
[-- Type: text/x-patch, Size: 60125 bytes --]

--- user-manual.html	2021-04-03 11:58:44.937710623 +0700
+++ user-manual.patched.html	2021-04-03 12:01:01.634421455 +0700
@@ -1,17 +1,17 @@
 <!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 V1.79.1"></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>
+<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 V1.79.1"></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="chapter"><a href="#introduction">1. Introduction</a></span></dt><dt><span class="chapter"><a href="#repositories-and-branches">2. 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">3. 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">4. 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">5. 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">6. 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">7. 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">8. 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">9. 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">10. 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">11. 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">12. 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>
+<div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="introduction"></a>Chapter 1. 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
+<p><a class="xref" href="#repositories-and-branches" title="Chapter 2. Repositories and Branches">Chapter 2, <i>Repositories 
and Branches</i></a> and <a class="xref" href="#exploring-git-history" title="Chapter 3. Exploring Git history">Chapter 3, <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
 regressions, and so on.</p>
 <p>People needing to do actual development will also want to read
-<a class="xref" href="#Developing-With-git" title="Chapter 3. Developing with Git">Chapter 3, <i>Developing with Git</i></a> 
and <a class="xref" href="#sharing-development" title="Chapter 4. Sharing development with others">Chapter 4, <i>Sharing development with others</i></a>.</p>
+<a class="xref" href="#Developing-With-git" title="Chapter 4. Developing with Git">Chapter 4, <i>Developing with Git</i></a> 
and <a class="xref" href="#sharing-development" title="Chapter 5. Sharing development with others">Chapter 5, <i>Sharing development with others</i></a>.</p>
 <p>Further chapters cover more specialized topics.</p>
 <p>Comprehensive reference documentation is available through the man
 pages, or <a class="ulink" href="git-help.html" target="_top">git-help(1)</a> command.  For example, for the command
@@ -26,7 +26,7 @@
 <p>Finally, see <a class="xref" href="#todo" title="Appendix B. Notes and todo list for this manual">Appendix B, <i>Notes and todo list for this manual</i></a> for ways that you can help make this manual more
 complete.</p>
 </div>
-<div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="repositories-and-branches"></a>Chapter 1. Repositories and Branches</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><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></div>
+<div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="repositories-and-branches"></a>Chapter 2. Repositories and Branches</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><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></div>
 
 <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="how-to-get-a-git-repository"></a>How to get a Git repository</h2></div></div></div>
 
@@ -139,7 +139,7 @@
 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.</p>
-<p>In fact, in <a class="xref" href="#git-concepts" title="Chapter 7. Git concepts">Chapter 7, <i>Git concepts</i></a> we shall see that everything stored in Git
+<p>In fact, in <a class="xref" href="#git-concepts" title="Chapter 8. Git concepts">Chapter 8, <i>Git concepts</i></a> 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.</p>
 <div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="understanding-reachability"></a>Understanding history: commits, parents, and reachability</h3></div></div></div>
@@ -351,7 +351,7 @@
 <a class="ulink" href="git-config.html" target="_top">git-config(1)</a> for details.)</p>
 </div>
 </div>
-<div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="exploring-git-history"></a>Chapter 2. Exploring Git history</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><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></div>
+<div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="exploring-git-history"></a>Chapter 3. Exploring Git history</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><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></div>
 
 <p>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
@@ -679,7 +679,7 @@
 </div>
 </div>
 </div>
-<div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="Developing-With-git"></a>Chapter 3. Developing 
with Git</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><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></div>
+<div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="Developing-With-git"></a>Chapter 4. Developing 
with Git</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><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></div>
 
 <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="telling-git-your-name"></a>Telling 
Git your name</h2></div></div></div>
 
@@ -1023,7 +1023,7 @@
 that case.</p>
 <p>It is also possible to replace commits further back in the history, but
 this is an advanced topic to be left for
-<a class="link" href="#cleaning-up-history" title="Chapter 5. Rewriting history and maintaining patch series">another chapter</a>.</p>
+<a class="link" href="#cleaning-up-history" title="Chapter 6. Rewriting history and maintaining patch series">another chapter</a>.</p>
 </div>
 <div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="checkout-of-path"></a>Checking out an old version of a file</h3></div></div></div>
 
@@ -1155,7 +1155,7 @@
 </div>
 </div>
 </div>
-<div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="sharing-development"></a>Chapter 4. Sharing development with others</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><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></div>
+<div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="sharing-development"></a>Chapter 5. Sharing development with others</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><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></div>
 
 <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="getting-updates-With-git-pull"></a>Getting updates with git pull</h2></div></div></div>
 
@@ -1492,7 +1492,7 @@
 and can be updated using <a class="ulink" href="git-fetch.html" target="_top">git-fetch(1)</a>; you can track other
 public trees using <a class="ulink" href="git-remote.html" target="_top">git-remote(1)</a> to set up a "remote" and
 <a class="ulink" href="git-fetch.html" target="_top">git-fetch(1)</a> to keep them up to date; see
-<a class="xref" href="#repositories-and-branches" title="Chapter 1. Repositories and Branches">Chapter 1, <i>Repositories and 
Branches</i></a>.</p>
+<a class="xref" href="#repositories-and-branches" title="Chapter 2. Repositories and Branches">Chapter 2, <i>Repositories and 
Branches</i></a>.</p>
 <p>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 <code class="literal">--track</code> option to <a class="ulink" href="git-branch.html" target="_top">git-branch(1)</a>) to merge changes in from
@@ -1679,7 +1679,7 @@
 </div>
 </div>
 </div>
-<div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="cleaning-up-history"></a>Chapter 5. Rewriting history and maintaining patch series</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><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></div>
+<div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="cleaning-up-history"></a>Chapter 6. Rewriting history and maintaining patch series</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><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></div>
 
 <p>Normally commits are only added to a project, never taken away or
 replaced.  Git is designed with this assumption, and violating it will
@@ -1923,7 +1923,7 @@
 publishing.</p>
 </div>
 </div>
-<div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="advanced-branch-management"></a>Chapter 6. Advanced branch management</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><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></div>
+<div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="advanced-branch-management"></a>Chapter 7. Advanced branch management</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><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></div>
 
 <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="fetching-individual-branches"></a>Fetching individual branches</h2></div></div></div>
 
@@ -2012,7 +2012,7 @@
 the refspec syntax.</p>
 </div>
 </div>
-<div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="git-concepts"></a>Chapter 7. Git concepts</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><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></div>
+<div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="git-concepts"></a>Chapter 8. Git concepts</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><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></div>
 
 <p>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
@@ -2141,7 +2141,7 @@
 between two related tree objects, since it can ignore any entries with
 identical object names.</p>
 <p>(Note: in the presence of submodules, trees may also have commits as
-entries.  See <a class="xref" href="#submodules" title="Chapter 8. Submodules">Chapter 8, <i>Submodules</i></a> for documentation.)</p>
+entries.  See <a class="xref" href="#submodules" title="Chapter 9. Submodules">Chapter 9, <i>Submodules</i></a> for documentation.)</p>
 <p>Note that the files all have mode 644 or 755: Git actually only pays
 attention to the executable bit.</p>
 </div>
@@ -2258,7 +2258,7 @@
 objects.  They are not a problem.</p>
 <p>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
-<a class="xref" href="#cleaning-up-history" title="Chapter 5. Rewriting history and maintaining patch series">Chapter 5, <i>Rewriting history and maintaining patch series</i></a>.  In that case, the old head of the original
+<a class="xref" href="#cleaning-up-history" title="Chapter 6. Rewriting history and maintaining patch series">Chapter 6, <i>Rewriting history and maintaining patch series</i></a>.  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.</p>
 <p>There are also other situations that cause dangling objects. For
@@ -2437,7 +2437,7 @@
 information as long as you have the name of the tree that it described.</p>
 </div>
 </div>
-<div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="submodules"></a>Chapter 8. Submodules</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#pitfalls-with-submodules">Pitfalls with submodules</a></span></dt></dl></div>
+<div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="submodules"></a>Chapter 9. Submodules</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#pitfalls-with-submodules">Pitfalls with submodules</a></span></dt></dl></div>
 
 <p>Large projects are often composed of smaller, self-contained modules. 
 For
 example, an embedded Linux distribution’s source tree would include every
@@ -2629,7 +2629,7 @@
 warning about not being able switch from a dirty branch.</p>
 </div>
 </div>
-<div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="low-level-operations"></a>Chapter 9. Low-level 
Git operations</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><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></div>
+<div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="low-level-operations"></a>Chapter 10. Low-level Git operations</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><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></div>
 
 <p>Many of the higher-level commands were originally implemented as shell
 scripts using a smaller core of low-level Git commands.  These can still
@@ -2891,7 +2891,7 @@
 <p>and that is what higher level <code class="literal">git merge -s resolve</code> is implemented with.</p>
 </div>
 </div>
-<div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="hacking-git"></a>Chapter 10. Hacking Git</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><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></div>
+<div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="hacking-git"></a>Chapter 11. Hacking Git</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><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></div>
 
 <p>This chapter covers internal details of the Git implementation which
 probably only Git developers need to understand.</p>
@@ -3072,7 +3072,7 @@
 itself!</p>
 </div>
 </div>
-<div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="glossary"></a>Chapter 11. Git Glossary</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#git-explained">Git explained</a></span></dt></dl></div>
+<div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="glossary"></a>Chapter 12. Git Glossary</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#git-explained">Git explained</a></span></dt></dl></div>
 
 <div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="git-explained"></a>Git explained</h2></div></div></div>
 

Re: [PATCH][GSoC] user-manual.txt: fix empty heading of introduction

[Junio C Hamano]

Bagas Sanjaya <bagasdotme@gmail.com> writes:

> On 03/04/21 04.22, Junio C Hamano wrote:
>> I would have expected to see "before and after".  Is it too obvious
>> what the postimage would be?  Otherwise, a better presentation would
>> be to show (an excerpt from) diff between preimage and postimage
>> output.
>> Thanks.
>> 
> Attached is `diff -u` of generated HTML output, before and after this
> patch. The HTML is generated using Asciidoctor.

Unfortunately, that is more-or-less unreadable gunk.  Even for the
first few places that have differences, the output of diff between
raw HTML is not suited to spot that the first entry in the TOC has
changed classs from preface to chapter or how they are treated
differently.

What I did before sending out the message was to generate HTML for
the before and after versions, render them into text and then run
diff on them.  It showed that most changes are the chapter numbering
and cross reference, of course.  This was still hard to see, but at
least it was possible to eyeball what was going on [*].

While Firmin showed only the "before" version of .xml, a diff
between before-and-after versions of .xml turned out to be far
easier to see how the change propagates down the toolchain than
either of the above two.  It would have been  the best to have that,
instead of just the "before" image, in the explanation.

    --- user-manual.xml	2021-04-03 17:36:14.804344928 -0700
    +++ user-manual.xml	2021-04-03 17:36:44.599025868 -0700
    @@ -7,8 +7,8 @@
     <bookinfo>
         <title>Git User Manual</title>
     </bookinfo>
    -<preface>
    -<title></title>
    +<chapter id="introduction">
    +<title>Introduction</title>
     <simpara>Git is a fast distributed revision control system.</simpara>
     <simpara>This manual is designed to be readable by someone with basic UNIX
     command-line skills, but no previous knowledge of Git.</simpara>
    @@ -31,7 +31,7 @@
     without any explanation.</simpara>
     <simpara>Finally, see <xref linkend="todo"/> for ways that you can help make this manual more
     complete.</simpara>
    -</preface>
    +</chapter>
     <chapter id="repositories-and-branches">
     <title>Repositories and Branches</title>
     <section id="how-to-get-a-git-repository">

If an updated version is planned, I'd expect it to come with
something like the above indented patch plus a brief explanation of
side effects (i.e. we lost preface and we have renumbered the
chapters) in its proposed log message.

Thanks.


[Footnote]

* The text-rendered HTML would compare like this (just an excerpt).

--- /var/tmp/before.txt	2021-04-03 17:40:07.777307995 -0700
+++ /var/tmp/after.txt	2021-04-03 17:39:51.423836495 -0700
@@ -4,255 +4,259 @@
 
    Table of Contents
 
-   [1]1. Repositories and Branches
+   [1]1. Introduction
 
-   [2]How to get a Git repository
+   [2]2. Repositories and Branches
 

...

TOC numbering is of course off by one, as the patch promotes the
preface into the first chapter.

...

-   [114]B. Notes and todo list for this manual
+   [116]Todo list
 
-   [115]Todo list
+                            Chapter 1. Introduction
 
...

And of course, we now have the chapter title.

...

    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.
 
-   [116]Chapter 1, Repositories and Branches and [117]Chapter 2, Exploring
+   [117]Chapter 2, Repositories and Branches and [118]Chapter 3, Exploring

...

Cross references are all off-by-one, too.

[PATCH v2 0/1] user-manual.txt: assign preface an id and a title

[Firmin Martin]

I found a more satisfying way to keep the change minimal: it turns out that
[preface] does exactly what we want. It just adds the missing id and the title.
No renumbering, etc.

See https://docs.asciidoctor.org/asciidoc/latest/sections/preface/

I attached the diff of user-manual.xml, user-manual.texi, git.info,
user-manual.html (using html2markdown) and user-manual.pdf (using
pdftotext) in the commit message which I also reworded and shortened.

Firmin Martin (1):
  user-manual.txt: assign preface an id and a title

 Documentation/user-manual.txt | 3 +++
 1 file changed, 3 insertions(+)

-- 
2.31.1.133.g84d06cdc06

[PATCH v2 1/1] user-manual.txt: assign preface an id and a title

[Firmin Martin]

Two among the three warnings raised by "make git.info" are related to the fact
that the preface has not id in user-manual.txt.

    user-manual.texi:15: warning: empty menu entry name in `* : idm4.'
    user-manual.texi:141: warning: @unnumbered missing argument

This causes asciidoc creating an empty preface and an empty title tag in
user-manual.xml which turns to be an empty node in user-manual.texi and
git.info. Consequently, one can notice in user-manual.texi and git.info
a node named "idm4" in the menu and the navigation bar. In emacs, the
first entry of the menu in the git info page is even displayed as empty.

This fix will name "Introduction" the preface and assign it an id.
The result can be seen in the files: user-manual.{xml, texi, html, pdf}
and git.info.

For future reference, the diff between old and new user-manual.xml,
user-manual.texi, git.info, user-manual.html (converted through
html2markdown) and user-manual.pdf (converted through pdftotext) are
attached.

    --- before/user-manual.xml	2021-04-04 03:58:47.758008722 +0200
    +++ after/user-manual.xml	2021-04-04 03:56:40.520551163 +0200
    @@ -7,8 +7,8 @@
     <bookinfo>
         <title>Git User Manual</title>
     </bookinfo>
    -<preface>
    -<title></title>
    +<preface id="_introduction">
    +<title>Introduction</title>
     <simpara>Git is a fast distributed revision control system.</simpara>
     <simpara>This manual is designed to be readable by someone with basic UNIX
     command-line skills, but no previous knowledge of Git.</simpara>

    --- before/user-manual.texi	2021-04-04 03:58:47.490005652 +0200
    +++ after/user-manual.texi	2021-04-04 03:56:40.520551163 +0200
    @@ -7,12 +7,12 @@
     * Git: (git).           A fast distributed revision control system
     @end direntry
     
    -@node Top, idm4, , (dir)
    +@node Top, Introduction, , (dir)
     @documentlanguage en
     @top Git User Manual
     
     @menu
    -* : idm4.
    +* Introduction::
     * Repositories and Branches::
     * Exploring Git history::
     * Developing with Git::
    @@ -137,8 +137,8 @@
     @end detailmenu
     @end menu
     
    -@node idm4, Repositories and Branches, Top, Top
    -@unnumbered 
    +@node Introduction, Repositories and Branches, Top, Top
    +@unnumbered Introduction
     
     Git is a fast distributed revision control system.
     
    @@ -178,7 +178,7 @@
     Finally, see @ref{Notes and todo list for this manual} for ways that you can help make this manual more
     complete.
     
    -@node Repositories and Branches, Exploring Git history, idm4, Top
    +@node Repositories and Branches, Exploring Git history, Introduction, Top
     @chapter Repositories and Branches
     
     @menu
    
    --- before/git.info	2021-04-04 03:58:46.557994966 +0200
    +++ after/git.info	2021-04-04 03:56:40.520551163 +0200
    @@ -7,14 +7,14 @@
     END-INFO-DIR-ENTRY
     
    -File: git.info,  Node: Top,  Next: idm4,  Up: (dir)
    +File: git.info,  Node: Top,  Next: Introduction,  Up: (dir)
     
     Git User Manual
     ***************
     
     * Menu:
     
    -* : idm4.
    +* Introduction::
     * Repositories and Branches::
     * Exploring Git history::
     * Developing with Git::
    @@ -137,7 +137,10 @@
     
     
    -File: git.info,  Node: idm4,  Next: Repositories and Branches,  Prev: Top,  Up: Top
    +File: git.info,  Node: Introduction,  Next: Repositories and Branches,  Prev: Top,  Up: Top
    +
    +Introduction
    +************
     
     Git is a fast distributed revision control system.
     
    @@ -174,7 +177,7 @@
     that you can help make this manual more complete.
     
    -File: git.info,  Node: Repositories and Branches,  Next: Exploring Git history,  Prev: idm4,  Up: Top
    +File: git.info,  Node: Repositories and Branches,  Next: Exploring Git history,  Prev: Introduction,  Up: Top
     
     1 Repositories and Branches
     ***************************
    @@ -5471,207 +5474,207 @@
    ...
     Tag Table:
     Node: Top\x7f212
    -Node: idm4\x7f3164
    -Node: Repositories and Branches\x7f4465
    ...
    +Node: Introduction\x7f3179
    +Node: Repositories and Branches\x7f4515
    +Node: How to get a Git repository\x7f5128
    ...
    End Tag Table
    
    --- before/user-manual.html.md	2021-04-04 05:20:55.378695854 +0200
    +++ after/user-manual.html.md	2021-04-04 05:21:11.282850802 +0200
    @@ -4,6 +4,8 @@
     
      **Table of Contents**
     
    +Introduction
    +
     1\. Repositories and Branches
     
         
    @@ -278,7 +280,7 @@
     
     Todo list
     
    -#
    +# Introduction
     
     Git is a fast distributed revision control system.
     
    --- before/user-manual.pdf.txt	2021-04-04 05:28:20.367036836 +0200
    +++ after/user-manual.pdf.txt	2021-04-04 05:30:01.680026312 +0200
    @@ -487,6 +487,7 @@
     
     vii
     
    +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.
     Chapter 1 and Chapter 2 explain how to fetch and study a project using git—read these chapters to learn how to build and test a

Signed-off-by: Firmin Martin <firminmartin24@gmail.com>
---
 Documentation/user-manual.txt | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index fd480b8645..f9e54b8674 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/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
-- 
2.31.1.133.g84d06cdc06

Re: [PATCH v2 0/1] user-manual.txt: assign preface an id and a title

[Firmin Martin]

The first line of the cover-letter has been eaten because I forgot to
leave an empty line... I wanted to thank Junio and Bagas for their
reviews. I hope I didn't miss anything important.

Thanks,

Firmin

Firmin Martin <firminmartin24@gmail.com> writes:

> I found a more satisfying way to keep the change minimal: it turns out that
> [preface] does exactly what we want. It just adds the missing id and the title.
> No renumbering, etc.
>
> See https://docs.asciidoctor.org/asciidoc/latest/sections/preface/
>
> I attached the diff of user-manual.xml, user-manual.texi, git.info,
> user-manual.html (using html2markdown) and user-manual.pdf (using
> pdftotext) in the commit message which I also reworded and shortened.
>
> Firmin Martin (1):
>   user-manual.txt: assign preface an id and a title
>
>  Documentation/user-manual.txt | 3 +++
>  1 file changed, 3 insertions(+)
>
> -- 
> 2.31.1.133.g84d06cdc06

Re: [PATCH v2 1/1] user-manual.txt: assign preface an id and a title

[Junio C Hamano]

Firmin Martin <firminmartin24@gmail.com> writes:

>     -<preface>
>     -<title></title>
>     +<preface id="_introduction">
>     +<title>Introduction</title>

Makes sense.

>     -@node Top, idm4, , (dir)
>     +@node Top, Introduction, , (dir)

and of course this looks nicer.

>      @documentlanguage en
>      @top Git User Manual
>      
>      @menu
>     -* : idm4.
>     +* Introduction::

so does this.

And the side effects on other formats are ...

>     --- before/user-manual.html.md	2021-04-04 05:20:55.378695854 +0200
>     +++ after/user-manual.html.md	2021-04-04 05:21:11.282850802 +0200
>     @@ -4,6 +4,8 @@
>      
>       **Table of Contents**
>      
>     +Introduction
>     +
>      1\. Repositories and Branches
>      
>          
>     @@ -278,7 +280,7 @@
>      
>      Todo list
>      
>     -#
>     +# Introduction
>      
>      Git is a fast distributed revision control system.
>      
>     --- before/user-manual.pdf.txt	2021-04-04 05:28:20.367036836 +0200
>     +++ after/user-manual.pdf.txt	2021-04-04 05:30:01.680026312 +0200
>     @@ -487,6 +487,7 @@
>      
>      vii
>      
>     +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.
>      Chapter 1 and Chapter 2 explain how to fetch and study a project using git—read these chapters to learn how to build and test a

... all sensible.

> Signed-off-by: Firmin Martin <firminmartin24@gmail.com>
> ---
>  Documentation/user-manual.txt | 3 +++
>  1 file changed, 3 insertions(+)
>
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index fd480b8645..f9e54b8674 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/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

Thanks, will queue.