{"thread":{"id":"55427","subject":"[PATCH][GSoC] user-manual.txt: fix empty heading of introduction","startedAt":"2021-04-02T12:23:41Z","lastAt":"2021-04-04T06:21:38Z","messageCount":10,"participants":["Firmin Martin","Junio C Hamano","Bagas Sanjaya"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"420879","messageId":"20210402121303.344914-1-firminmartin24@gmail.com","threadId":"55427","inReplyTo":null,"subject":"[PATCH][GSoC] user-manual.txt: fix empty heading of introduction","fromName":"Firmin Martin","fromEmail":"firminmartin24@gmail.com","sentAt":"2021-04-02T12:13:03Z","receivedAt":"2021-04-02T12:23:41Z","isPatch":true,"sender":{"key":"firminmartin24@gmail.com","avatar":"https://avatars.githubusercontent.com/u/20540328?v=4"},"body":"Two among the three warnings raised by \"make git.info\" are related to the fact\nthat the introductory heading being empty in user-manual.txt.\n\n    user-manual.texi:15: warning: empty menu entry name in `* : idm4.'\n    user-manual.texi:141: warning: @unnumbered missing argument\n\nRecall that the dependencies chain is as follows:\n\n    user-manual.txt => user-manual.xml => user-manual.texi => git.info\n\nAsciidoc creates an empty title tag in user-manual.xml which turns to be an\nempty node in user-manual.texi and git.info. This is not negligible in those\nfiles as docbook2x-texi creates a node \"idm4\" in the menu and the navigation\nbar, which can be confusing for the average user: in Emacs, the first entry of\nthe menu in the git info page is even displayed as empty.\n\nNote that this fix will create an \"Introduction\" section in the files:\nuser-manual.{xml, texi, html, pdf} and git.info.\n\nFor future reference, here are the content of the relevant & auto-generated files\nbefore this commit.\n\nuser-manual.xml:\n\n    l07|<bookinfo>\n    l08|<title>Git User Manual</title>\n    l09|</bookinfo>\n    l10|<preface>\n    l11|<title></title>\n    l12|<simpara>Git is a fast distributed revision control system.</simpara>\n\nuser-manual.texi:\n\n    l10 |@node Top, idm4, , (dir)\n    ... |\n    l14 |@menu\n    l15 |* : idm4.\n    ... |\n    l140|@node idm4, Repositories and Branches, Top, Top\n    l141|@unnumbered\n    ... | ...\n    l181|@node Repositories and Branches, Exploring Git history, idm4, Top\n\ngit.info:\n\n    l10  |File: git.info,  Node: Top,  Next: idm4,  Up: (dir)\n    ...  | ...\n    l15  |* Menu:\n    l16  |\n    l17  |* : idm4.\n    ...  | ...\n    l140 |File: git.info,  Node: idm4,  Next: Repositories and Branches,  Prev: Top,  Up: Top\n    ...  | ...\n    l177 |File: git.info,  Node: Repositories and Branches,  Next: Exploring Git history,  Prev: idm4,  Up: Top\n    ...  | ...\n    l5474|Node: idm43164\n\nSigned-off-by: Firmin Martin <firminmartin24@gmail.com>\n---\n Documentation/user-manual.txt | 3 +++\n 1 file changed, 3 insertions(+)\n\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex fd480b8645..d708612da2 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -1,5 +1,8 @@\n = Git User Manual\n \n+[[introduction]]\n+== Introduction\n+\n Git is a fast distributed revision control system.\n \n This manual is designed to be readable by someone with basic UNIX\n-- \n2.31.1.133.g84d06cdc06\n\n"},{"id":"420898","messageId":"xmqqwntk2xgy.fsf@gitster.g","threadId":"55427","inReplyTo":"20210402121303.344914-1-firminmartin24@gmail.com","subject":"Re: [PATCH][GSoC] user-manual.txt: fix empty heading of introduction","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-04-02T21:22:21Z","receivedAt":"2021-04-02T21:22:24Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Firmin Martin <firminmartin24@gmail.com> writes:\n\n> For future reference, here are the content of the relevant & auto-generated files\n> before this commit.\n\nI would have expected to see \"before and after\".  Is it too obvious\nwhat the postimage would be?  Otherwise, a better presentation would\nbe to show (an excerpt from) diff between preimage and postimage\noutput.\n\nThanks.\n"},{"id":"420899","messageId":"xmqqsg482x4f.fsf@gitster.g","threadId":"55427","inReplyTo":"xmqqwntk2xgy.fsf@gitster.g","subject":"Re: [PATCH][GSoC] user-manual.txt: fix empty heading of introduction","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-04-02T21:29:52Z","receivedAt":"2021-04-02T21:29:58Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> Firmin Martin <firminmartin24@gmail.com> writes:\n>\n>> For future reference, here are the content of the relevant & auto-generated files\n>> before this commit.\n>\n> I would have expected to see \"before and after\".  Is it too obvious\n> what the postimage would be?  Otherwise, a better presentation would\n> be to show (an excerpt from) diff between preimage and postimage\n> output.\n>\n> Thanks.\n\nAnother thing to look out for.  I do not think git.info is the only\nconsumer of user-manual.txt.  Does this change affect the other\nconsumer, user-manual.html, and if so how?\n"},{"id":"420907","messageId":"xmqqblaw2un9.fsf@gitster.g","threadId":"55427","inReplyTo":"xmqqsg482x4f.fsf@gitster.g","subject":"Re: [PATCH][GSoC] user-manual.txt: fix empty heading of introduction","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-04-02T22:23:22Z","receivedAt":"2021-04-02T22:23:26Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> Junio C Hamano <gitster@pobox.com> writes:\n>\n>> Firmin Martin <firminmartin24@gmail.com> writes:\n>>\n>>> For future reference, here are the content of the relevant & auto-generated files\n>>> before this commit.\n>>\n>> I would have expected to see \"before and after\".  Is it too obvious\n>> what the postimage would be?  Otherwise, a better presentation would\n>> be to show (an excerpt from) diff between preimage and postimage\n>> output.\n>>\n>> Thanks.\n>\n> Another thing to look out for.  I do not think git.info is the only\n> consumer of user-manual.txt.  Does this change affect the other\n> consumer, user-manual.html, and if so how?\n\nSo, here is what \"before and after\" of the user-manual.xml output\nfile looks like.  It shows that the standalone document loses its\nPreface and all the chapters have been renumbered (because what was\nin the Preface has become the first chapter).\n\nTo pages like http://git-scm.com/docs/user-manual that take our\nsource material and show them in preformatted, this change will\ncascade through.  Hopefully these places won't be upset for not\nhaving the Preface (e.g. this particular site does not even refer\nto the chapters as \"chapter 1\", \"chapter 2\", etc.) but we'd never\nknow until we try and break them ;-)\n\n\n--- user-manual-without-patch.xml\n+++ user-manual.xml\n@@ -7,8 +7,8 @@\n <bookinfo>\n     <title>Git User Manual</title>\n </bookinfo>\n-<preface>\n-<title></title>\n+<chapter id=\"introduction\">\n+<title>Introduction</title>\n <simpara>Git is a fast distributed revision control system.</simpara>\n <simpara>This manual is designed to be readable by someone with basic UNIX\n command-line skills, but no previous knowledge of Git.</simpara>\n@@ -31,7 +31,7 @@ pages, or <ulink url=\"git-help.html\">git-help(1)\n without any explanation.</simpara>\n <simpara>Finally, see <xref linkend=\"todo\"/> for ways that you can help make this manual more\n complete.</simpara>\n-</preface>\n+</chapter>\n <chapter id=\"repositories-and-branches\">\n <title>Repositories and Branches</title>\n <section id=\"how-to-get-a-git-repository\">\n"},{"id":"420922","messageId":"7530f132-cd72-bb6f-21f1-1ee23ca5e20f@gmail.com","threadId":"55427","inReplyTo":"xmqqwntk2xgy.fsf@gitster.g","subject":"Re: [PATCH][GSoC] user-manual.txt: fix empty heading of introduction","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-04-03T05:16:40Z","receivedAt":"2021-04-03T05:16:48Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"On 03/04/21 04.22, Junio C Hamano wrote:\n> I would have expected to see \"before and after\".  Is it too obvious\n> what the postimage would be?  Otherwise, a better presentation would\n> be to show (an excerpt from) diff between preimage and postimage\n> output.\n> \n> Thanks.\n> \nAttached is `diff -u` of generated HTML output, before and after this\npatch. The HTML is generated using Asciidoctor.\n\nIt seems like from the output, this patch actually add missing header\nfor intro chapter (in line with title of this patch).\n\nAnyway, thanks.\n\nReviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>\n\n-- \nAn old man doll... just what I always wanted! - Clara\n\n\n--- user-manual.html\t2021-04-03 11:58:44.937710623 +0700\n+++ user-manual.patched.html\t2021-04-03 12:01:01.634421455 +0700\n@@ -1,17 +1,17 @@\n <!DOCTYPE html PUBLIC \"-//W3C//DTD HTML 4.01//EN\" \"http://www.w3.org/TR/html4/strict.dtd\">\n-<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 \nrepository 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 \nfix</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 \nchangelog 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 \nclass=\"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 \nhref=\"#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 \nhref=\"#forcing-push\">What to do when a push fails</a></span></dt><dt><span class=\"section\"><a href=\"#setting-up-a-shared-repository\">Setting \nup 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 \nindividual 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 → \nobject 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 \nthe 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>\n+<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 \nis 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 \nclass=\"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 \na 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 \nnew 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 \nlost 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 \nclass=\"section\"><a href=\"#submitting-patches\">Submitting patches to a \nproject</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 \nclass=\"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 \nhref=\"#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 \nlinear 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 \nclass=\"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 → \nindex</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>\n \n-<div class=\"preface\"><div class=\"titlepage\"><div><div><h1 class=\"title\"><a name=\"id-1.2\"></a></h1></div></div></div>\n+<div class=\"chapter\"><div class=\"titlepage\"><div><div><h1 class=\"title\"><a name=\"introduction\"></a>Chapter 1. Introduction</h1></div></div></div>\n \n <p>Git is a fast distributed revision control system.</p>\n <p>This manual is designed to be readable by someone with basic UNIX\n command-line skills, but no previous knowledge of Git.</p>\n-<p><a class=\"xref\" href=\"#repositories-and-branches\" title=\"Chapter 1. Repositories and Branches\">Chapter 1, <i>Repositories \nand 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\n+<p><a class=\"xref\" href=\"#repositories-and-branches\" title=\"Chapter 2. Repositories and Branches\">Chapter 2, <i>Repositories \nand 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\n to fetch and study a project using git—​read these chapters to learn how\n to build and test a particular version of a software project, search for\n regressions, and so on.</p>\n <p>People needing to do actual development will also want to read\n-<a class=\"xref\" href=\"#Developing-With-git\" title=\"Chapter 3. Developing with Git\">Chapter 3, <i>Developing with Git</i></a> \nand <a class=\"xref\" href=\"#sharing-development\" title=\"Chapter 4. Sharing development with others\">Chapter 4, <i>Sharing development with others</i></a>.</p>\n+<a class=\"xref\" href=\"#Developing-With-git\" title=\"Chapter 4. Developing with Git\">Chapter 4, <i>Developing with Git</i></a> \nand <a class=\"xref\" href=\"#sharing-development\" title=\"Chapter 5. Sharing development with others\">Chapter 5, <i>Sharing development with others</i></a>.</p>\n <p>Further chapters cover more specialized topics.</p>\n <p>Comprehensive reference documentation is available through the man\n pages, or <a class=\"ulink\" href=\"git-help.html\" target=\"_top\">git-help(1)</a> command.  For example, for the command\n@@ -26,7 +26,7 @@\n <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\n complete.</p>\n </div>\n-<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 \nis 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>\n+<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 \nis 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>\n \n <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>\n \n@@ -139,7 +139,7 @@\n has that commit at all).  Since the object name is computed as a hash over the\n contents of the commit, you are guaranteed that the commit can never change\n without its name also changing.</p>\n-<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\n+<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\n history, including file data and directory contents, is stored in an object\n with a name that is a hash of its contents.</p>\n <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>\n@@ -351,7 +351,7 @@\n <a class=\"ulink\" href=\"git-config.html\" target=\"_top\">git-config(1)</a> for details.)</p>\n </div>\n </div>\n-<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>\n+<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>\n \n <p>Git is best thought of as a tool for storing the history of a\n collection of files.  It does this by storing compressed snapshots of\n@@ -679,7 +679,7 @@\n </div>\n </div>\n </div>\n-<div class=\"chapter\"><div class=\"titlepage\"><div><div><h1 class=\"title\"><a name=\"Developing-With-git\"></a>Chapter 3. Developing \nwith 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>\n+<div class=\"chapter\"><div class=\"titlepage\"><div><div><h1 class=\"title\"><a name=\"Developing-With-git\"></a>Chapter 4. Developing \nwith 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>\n \n <div class=\"section\"><div class=\"titlepage\"><div><div><h2 class=\"title\" style=\"clear: both\"><a name=\"telling-git-your-name\"></a>Telling \nGit your name</h2></div></div></div>\n \n@@ -1023,7 +1023,7 @@\n that case.</p>\n <p>It is also possible to replace commits further back in the history, but\n this is an advanced topic to be left for\n-<a class=\"link\" href=\"#cleaning-up-history\" title=\"Chapter 5. Rewriting history and maintaining patch series\">another chapter</a>.</p>\n+<a class=\"link\" href=\"#cleaning-up-history\" title=\"Chapter 6. Rewriting history and maintaining patch series\">another chapter</a>.</p>\n </div>\n <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>\n \n@@ -1155,7 +1155,7 @@\n </div>\n </div>\n </div>\n-<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 \nhref=\"#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>\n+<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 \nhref=\"#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>\n \n <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>\n \n@@ -1492,7 +1492,7 @@\n and can be updated using <a class=\"ulink\" href=\"git-fetch.html\" target=\"_top\">git-fetch(1)</a>; you can track other\n public trees using <a class=\"ulink\" href=\"git-remote.html\" target=\"_top\">git-remote(1)</a> to set up a \"remote\" and\n <a class=\"ulink\" href=\"git-fetch.html\" target=\"_top\">git-fetch(1)</a> to keep them up to date; see\n-<a class=\"xref\" href=\"#repositories-and-branches\" title=\"Chapter 1. Repositories and Branches\">Chapter 1, <i>Repositories and \nBranches</i></a>.</p>\n+<a class=\"xref\" href=\"#repositories-and-branches\" title=\"Chapter 2. Repositories and Branches\">Chapter 2, <i>Repositories and \nBranches</i></a>.</p>\n <p>Now create the branches in which you are going to work; these start out\n at the current tip of origin/master branch, and should be set up (using\n 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\n@@ -1679,7 +1679,7 @@\n </div>\n </div>\n </div>\n-<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>\n+<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>\n \n <p>Normally commits are only added to a project, never taken away or\n replaced.  Git is designed with this assumption, and violating it will\n@@ -1923,7 +1923,7 @@\n publishing.</p>\n </div>\n </div>\n-<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 \nfetch 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>\n+<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 \nfetch 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>\n \n <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>\n \n@@ -2012,7 +2012,7 @@\n the refspec syntax.</p>\n </div>\n </div>\n-<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 \nclass=\"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 \nrepository corruption</a></span></dt></dl></dd><dt><span class=\"section\"><a href=\"#the-index\">The index</a></span></dt></dl></div>\n+<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 \nclass=\"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 \nrepository corruption</a></span></dt></dl></dd><dt><span class=\"section\"><a href=\"#the-index\">The index</a></span></dt></dl></div>\n \n <p>Git is built on a small number of simple but powerful ideas.  While it\n is possible to get things done without understanding them, you will find\n@@ -2141,7 +2141,7 @@\n between two related tree objects, since it can ignore any entries with\n identical object names.</p>\n <p>(Note: in the presence of submodules, trees may also have commits as\n-entries.  See <a class=\"xref\" href=\"#submodules\" title=\"Chapter 8. Submodules\">Chapter 8, <i>Submodules</i></a> for documentation.)</p>\n+entries.  See <a class=\"xref\" href=\"#submodules\" title=\"Chapter 9. Submodules\">Chapter 9, <i>Submodules</i></a> for documentation.)</p>\n <p>Note that the files all have mode 644 or 755: Git actually only pays\n attention to the executable bit.</p>\n </div>\n@@ -2258,7 +2258,7 @@\n objects.  They are not a problem.</p>\n <p>The most common cause of dangling objects is that you’ve rebased a\n branch, or you have pulled from somebody else who rebased a branch—​see\n-<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\n+<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\n branch still exists, as does everything it pointed to. The branch\n pointer itself just doesn’t, since you replaced it with another one.</p>\n <p>There are also other situations that cause dangling objects. For\n@@ -2437,7 +2437,7 @@\n information as long as you have the name of the tree that it described.</p>\n </div>\n </div>\n-<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>\n+<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>\n \n <p>Large projects are often composed of smaller, self-contained modules. \n For\n example, an embedded Linux distribution’s source tree would include every\n@@ -2629,7 +2629,7 @@\n warning about not being able switch from a dirty branch.</p>\n </div>\n </div>\n-<div class=\"chapter\"><div class=\"titlepage\"><div><div><h1 class=\"title\"><a name=\"low-level-operations\"></a>Chapter 9. Low-level \nGit 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>\n+<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>\n \n <p>Many of the higher-level commands were originally implemented as shell\n scripts using a smaller core of low-level Git commands.  These can still\n@@ -2891,7 +2891,7 @@\n <p>and that is what higher level <code class=\"literal\">git merge -s resolve</code> is implemented with.</p>\n </div>\n </div>\n-<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>\n+<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>\n \n <p>This chapter covers internal details of the Git implementation which\n probably only Git developers need to understand.</p>\n@@ -3072,7 +3072,7 @@\n itself!</p>\n </div>\n </div>\n-<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>\n+<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>\n \n <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>\n \n"},{"id":"420944","messageId":"xmqq5z1227wq.fsf@gitster.g","threadId":"55427","inReplyTo":"7530f132-cd72-bb6f-21f1-1ee23ca5e20f@gmail.com","subject":"Re: [PATCH][GSoC] user-manual.txt: fix empty heading of introduction","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-04-04T00:46:45Z","receivedAt":"2021-04-04T00:46:52Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Bagas Sanjaya <bagasdotme@gmail.com> writes:\n\n> On 03/04/21 04.22, Junio C Hamano wrote:\n>> I would have expected to see \"before and after\".  Is it too obvious\n>> what the postimage would be?  Otherwise, a better presentation would\n>> be to show (an excerpt from) diff between preimage and postimage\n>> output.\n>> Thanks.\n>> \n> Attached is `diff -u` of generated HTML output, before and after this\n> patch. The HTML is generated using Asciidoctor.\n\nUnfortunately, that is more-or-less unreadable gunk.  Even for the\nfirst few places that have differences, the output of diff between\nraw HTML is not suited to spot that the first entry in the TOC has\nchanged classs from preface to chapter or how they are treated\ndifferently.\n\nWhat I did before sending out the message was to generate HTML for\nthe before and after versions, render them into text and then run\ndiff on them.  It showed that most changes are the chapter numbering\nand cross reference, of course.  This was still hard to see, but at\nleast it was possible to eyeball what was going on [*].\n\nWhile Firmin showed only the \"before\" version of .xml, a diff\nbetween before-and-after versions of .xml turned out to be far\neasier to see how the change propagates down the toolchain than\neither of the above two.  It would have been  the best to have that,\ninstead of just the \"before\" image, in the explanation.\n\n    --- user-manual.xml\t2021-04-03 17:36:14.804344928 -0700\n    +++ user-manual.xml\t2021-04-03 17:36:44.599025868 -0700\n    @@ -7,8 +7,8 @@\n     <bookinfo>\n         <title>Git User Manual</title>\n     </bookinfo>\n    -<preface>\n    -<title></title>\n    +<chapter id=\"introduction\">\n    +<title>Introduction</title>\n     <simpara>Git is a fast distributed revision control system.</simpara>\n     <simpara>This manual is designed to be readable by someone with basic UNIX\n     command-line skills, but no previous knowledge of Git.</simpara>\n    @@ -31,7 +31,7 @@\n     without any explanation.</simpara>\n     <simpara>Finally, see <xref linkend=\"todo\"/> for ways that you can help make this manual more\n     complete.</simpara>\n    -</preface>\n    +</chapter>\n     <chapter id=\"repositories-and-branches\">\n     <title>Repositories and Branches</title>\n     <section id=\"how-to-get-a-git-repository\">\n\nIf an updated version is planned, I'd expect it to come with\nsomething like the above indented patch plus a brief explanation of\nside effects (i.e. we lost preface and we have renumbered the\nchapters) in its proposed log message.\n\nThanks.\n\n\n[Footnote]\n\n* The text-rendered HTML would compare like this (just an excerpt).\n\n--- /var/tmp/before.txt\t2021-04-03 17:40:07.777307995 -0700\n+++ /var/tmp/after.txt\t2021-04-03 17:39:51.423836495 -0700\n@@ -4,255 +4,259 @@\n \n    Table of Contents\n \n-   [1]1. Repositories and Branches\n+   [1]1. Introduction\n \n-   [2]How to get a Git repository\n+   [2]2. Repositories and Branches\n \n\n...\n\nTOC numbering is of course off by one, as the patch promotes the\npreface into the first chapter.\n\n...\n\n-   [114]B. Notes and todo list for this manual\n+   [116]Todo list\n \n-   [115]Todo list\n+                            Chapter 1. Introduction\n \n...\n\nAnd of course, we now have the chapter title.\n\n...\n\n    Git is a fast distributed revision control system.\n \n    This manual is designed to be readable by someone with basic UNIX\n    command-line skills, but no previous knowledge of Git.\n \n-   [116]Chapter 1, Repositories and Branches and [117]Chapter 2, Exploring\n+   [117]Chapter 2, Repositories and Branches and [118]Chapter 3, Exploring\n\n...\n\nCross references are all off-by-one, too.\n"},{"id":"420949","messageId":"20210404040739.2671960-1-firminmartin24@gmail.com","threadId":"55427","inReplyTo":"20210402121303.344914-1-firminmartin24@gmail.com","subject":"[PATCH v2 0/1] user-manual.txt: assign preface an id and a title","fromName":"Firmin Martin","fromEmail":"firminmartin24@gmail.com","sentAt":"2021-04-04T04:07:38Z","receivedAt":"2021-04-04T04:09:09Z","isPatch":true,"sender":{"key":"firminmartin24@gmail.com","avatar":"https://avatars.githubusercontent.com/u/20540328?v=4"},"body":"I found a more satisfying way to keep the change minimal: it turns out that\n[preface] does exactly what we want. It just adds the missing id and the title.\nNo renumbering, etc.\n\nSee https://docs.asciidoctor.org/asciidoc/latest/sections/preface/\n\nI attached the diff of user-manual.xml, user-manual.texi, git.info,\nuser-manual.html (using html2markdown) and user-manual.pdf (using\npdftotext) in the commit message which I also reworded and shortened.\n\nFirmin Martin (1):\n  user-manual.txt: assign preface an id and a title\n\n Documentation/user-manual.txt | 3 +++\n 1 file changed, 3 insertions(+)\n\n-- \n2.31.1.133.g84d06cdc06\n\n"},{"id":"420950","messageId":"20210404040739.2671960-2-firminmartin24@gmail.com","threadId":"55427","inReplyTo":"20210404040739.2671960-1-firminmartin24@gmail.com","subject":"[PATCH v2 1/1] user-manual.txt: assign preface an id and a title","fromName":"Firmin Martin","fromEmail":"firminmartin24@gmail.com","sentAt":"2021-04-04T04:07:39Z","receivedAt":"2021-04-04T04:09:49Z","isPatch":true,"sender":{"key":"firminmartin24@gmail.com","avatar":"https://avatars.githubusercontent.com/u/20540328?v=4"},"body":"Two among the three warnings raised by \"make git.info\" are related to the fact\nthat the preface has not id in user-manual.txt.\n\n    user-manual.texi:15: warning: empty menu entry name in `* : idm4.'\n    user-manual.texi:141: warning: @unnumbered missing argument\n\nThis causes asciidoc creating an empty preface and an empty title tag in\nuser-manual.xml which turns to be an empty node in user-manual.texi and\ngit.info. Consequently, one can notice in user-manual.texi and git.info\na node named \"idm4\" in the menu and the navigation bar. In emacs, the\nfirst entry of the menu in the git info page is even displayed as empty.\n\nThis fix will name \"Introduction\" the preface and assign it an id.\nThe result can be seen in the files: user-manual.{xml, texi, html, pdf}\nand git.info.\n\nFor future reference, the diff between old and new user-manual.xml,\nuser-manual.texi, git.info, user-manual.html (converted through\nhtml2markdown) and user-manual.pdf (converted through pdftotext) are\nattached.\n\n    --- before/user-manual.xml\t2021-04-04 03:58:47.758008722 +0200\n    +++ after/user-manual.xml\t2021-04-04 03:56:40.520551163 +0200\n    @@ -7,8 +7,8 @@\n     <bookinfo>\n         <title>Git User Manual</title>\n     </bookinfo>\n    -<preface>\n    -<title></title>\n    +<preface id=\"_introduction\">\n    +<title>Introduction</title>\n     <simpara>Git is a fast distributed revision control system.</simpara>\n     <simpara>This manual is designed to be readable by someone with basic UNIX\n     command-line skills, but no previous knowledge of Git.</simpara>\n\n    --- before/user-manual.texi\t2021-04-04 03:58:47.490005652 +0200\n    +++ after/user-manual.texi\t2021-04-04 03:56:40.520551163 +0200\n    @@ -7,12 +7,12 @@\n     * Git: (git).           A fast distributed revision control system\n     @end direntry\n     \n    -@node Top, idm4, , (dir)\n    +@node Top, Introduction, , (dir)\n     @documentlanguage en\n     @top Git User Manual\n     \n     @menu\n    -* : idm4.\n    +* Introduction::\n     * Repositories and Branches::\n     * Exploring Git history::\n     * Developing with Git::\n    @@ -137,8 +137,8 @@\n     @end detailmenu\n     @end menu\n     \n    -@node idm4, Repositories and Branches, Top, Top\n    -@unnumbered \n    +@node Introduction, Repositories and Branches, Top, Top\n    +@unnumbered Introduction\n     \n     Git is a fast distributed revision control system.\n     \n    @@ -178,7 +178,7 @@\n     Finally, see @ref{Notes and todo list for this manual} for ways that you can help make this manual more\n     complete.\n     \n    -@node Repositories and Branches, Exploring Git history, idm4, Top\n    +@node Repositories and Branches, Exploring Git history, Introduction, Top\n     @chapter Repositories and Branches\n     \n     @menu\n    \n    --- before/git.info\t2021-04-04 03:58:46.557994966 +0200\n    +++ after/git.info\t2021-04-04 03:56:40.520551163 +0200\n    @@ -7,14 +7,14 @@\n     END-INFO-DIR-ENTRY\n     \n    -File: git.info,  Node: Top,  Next: idm4,  Up: (dir)\n    +File: git.info,  Node: Top,  Next: Introduction,  Up: (dir)\n     \n     Git User Manual\n     ***************\n     \n     * Menu:\n     \n    -* : idm4.\n    +* Introduction::\n     * Repositories and Branches::\n     * Exploring Git history::\n     * Developing with Git::\n    @@ -137,7 +137,10 @@\n     \n     \n    -File: git.info,  Node: idm4,  Next: Repositories and Branches,  Prev: Top,  Up: Top\n    +File: git.info,  Node: Introduction,  Next: Repositories and Branches,  Prev: Top,  Up: Top\n    +\n    +Introduction\n    +************\n     \n     Git is a fast distributed revision control system.\n     \n    @@ -174,7 +177,7 @@\n     that you can help make this manual more complete.\n     \n    -File: git.info,  Node: Repositories and Branches,  Next: Exploring Git history,  Prev: idm4,  Up: Top\n    +File: git.info,  Node: Repositories and Branches,  Next: Exploring Git history,  Prev: Introduction,  Up: Top\n     \n     1 Repositories and Branches\n     ***************************\n    @@ -5471,207 +5474,207 @@\n    ...\n     Tag Table:\n     Node: Top212\n    -Node: idm43164\n    -Node: Repositories and Branches4465\n    ...\n    +Node: Introduction3179\n    +Node: Repositories and Branches4515\n    +Node: How to get a Git repository5128\n    ...\n    End Tag Table\n    \n    --- before/user-manual.html.md\t2021-04-04 05:20:55.378695854 +0200\n    +++ after/user-manual.html.md\t2021-04-04 05:21:11.282850802 +0200\n    @@ -4,6 +4,8 @@\n     \n      **Table of Contents**\n     \n    +Introduction\n    +\n     1\\. Repositories and Branches\n     \n         \n    @@ -278,7 +280,7 @@\n     \n     Todo list\n     \n    -#\n    +# Introduction\n     \n     Git is a fast distributed revision control system.\n     \n    --- before/user-manual.pdf.txt\t2021-04-04 05:28:20.367036836 +0200\n    +++ after/user-manual.pdf.txt\t2021-04-04 05:30:01.680026312 +0200\n    @@ -487,6 +487,7 @@\n     \n     vii\n     \n    +Introduction\n     Git is a fast distributed revision control system.\n     This manual is designed to be readable by someone with basic UNIX command-line skills, but no previous knowledge of Git.\n     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\n\nSigned-off-by: Firmin Martin <firminmartin24@gmail.com>\n---\n Documentation/user-manual.txt | 3 +++\n 1 file changed, 3 insertions(+)\n\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex fd480b8645..f9e54b8674 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -1,5 +1,8 @@\n = Git User Manual\n \n+[preface]\n+== Introduction\n+\n Git is a fast distributed revision control system.\n \n This manual is designed to be readable by someone with basic UNIX\n-- \n2.31.1.133.g84d06cdc06\n\n"},{"id":"420951","messageId":"875z12isbx.fsf@Inspiron.i-did-not-set--mail-host-address--so-tickle-me","threadId":"55427","inReplyTo":"20210404040739.2671960-1-firminmartin24@gmail.com","subject":"Re: [PATCH v2 0/1] user-manual.txt: assign preface an id and a title","fromName":"Firmin Martin","fromEmail":"firminmartin24@gmail.com","sentAt":"2021-04-04T04:31:14Z","receivedAt":"2021-04-04T04:31:26Z","isPatch":true,"sender":{"key":"firminmartin24@gmail.com","avatar":"https://avatars.githubusercontent.com/u/20540328?v=4"},"body":"The first line of the cover-letter has been eaten because I forgot to\nleave an empty line... I wanted to thank Junio and Bagas for their\nreviews. I hope I didn't miss anything important.\n\nThanks,\n\nFirmin\n\nFirmin Martin <firminmartin24@gmail.com> writes:\n\n> I found a more satisfying way to keep the change minimal: it turns out that\n> [preface] does exactly what we want. It just adds the missing id and the title.\n> No renumbering, etc.\n>\n> See https://docs.asciidoctor.org/asciidoc/latest/sections/preface/\n>\n> I attached the diff of user-manual.xml, user-manual.texi, git.info,\n> user-manual.html (using html2markdown) and user-manual.pdf (using\n> pdftotext) in the commit message which I also reworded and shortened.\n>\n> Firmin Martin (1):\n>   user-manual.txt: assign preface an id and a title\n>\n>  Documentation/user-manual.txt | 3 +++\n>  1 file changed, 3 insertions(+)\n>\n> -- \n> 2.31.1.133.g84d06cdc06\n"},{"id":"420960","messageId":"xmqqr1jqy3h0.fsf@gitster.g","threadId":"55427","inReplyTo":"20210404040739.2671960-2-firminmartin24@gmail.com","subject":"Re: [PATCH v2 1/1] user-manual.txt: assign preface an id and a title","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-04-04T06:21:31Z","receivedAt":"2021-04-04T06:21:38Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Firmin Martin <firminmartin24@gmail.com> writes:\n\n>     -<preface>\n>     -<title></title>\n>     +<preface id=\"_introduction\">\n>     +<title>Introduction</title>\n\nMakes sense.\n\n>     -@node Top, idm4, , (dir)\n>     +@node Top, Introduction, , (dir)\n\nand of course this looks nicer.\n\n>      @documentlanguage en\n>      @top Git User Manual\n>      \n>      @menu\n>     -* : idm4.\n>     +* Introduction::\n\nso does this.\n\nAnd the side effects on other formats are ...\n\n>     --- before/user-manual.html.md\t2021-04-04 05:20:55.378695854 +0200\n>     +++ after/user-manual.html.md\t2021-04-04 05:21:11.282850802 +0200\n>     @@ -4,6 +4,8 @@\n>      \n>       **Table of Contents**\n>      \n>     +Introduction\n>     +\n>      1\\. Repositories and Branches\n>      \n>          \n>     @@ -278,7 +280,7 @@\n>      \n>      Todo list\n>      \n>     -#\n>     +# Introduction\n>      \n>      Git is a fast distributed revision control system.\n>      \n>     --- before/user-manual.pdf.txt\t2021-04-04 05:28:20.367036836 +0200\n>     +++ after/user-manual.pdf.txt\t2021-04-04 05:30:01.680026312 +0200\n>     @@ -487,6 +487,7 @@\n>      \n>      vii\n>      \n>     +Introduction\n>      Git is a fast distributed revision control system.\n>      This manual is designed to be readable by someone with basic UNIX command-line skills, but no previous knowledge of Git.\n>      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\n\n... all sensible.\n\n> Signed-off-by: Firmin Martin <firminmartin24@gmail.com>\n> ---\n>  Documentation/user-manual.txt | 3 +++\n>  1 file changed, 3 insertions(+)\n>\n> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\n> index fd480b8645..f9e54b8674 100644\n> --- a/Documentation/user-manual.txt\n> +++ b/Documentation/user-manual.txt\n> @@ -1,5 +1,8 @@\n>  = Git User Manual\n>  \n> +[preface]\n> +== Introduction\n> +\n>  Git is a fast distributed revision control system.\n>  \n>  This manual is designed to be readable by someone with basic UNIX\n\nThanks, will queue.\n"}]}