{"thread":{"id":"66371","subject":"[PATCH] doc: add more AsciiDoc cross-references","startedAt":"2026-09-22T19:29:05Z","lastAt":"2026-09-28T15:16:21Z","messageCount":22,"participants":["Julia Evans via GitGitGadget","Junio C Hamano","Julia Evans","Kristoffer Haugsbakk","Jeff King"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"553010","messageId":"pull.2416.git.git.1790105342890.gitgitgadget@gmail.com","threadId":"66371","inReplyTo":null,"subject":"[PATCH] doc: add more AsciiDoc cross-references","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-09-22T19:29:02Z","receivedAt":"2026-09-22T19:29:05Z","isPatch":true,"body":"From: Julia Evans <julia@jvns.ca>\n\nInstead of saying \"see EXAMPLES below\", say \"see <<EXAMPLES,EXAMPLES>>\nbelow\" to make the man pages easier to navigate on the web.\n\nThe reason for using the more verbose <<EXAMPLES,EXAMPLES>>\n(instead of <<EXAMPLES>>) is that if the header that `<<EXAMPLES>>`\nis referring to is in an included page (for example `REMOTES` in the\n`git-push` man page), then AsciiDoc will think it's a broken link even\nthough it isn't. So it's easier to just make all of the links use the\nform with two parts.\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n    doc: add more AsciiDoc cross-references\n    \n    This patch is a bit long so it's hard to review manually. A few notes\n    about testing:\n    \n     * I tested it by running this script\n       (https://gist.github.com/jvns/039c8ed0add092f2179f0dba52ebb896) which\n       builds the previous and current views of all the man pages. I looked\n       at the output to make sure there were no differences. You can see the\n       output in that gist.\n     * I believe that asciidoctor will automatically make sure that there\n       are no broken links.\n     * I also spot checked some of the HTML output to make sure it looked\n       reasonable.\n    \n    There are some inconsistencies in how the cross-references are formatted\n    but I left in all of the inconsistencies for now because it makes it\n    easier to test that we're not introducing mistakes.\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2416%2Fjvns%2Fanchors-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2416/jvns/anchors-v1\nPull-Request: https://github.com/git/git/pull/2416\n\n Documentation/fetch-options.adoc              |  4 +-\n Documentation/git-add.adoc                    |  3 +-\n Documentation/git-bundle.adoc                 |  7 +-\n Documentation/git-cat-file.adoc               | 12 ++--\n Documentation/git-checkout.adoc               | 11 +--\n Documentation/git-credential-cache.adoc       |  3 +-\n Documentation/git-credential-store.adoc       |  3 +-\n Documentation/git-fast-export.adoc            |  5 +-\n Documentation/git-fast-import.adoc            |  7 +-\n Documentation/git-fetch.adoc                  |  1 +\n Documentation/git-filter-branch.adoc          |  3 +-\n Documentation/git-for-each-ref.adoc           |  4 +-\n Documentation/git-format-patch.adoc           |  4 +-\n Documentation/git-gc.adoc                     | 12 ++--\n Documentation/git-grep.adoc                   |  9 ++-\n Documentation/git-http-backend.adoc           |  6 +-\n Documentation/git-ls-files.adoc               |  8 ++-\n Documentation/git-ls-tree.adoc                |  3 +-\n Documentation/git-maintenance.adoc            |  3 +-\n Documentation/git-merge-tree.adoc             |  2 +-\n Documentation/git-notes.adoc                  | 14 ++--\n Documentation/git-p4.adoc                     | 12 ++--\n Documentation/git-pack-objects.adoc           |  5 +-\n Documentation/git-prune.adoc                  |  3 +-\n Documentation/git-push.adoc                   | 10 +--\n Documentation/git-rebase.adoc                 | 69 +++++++++++--------\n Documentation/git-replay.adoc                 |  4 +-\n Documentation/git-repo.adoc                   |  5 +-\n Documentation/git-rev-parse.adoc              |  7 +-\n Documentation/git-send-email.adoc             |  5 +-\n Documentation/git-stash.adoc                  |  3 +-\n Documentation/git-svn.adoc                    | 10 +--\n Documentation/git-worktree.adoc               |  5 +-\n Documentation/gitremote-helpers.adoc          | 15 ++--\n Documentation/gitsubmodules.adoc              |  9 ++-\n Documentation/gitworkflows.adoc               |  6 +-\n .../howto/revert-a-faulty-merge.adoc          |  5 +-\n Documentation/revisions.adoc                  |  4 +-\n 38 files changed, 190 insertions(+), 111 deletions(-)\n\ndiff --git a/Documentation/fetch-options.adoc b/Documentation/fetch-options.adoc\nindex 035f780e58..47dea1de8e 100644\n--- a/Documentation/fetch-options.adoc\n+++ b/Documentation/fetch-options.adoc\n@@ -199,7 +199,7 @@ endif::git-pull[]\n \tproviding the tag refspec.\n ifndef::git-pull[]\n +\n-See the PRUNING section below for more details.\n+See the <<PRUNING,PRUNING>> section below for more details.\n \n `-P`::\n `--prune-tags`::\n@@ -210,7 +210,7 @@ See the PRUNING section below for more details.\n \ta shorthand for providing the explicit tag refspec along with\n \t`--prune`, see the discussion about that in its documentation.\n +\n-See the PRUNING section below for more details.\n+See the <<PRUNING,PRUNING>> section below for more details.\n \n endif::git-pull[]\n \ndiff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc\nindex 16b06e38e1..906db7ccf3 100644\n--- a/Documentation/git-add.adoc\n+++ b/Documentation/git-add.adoc\n@@ -117,7 +117,7 @@ The intent of this option is to pick and choose lines of the patch to\n apply, or even to modify the contents of lines to be staged. This can be\n quicker and more flexible than using the interactive hunk selector.\n However, it is easy to confuse oneself and create a patch that does not\n-apply to the index. See EDITING PATCHES below.\n+apply to the index. See <<EDITING_PATCHES,EDITING PATCHES>> below.\n \n `-u`::\n `--update`::\n@@ -375,6 +375,7 @@ diff::\n   `HEAD` and index).\n \n \n+[[EDITING_PATCHES]]\n EDITING PATCHES\n ---------------\n \ndiff --git a/Documentation/git-bundle.adoc b/Documentation/git-bundle.adoc\nindex 03cd36fe8d..cd722bd674 100644\n--- a/Documentation/git-bundle.adoc\n+++ b/Documentation/git-bundle.adoc\n@@ -43,7 +43,7 @@ header indicating what references are contained within the bundle.\n \n Like the packed archive format itself bundles can either be\n self-contained, or be created using exclusions.\n-See the \"OBJECT PREREQUISITES\" section below.\n+See the <<OBJECT_PREREQUISITES,\"OBJECT PREREQUISITES\">> section below.\n \n Bundles created using revision exclusions are \"thin packs\" created\n using the `--thin` option to linkgit:git-pack-objects[1], and\n@@ -94,7 +94,8 @@ unbundle <file>::\n \n <git-rev-list-args>::\n \tA list of arguments, acceptable to 'git rev-parse' and\n-\t'git rev-list' (and containing a named ref, see SPECIFYING REFERENCES\n+\t'git rev-list' (and containing a named ref, see\n+\t<<SPECIFYING_REFERENCES,SPECIFYING REFERENCES>>\n \tbelow), that specifies the specific objects and references\n \tto transport.  For example, `master~10..master` causes the\n \tcurrent master reference to be packaged along with all objects\n@@ -127,6 +128,7 @@ unbundle <file>::\n \tThis flag makes the command not to report its progress\n \ton the standard error stream.\n \n+[[SPECIFYING_REFERENCES]]\n SPECIFYING REFERENCES\n ---------------------\n \n@@ -169,6 +171,7 @@ $ git bundle create master-yesterday.bundle master~10..master~5\n fatal: Refusing to create empty bundle.\n ----------------\n \n+[[OBJECT_PREREQUISITES]]\n OBJECT PREREQUISITES\n --------------------\n \ndiff --git a/Documentation/git-cat-file.adoc b/Documentation/git-cat-file.adoc\nindex 514bfc0032..c4ea2524cf 100644\n--- a/Documentation/git-cat-file.adoc\n+++ b/Documentation/git-cat-file.adoc\n@@ -115,7 +115,7 @@ are not of the requested type.\n --\n \t* When used with `--textconv` or `--filters`, the input lines\n \t  must specify the path, separated by whitespace. See the section\n-\t  `BATCH OUTPUT` below for details.\n+\t  <<BATCH_OUTPUT,`BATCH OUTPUT`>> below for details.\n \n \t* When used with `--use-mailmap`, for commit and tag objects, the\n \t  contents part of the output shows the identities replaced using the\n@@ -133,7 +133,7 @@ are not of the requested type.\n --\n \t* When used with `--textconv` or `--filters`, the input lines must\n \t specify the path, separated by whitespace. See the section\n-\t `BATCH OUTPUT` below for details.\n+\t <<BATCH_OUTPUT,`BATCH OUTPUT`>> below for details.\n \n \t* When used with `--use-mailmap`, for commit and tag objects, the\n \t  printed object information shows the size of the object as if the\n@@ -149,7 +149,7 @@ are not of the requested type.\n --\n \t* When used with `--textconv` or `--filters`, the input lines must\n \t  specify the path, separated by whitespace. See the section\n-\t  `BATCH OUTPUT` below for details.\n+\t  <<BATCH_OUTPUT,`BATCH OUTPUT`>> below for details.\n \n \t* When used with `--use-mailmap`, for commit and tag objects, the\n \t  `contents` command shows the identities replaced using the\n@@ -295,6 +295,7 @@ If `-p` is specified, the contents of `<object>` are pretty-printed.\n If `<type>` is specified, the raw (though uncompressed) contents of the `<object>`\n will be returned.\n \n+[[BATCH_OUTPUT]]\n BATCH OUTPUT\n ------------\n \n@@ -333,12 +334,12 @@ newline. The available atoms are:\n \n `objectsize:disk`::\n \tThe size, in bytes, that the object takes up on disk. See the\n-\tnote about on-disk sizes in the `CAVEATS` section below.\n+\tnote about on-disk sizes in the <<CAVEATS,`CAVEATS`>> section below.\n \n `deltabase`::\n \tIf the object is stored as a delta on-disk, this expands to the\n \tfull hex representation of the delta base object name.\n-\tOtherwise, expands to the null OID (all zeroes). See `CAVEATS`\n+\tOtherwise, expands to the null OID (all zeroes). See <<CAVEATS,`CAVEATS`>>\n \tbelow.\n \n `rest`::\n@@ -447,6 +448,7 @@ are replaced with NUL terminators. This ensures that output will be parsable if\n the output itself would contain a linefeed and is thus recommended for\n scripting purposes.\n \n+[[CAVEATS]]\n CAVEATS\n -------\n \ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex a8b3b8c2e2..2aefea0228 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -27,7 +27,8 @@ DESCRIPTION\n 2. **Restore a different version of a file**, for example with\n    `git checkout <commit> <filename>` or `git checkout <filename>`\n \n-See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.\n+See <<ARGUMENT_DISAMBIGUATION,ARGUMENT DISAMBIGUATION>> below\n+for how Git decides which one to do.\n \n `git checkout [<branch>]`::\n \tSwitch to _<branch>_. This sets the current branch to _<branch>_ and\n@@ -68,7 +69,7 @@ uncommitted changes.\n \n \tThe same as `git checkout <branch>`, except that instead of pointing\n \t`HEAD` at the branch, it points `HEAD` at the commit ID.\n-\tSee the \"DETACHED HEAD\" section below for more.\n+\tSee the <<DETACHED_HEAD,\"DETACHED HEAD\">> section below for more.\n +\n Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.\n \n@@ -210,8 +211,8 @@ variable.\n \tRather than checking out a branch to work on it, check out a\n \tcommit for inspection and discardable experiments.\n \tThis is the default behavior of `git checkout <commit>` when\n-\t_<commit>_ is not a branch name.  See the \"DETACHED HEAD\" section\n-\tbelow for details.\n+\t_<commit>_ is not a branch name.  See the\n+\t<<DETACHED_HEAD,\"DETACHED HEAD\">> section below for details.\n \n `--orphan <new-branch>`::\n \tCreate a new unborn branch, named _<new-branch>_, started from\n@@ -372,6 +373,7 @@ leave out at most one of _<rev-a>_ and _<rev-b>_, in which case it defaults to `\n +\n For more details, see the 'pathspec' entry in linkgit:gitglossary[7].\n \n+[[DETACHED_HEAD]]\n DETACHED HEAD\n -------------\n `HEAD` normally refers to a named branch (e.g. `master`). Meanwhile, each\n@@ -504,6 +506,7 @@ $ git reflog -2 HEAD # or\n $ git log -g -2 HEAD\n ------------\n \n+[[ARGUMENT_DISAMBIGUATION]]\n ARGUMENT DISAMBIGUATION\n -----------------------\n \ndiff --git a/Documentation/git-credential-cache.adoc b/Documentation/git-credential-cache.adoc\nindex 54fa7a27e1..2f6395937d 100644\n--- a/Documentation/git-credential-cache.adoc\n+++ b/Documentation/git-credential-cache.adoc\n@@ -24,7 +24,7 @@ user by filesystem permissions.\n \n You probably don't want to invoke this command directly; it is meant to\n be used as a credential helper by other parts of Git. See\n-linkgit:gitcredentials[7] or `EXAMPLES` below.\n+linkgit:gitcredentials[7] or <<EXAMPLES,`EXAMPLES`>> below.\n \n OPTIONS\n -------\n@@ -54,6 +54,7 @@ credentials before their timeout, you can issue an `exit` action:\n git credential-cache exit\n --------------------------------------\n \n+[[EXAMPLES]]\n EXAMPLES\n --------\n \ndiff --git a/Documentation/git-credential-store.adoc b/Documentation/git-credential-store.adoc\nindex 71864a8726..3f8a426f93 100644\n--- a/Documentation/git-credential-store.adoc\n+++ b/Documentation/git-credential-store.adoc\n@@ -24,7 +24,7 @@ Git programs.\n \n You probably don't want to invoke this command directly; it is meant to\n be used as a credential helper by other parts of git. See\n-linkgit:gitcredentials[7] or `EXAMPLES` below.\n+linkgit:gitcredentials[7] or <<EXAMPLES,`EXAMPLES`>> below.\n \n OPTIONS\n -------\n@@ -67,6 +67,7 @@ written to.\n \n When erasing credentials, matching credentials will be erased from all files.\n \n+[[EXAMPLES]]\n EXAMPLES\n --------\n \ndiff --git a/Documentation/git-fast-export.adoc b/Documentation/git-fast-export.adoc\nindex 719aeca244..0c2ce385c4 100644\n--- a/Documentation/git-fast-export.adoc\n+++ b/Documentation/git-fast-export.adoc\n@@ -148,12 +148,12 @@ by keeping the marks the same across runs.\n --anonymize::\n \tAnonymize the contents of the repository while still retaining\n \tthe shape of the history and stored tree.  See the section on\n-\t`ANONYMIZING` below.\n+\t<<ANONYMIZING,`ANONYMIZING`>> below.\n \n --anonymize-map=<from>[:<to>]::\n \tConvert token `<from>` to `<to>` in the anonymized output. If\n \t`<to>` is omitted, map `<from>` to itself (i.e., do not\n-\tanonymize it). See the section on `ANONYMIZING` below.\n+\tanonymize it). See the section on <<ANONYMIZING,`ANONYMIZING`>> below.\n \n --reference-excluded-parents::\n \tBy default, running a command such as `git fast-export\n@@ -219,6 +219,7 @@ referenced by that revision range contains the string\n 'refs/heads/master'.\n \n \n+[[ANONYMIZING]]\n ANONYMIZING\n -----------\n \ndiff --git a/Documentation/git-fast-import.adoc b/Documentation/git-fast-import.adoc\nindex fd165e11d2..c5e1cec1a5 100644\n--- a/Documentation/git-fast-import.adoc\n+++ b/Documentation/git-fast-import.adoc\n@@ -31,6 +31,7 @@ imports are supported from a particular foreign source depends on\n the frontend program in use.\n \n \n+[[OPTIONS]]\n OPTIONS\n -------\n \n@@ -456,7 +457,7 @@ and control the current import process.  More detailed discussion\n \tsupports the specified feature, and aborts if it does not.\n \n `option`::\n-\tSpecify any of the options listed under OPTIONS that do not\n+\tSpecify any of the options listed under <<OPTIONS,OPTIONS>> that do not\n \tchange stream semantic to suit the frontend's needs. This\n \tcommand is optional and is not needed to perform an import.\n \n@@ -1242,7 +1243,7 @@ no-relative-marks::\n force::\n \tAct as though the corresponding command-line option with\n \ta leading `--` was passed on the command line\n-\t(see OPTIONS, above).\n+\t(see <<OPTIONS,OPTIONS>>, above).\n \n import-marks::\n import-marks-if-exists::\n@@ -1291,7 +1292,7 @@ options the user may specify to git fast-import itself.\n ....\n \n The `<option>` part of the command may contain any of the options\n-listed in the OPTIONS section that do not change import semantics,\n+listed in the <<OPTIONS,OPTIONS>> section that do not change import semantics,\n without the leading `--` and is treated in the same way.\n \n Option commands must be the first commands on the input (not counting\ndiff --git a/Documentation/git-fetch.adoc b/Documentation/git-fetch.adoc\nindex db03541915..61fed797af 100644\n--- a/Documentation/git-fetch.adoc\n+++ b/Documentation/git-fetch.adoc\n@@ -103,6 +103,7 @@ The latter use of the `remote.<repository>.fetch` values can be\n overridden by giving the `--refmap=<refspec>` parameter(s) on the\n command line.\n \n+[[PRUNING]]\n PRUNING\n -------\n \ndiff --git a/Documentation/git-filter-branch.adoc b/Documentation/git-filter-branch.adoc\nindex 5a4f853785..80a55b3706 100644\n--- a/Documentation/git-filter-branch.adoc\n+++ b/Documentation/git-filter-branch.adoc\n@@ -125,7 +125,7 @@ OPTIONS\n \tThis is the filter for rewriting the index.  It is similar to the\n \ttree filter but does not check out the tree, which makes it much\n \tfaster.  Frequently used with `git rm --cached\n-\t--ignore-unmatch ...`, see EXAMPLES below.  For hairy\n+\t--ignore-unmatch ...`, see <<EXAMPLES,EXAMPLES>> below.  For hairy\n \tcases, see linkgit:git-update-index[1].\n \n --parent-filter <command>::\n@@ -243,6 +243,7 @@ rewrite, the exit status is `2`.  On any other error, the exit status may be\n any other non-zero value.\n \n \n+[[EXAMPLES]]\n EXAMPLES\n --------\n \ndiff --git a/Documentation/git-for-each-ref.adoc b/Documentation/git-for-each-ref.adoc\nindex c02cb7f886..a7b31e8aaf 100644\n--- a/Documentation/git-for-each-ref.adoc\n+++ b/Documentation/git-for-each-ref.adoc\n@@ -64,7 +64,8 @@ For all objects, the following names can be used:\n `objectsize`::\n \tThe size of the object (the same as 'git cat-file -s' reports).\n \tAppend `:disk` to get the size, in bytes, that the object takes up on\n-\tdisk. See the note about on-disk sizes in the 'CAVEATS' section below.\n+\tdisk. See the note about on-disk sizes in the\n+\t<<CAVEATS,'CAVEATS'>> section below.\n `objectname`::\n \tThe object name (aka SHA-1).\n \tFor a non-ambiguous abbreviation of the object name append `:short`.\n@@ -448,6 +449,7 @@ This prints the authorname, if present.\n git for-each-ref --format=\"%(refname)%(if)%(authorname)%(then) Authored by: %(authorname)%(end)\"\n ------------\n \n+[[CAVEATS]]\n CAVEATS\n -------\n \ndiff --git a/Documentation/git-format-patch.adoc b/Documentation/git-format-patch.adoc\nindex 191f64b77d..a78fe564f0 100644\n--- a/Documentation/git-format-patch.adoc\n+++ b/Documentation/git-format-patch.adoc\n@@ -430,7 +430,8 @@ you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`.\n `--no-base`::\n `--base[=<commit>]`::\n \tRecord the base tree information to identify the state the\n-\tpatch series applies to.  See the BASE TREE INFORMATION section\n+\tpatch series applies to.  See the\n+\t<<BASE_TREE_INFORMATION,BASE TREE INFORMATION>> section\n \tbelow for details. If _<commit>_ is `auto`, a base commit is\n \tautomatically chosen. The `--no-base` option overrides a\n \t`format.useAutoBase` configuration.\n@@ -702,6 +703,7 @@ This should help you to submit patches inline using KMail.\n 5. Back in the compose window: add whatever other text you wish to the\n    message, complete the addressing and subject fields, and press send.\n \n+[[BASE_TREE_INFORMATION]]\n BASE TREE INFORMATION\n ---------------------\n \ndiff --git a/Documentation/git-gc.adoc b/Documentation/git-gc.adoc\nindex 6fed646dd8..5788a43215 100644\n--- a/Documentation/git-gc.adoc\n+++ b/Documentation/git-gc.adoc\n@@ -39,14 +39,15 @@ OPTIONS\n \tspace utilization and performance.  This option will cause\n \t'git gc' to more aggressively optimize the repository at the expense\n \tof taking much more time.  The effects of this optimization are\n-\tmostly persistent. See the \"AGGRESSIVE\" section below for details.\n+\tmostly persistent. See the <<AGGRESSIVE,\"AGGRESSIVE\">>\n+\tsection below for details.\n \n --auto::\n \tWith this option, 'git gc' checks whether any housekeeping is\n \trequired; if not, it exits without performing any work.\n +\n-See the `gc.auto` option in the \"CONFIGURATION\" section below for how\n-this heuristic works.\n+See the `gc.auto` option in the <<CONFIGURATION,\"CONFIGURATION\">>\n+section below for how this heuristic works.\n +\n Once housekeeping is triggered by exceeding the limits of\n configuration options such as `gc.auto` and `gc.autoPackLimit`, all\n@@ -83,7 +84,7 @@ be performed as well.\n \toverridable by the config variable `gc.pruneExpire`).\n \t--prune=now prunes loose objects regardless of their age and\n \tincreases the risk of corruption if another process is writing to\n-\tthe repository concurrently; see \"NOTES\" below. --prune is on by\n+\tthe repository concurrently; see <<NOTES,\"NOTES\">> below. --prune is on by\n \tdefault.\n \n --no-prune::\n@@ -102,6 +103,7 @@ be performed as well.\n \ta single pack. When this option is used, `gc.bigPackThreshold`\n \tis ignored.\n \n+[[AGGRESSIVE]]\n AGGRESSIVE\n ----------\n \n@@ -128,6 +130,7 @@ more time, and the resulting space/delta optimization may or may not\n be worth it. Not using this at all is the right trade-off for most\n users and their repositories.\n \n+[[CONFIGURATION]]\n CONFIGURATION\n -------------\n \n@@ -135,6 +138,7 @@ include::includes/cmd-config-section-all.adoc[]\n \n include::config/gc.adoc[]\n \n+[[NOTES]]\n NOTES\n -----\n \ndiff --git a/Documentation/git-grep.adoc b/Documentation/git-grep.adoc\nindex 19b3ade16d..dd4a7cc9e9 100644\n--- a/Documentation/git-grep.adoc\n+++ b/Documentation/git-grep.adoc\n@@ -58,7 +58,7 @@ OPTIONS\n \tin linkgit:gitglossary[7] for more information.\n +\n This option cannot be used together with `--cached` or `--untracked`.\n-See also `grep.fallbackToNoIndex` in 'CONFIGURATION' below.\n+See also `grep.fallbackToNoIndex` in <<CONFIGURATION,'CONFIGURATION'>> below.\n \n `--no-exclude-standard`::\n \tAlso search in ignored files by not honoring the `.gitignore`\n@@ -256,8 +256,9 @@ providing this option will cause it to die.\n \ta non-zero status.\n \n `--threads <num>`::\n-\tNumber of `grep` worker threads to use.  See `NOTES ON THREADS`\n-\tand `grep.threads` in 'CONFIGURATION' for more information.\n+\tNumber of `grep` worker threads to use. See\n+\t<<NOTES_ON_THREADS,`NOTES ON THREADS`>> and `grep.threads` in\n+\t<<CONFIGURATION,'CONFIGURATION'>> for more information.\n \n `-f <file>`::\n \tRead patterns from _<file>_, one per line.\n@@ -337,6 +338,7 @@ EXAMPLES\n `git grep solution -- :^Documentation`::\n \tLooks for `solution`, excluding files in `Documentation`.\n \n+[[NOTES_ON_THREADS]]\n NOTES ON THREADS\n ----------------\n \n@@ -348,6 +350,7 @@ with multiple threads might perform slower than single-threaded if `--textconv`\n is given and there are too many text conversions.  Thus, if low performance is\n experienced in this case, it might be desirable to use `--threads=1`.\n \n+[[CONFIGURATION]]\n CONFIGURATION\n -------------\n \ndiff --git a/Documentation/git-http-backend.adoc b/Documentation/git-http-backend.adoc\nindex 1dea426852..5fabc85d12 100644\n--- a/Documentation/git-http-backend.adoc\n+++ b/Documentation/git-http-backend.adoc\n@@ -18,7 +18,7 @@ The program supports clients fetching using both the smart HTTP protocol\n and the backwards-compatible dumb HTTP protocol, as well as clients\n pushing using the smart HTTP protocol. It also supports Git's\n more-efficient \"v2\" protocol if properly configured; see the\n-discussion of `GIT_PROTOCOL` in the ENVIRONMENT section below.\n+discussion of `GIT_PROTOCOL` in the <<ENVIRONMENT,ENVIRONMENT>> section below.\n \n It verifies that the directory has the magic file\n \"git-daemon-export-ok\", and it will refuse to export any Git directory\n@@ -69,6 +69,7 @@ manually in the web server configuration.  If GIT_PROJECT_ROOT is not\n set, 'git http-backend' reads PATH_TRANSLATED, which is also set\n automatically by the web server.\n \n+[[EXAMPLES]]\n EXAMPLES\n --------\n All of the following examples map `http://$hostname/git/foo/bar.git`\n@@ -257,6 +258,7 @@ $HTTP[\"url\"] =~ \"^/git/private\" {\n ----------------------------------------------------------------\n \n \n+[[ENVIRONMENT]]\n ENVIRONMENT\n -----------\n 'git http-backend' relies upon the `CGI` environment variables set\n@@ -290,7 +292,7 @@ via the `HTTP_GIT_PROTOCOL` variable, and `git-http-backend` will\n automatically copy that to `GIT_PROTOCOL`. However, some webservers may\n be more selective about which headers they'll pass, in which case they\n need to be configured explicitly (see the mention of `Git-Protocol` in\n-the Apache config from the earlier EXAMPLES section).\n+the Apache config from the earlier <<EXAMPLES,EXAMPLES>> section).\n \n The backend process sets GIT_COMMITTER_NAME to '$REMOTE_USER' and\n GIT_COMMITTER_EMAIL to '$\\{REMOTE_USER}@http.$\\{REMOTE_ADDR\\}',\ndiff --git a/Documentation/git-ls-files.adoc b/Documentation/git-ls-files.adoc\nindex 2b175388e1..14ebad8b71 100644\n--- a/Documentation/git-ls-files.adoc\n+++ b/Documentation/git-ls-files.adoc\n@@ -98,7 +98,7 @@ OPTIONS\n \n -z::\n \t\\0 line termination on output and do not quote filenames.\n-\tSee OUTPUT below for more information.\n+\tSee <<OUTPUT,OUTPUT>> below for more information.\n \n --deduplicate::\n \tWhen only filenames are shown, suppress duplicates that may\n@@ -110,8 +110,8 @@ OPTIONS\n -x <pattern>::\n --exclude=<pattern>::\n \tSkip untracked files matching pattern.\n-\tNote that pattern is a shell wildcard pattern. See EXCLUDE PATTERNS\n-\tbelow for more information.\n+\tNote that pattern is a shell wildcard pattern.\n+\tSee <<EXCLUDE_PATTERNS,EXCLUDE PATTERNS>> below for more information.\n \n -X <file>::\n --exclude-from=<file>::\n@@ -231,6 +231,7 @@ followed by the  (\"attr/<eolattr>\").\n \tFiles to show. If no files are given all files which match the other\n \tspecified criteria are shown.\n \n+[[OUTPUT]]\n OUTPUT\n ------\n 'git ls-files' just outputs the filenames unless `--stage` is specified in\n@@ -292,6 +293,7 @@ eolattr::\n path::\n \tThe pathname of the file which is recorded in the index.\n \n+[[EXCLUDE_PATTERNS]]\n EXCLUDE PATTERNS\n ----------------\n \ndiff --git a/Documentation/git-ls-tree.adoc b/Documentation/git-ls-tree.adoc\nindex 6572095d8d..29bde9366d 100644\n--- a/Documentation/git-ls-tree.adoc\n+++ b/Documentation/git-ls-tree.adoc\n@@ -54,7 +54,7 @@ OPTIONS\n \n -z::\n \t\\0 line termination on output and do not quote filenames.\n-\tSee OUTPUT FORMAT below for more information.\n+\tSee <<OUTPUT_FORMAT,OUTPUT FORMAT>> below for more information.\n \n --name-only::\n --name-status::\n@@ -99,6 +99,7 @@ OPTIONS\n \timplicitly uses the root level of the tree as the sole path argument.\n \n \n+[[OUTPUT_FORMAT]]\n Output Format\n -------------\n \ndiff --git a/Documentation/git-maintenance.adoc b/Documentation/git-maintenance.adoc\nindex bda616f14c..85f208031c 100644\n--- a/Documentation/git-maintenance.adoc\n+++ b/Documentation/git-maintenance.adoc\n@@ -95,6 +95,7 @@ in that order. Otherwise, the tasks are determined by which\n `maintenance.<task>.enabled` config options are true. By default, only\n `maintenance.gc.enabled` is true.\n \n+[[TASKS]]\n TASKS\n -----\n \n@@ -215,7 +216,7 @@ OPTIONS\n \tspecified tasks in the specified order. If no `--task=<task>`\n \targuments are specified, then only the tasks with\n \t`maintenance.<task>.enabled` configured as `true` are considered.\n-\tSee the 'TASKS' section for the list of accepted `<task>` values.\n+\tSee the <<TASKS,'TASKS'>> section for the list of accepted `<task>` values.\n \n --scheduler=auto|crontab|systemd-timer|launchctl|schtasks::\n \tWhen combined with the `start` subcommand, specify the scheduler\ndiff --git a/Documentation/git-merge-tree.adoc b/Documentation/git-merge-tree.adoc\nindex 4391bbee47..c5351f9699 100644\n--- a/Documentation/git-merge-tree.adoc\n+++ b/Documentation/git-merge-tree.adoc\n@@ -35,7 +35,7 @@ linkgit:git-merge[1], including:\n   * etc.\n \n After the merge completes, a new toplevel tree object is created.  See\n-`OUTPUT` below for details.\n+<<OUTPUT,`OUTPUT`>> below for details.\n \n OPTIONS\n -------\ndiff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc\nindex 46a232ca71..22d59ada86 100644\n--- a/Documentation/git-notes.adoc\n+++ b/Documentation/git-notes.adoc\n@@ -28,8 +28,9 @@ Adds, removes, or reads notes attached to objects, without touching\n the objects themselves.\n \n By default, notes are saved to and read from `refs/notes/commits`, but\n-this default can be overridden.  See the OPTIONS, CONFIGURATION, and\n-ENVIRONMENT sections below.  If this ref does not exist, it will be\n+this default can be overridden.  See the <<OPTIONS,OPTIONS>>,\n+<<CONFIGURATION,CONFIGURATION>>, and <<ENVIRONMENT,ENVIRONMENT>>\n+sections below. If this ref does not exist, it will be\n quietly created when it is first needed to store a note.\n \n A typical use of notes is to supplement a commit message without\n@@ -114,7 +115,8 @@ line.\n \tany) into the current notes ref (called \"local\").\n +\n If conflicts arise and a strategy for automatically resolving\n-conflicting notes (see the \"NOTES MERGE STRATEGIES\" section) is not given,\n+conflicting notes (see the\n+<<NOTES_MERGE_STRATEGIES,\"NOTES MERGE STRATEGIES\">> section) is not given,\n the `manual` resolver is used. This resolver checks out the\n conflicting notes in a special worktree (`.git/NOTES_MERGE_WORKTREE`),\n and instructs the user to manually resolve the conflicts there.\n@@ -139,6 +141,7 @@ the command line.\n \tPrint the current notes ref. This provides an easy way to\n \tretrieve the current notes ref (e.g. from scripts).\n \n+[[OPTIONS]]\n OPTIONS\n -------\n `-f`::\n@@ -225,7 +228,8 @@ future.\n \tstrategy. The following strategies are recognized: `manual`\n \t(default), `ours`, `theirs`, `union` and `cat_sort_uniq`.\n \tThis option overrides the `notes.mergeStrategy` configuration setting.\n-\tSee the \"NOTES MERGE STRATEGIES\" section below for more\n+\tSee the <<NOTES_MERGE_STRATEGIES,\"NOTES MERGE STRATEGIES\">>\n+\tsection below for more\n \tinformation on each notes merge strategy.\n \n `--commit`::\n@@ -278,6 +282,7 @@ object, in which case the history of the notes can be read with\n `git log -p -g <refname>`.\n \n \n+[[NOTES_MERGE_STRATEGIES]]\n NOTES MERGE STRATEGIES\n ----------------------\n \n@@ -361,6 +366,7 @@ include::includes/cmd-config-section-rest.adoc[]\n include::config/notes.adoc[]\n \n \n+[[ENVIRONMENT]]\n ENVIRONMENT\n -----------\n \ndiff --git a/Documentation/git-p4.adoc b/Documentation/git-p4.adoc\nindex 59edd24134..acf14cd03d 100644\n--- a/Documentation/git-p4.adoc\n+++ b/Documentation/git-p4.adoc\n@@ -119,7 +119,8 @@ importing directly from p4 is considerably slower than pulling changes\n from a Git remote, this can be useful in a multi-developer environment.\n \n If there are multiple branches, doing 'git p4 sync' will automatically\n-use the \"BRANCH DETECTION\" algorithm to try to partition new changes\n+use the <<BRANCH_DETECTION,\"BRANCH DETECTION\">> algorithm\n+to try to partition new changes\n into the right branch.  This can be overridden with the `--branch`\n option to specify just a single branch to update.\n \n@@ -245,7 +246,7 @@ Git repository:\n \n --detect-branches::\n \tUse the branch detection algorithm to find new paths in p4.  It is\n-\tdocumented below in \"BRANCH DETECTION\".\n+\tdocumented below in <<BRANCH_DETECTION,\"BRANCH DETECTION\">>.\n \n --changesfile <file>::\n \tImport exactly the p4 change numbers listed in 'file', one per\n@@ -297,7 +298,7 @@ Git repository:\n \n --use-client-spec::\n \tUse a client spec to find the list of interesting files in p4.\n-\tSee the \"CLIENT SPEC\" section below.\n+\tSee the <<CLIENT_SPEC,\"CLIENT SPEC\">> section below.\n \n -/ <path>::\n \tExclude selected depot paths when cloning or syncing.\n@@ -475,6 +476,7 @@ p4 revision specifier on the end:\n See 'p4 help revisions' for the full syntax of p4 revision specifiers.\n \n \n+[[CLIENT_SPEC]]\n CLIENT SPEC\n -----------\n The p4 client specification is maintained with the 'p4 client' command\n@@ -505,6 +507,7 @@ normal p4 mechanisms of determining the client are used:  environment\n variable `P4CLIENT`, a file referenced by `P4CONFIG`, or the local host name.\n \n \n+[[BRANCH_DETECTION]]\n BRANCH DETECTION\n ----------------\n P4 does not have the same concept of a branch as Git.  Instead,\n@@ -643,7 +646,8 @@ git-p4.labelImportRegexp::\n git-p4.useClientSpec::\n \tSpecify that the p4 client spec should be used to identify p4\n \tdepot paths of interest.  This is equivalent to specifying the\n-\toption `--use-client-spec`.  See the \"CLIENT SPEC\" section above.\n+\toption `--use-client-spec`.\n+\tSee the <<CLIENT_SPEC,\"CLIENT SPEC\">> section above.\n \tThis variable is a boolean, not the name of a p4 client.\n \n git-p4.pathEncoding::\ndiff --git a/Documentation/git-pack-objects.adoc b/Documentation/git-pack-objects.adoc\nindex 65cd00c152..ccad938c5b 100644\n--- a/Documentation/git-pack-objects.adoc\n+++ b/Documentation/git-pack-objects.adoc\n@@ -363,8 +363,8 @@ raise an error.\n \tKeep unreachable objects in loose form. This implies `--revs`.\n \n --delta-islands::\n-\tRestrict delta matches based on \"islands\". See DELTA ISLANDS\n-\tbelow.\n+\tRestrict delta matches based on \"islands\".\n+\tSee <<DELTA_ISLANDS,DELTA ISLANDS>> below.\n \n --name-hash-version=<n>::\n \tWhile performing delta compression, Git groups objects that may be\n@@ -411,6 +411,7 @@ request. The `--path-walk` option supports the `--filter=<spec>` forms\n `combine:<spec>+<spec>` form.\n \n \n+[[DELTA_ISLANDS]]\n DELTA ISLANDS\n -------------\n \ndiff --git a/Documentation/git-prune.adoc b/Documentation/git-prune.adoc\nindex 9a45571b90..d7836e625f 100644\n--- a/Documentation/git-prune.adoc\n+++ b/Documentation/git-prune.adoc\n@@ -15,7 +15,7 @@ DESCRIPTION\n -----------\n \n NOTE: In most cases, users should run 'git gc', which calls\n-'git prune'. See the section \"NOTES\", below.\n+'git prune'. See the section <<NOTES,\"NOTES\">>, below.\n \n This runs 'git fsck --unreachable' using all the refs\n available in `refs/`, optionally with an additional set of\n@@ -67,6 +67,7 @@ borrows from your repository via its\n $ git prune $(cd ../another && git rev-parse --all)\n ------------\n \n+[[NOTES]]\n NOTES\n -----\n \ndiff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc\nindex aa221c3909..e5b1023855 100644\n--- a/Documentation/git-push.adoc\n+++ b/Documentation/git-push.adoc\n@@ -132,7 +132,8 @@ as well as various other special refspec forms:\n     linkgit:git-config[1]) suggest what refs/ namespace you may have\n     wanted to push to.\n \n-Not all updates are allowed: see PUSH RULES below for the details.\n+Not all updates are allowed: see\n+<<PUSH_RULES,PUSH RULES>> below for the details.\n \n `--all`::\n `--branches`::\n@@ -337,9 +338,9 @@ allowing a forced update.\n \tUsually, `git push` will refuse to update a branch that is not an\n \tancestor of the commit being pushed.\n +\n-This flag disables that check, the other safety checks in PUSH RULES\n-below, and the checks in `--force-with-lease`. It can cause the remote\n-repository to lose commits; use it with care.\n+This flag disables that check, the other safety checks in\n+<<PUSH_RULES,PUSH RULES>> below, and the checks in `--force-with-lease`.\n+It can cause the remote repository to lose commits; use it with care.\n +\n Note that `--force` applies to all the refs that are pushed, hence\n using it with `push.default` set to `matching` or with multiple push\n@@ -568,6 +569,7 @@ reason::\n \trefs, no explanation is needed. For a failed ref, the reason for\n \tfailure is described.\n \n+[[PUSH_RULES]]\n PUSH RULES\n ----------\n \ndiff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc\nindex f6c22d1598..6536ebdc90 100644\n--- a/Documentation/git-rebase.adoc\n+++ b/Documentation/git-rebase.adoc\n@@ -17,8 +17,8 @@ SYNOPSIS\n DESCRIPTION\n -----------\n Transplant a series of commits onto a different starting point.\n-You can also use `git rebase` to reorder or combine commits: see INTERACTIVE\n-MODE below for how to do that.\n+You can also use `git rebase` to reorder or combine commits: see\n+<<INTERACTIVE_MODE,INTERACTIVE MODE>> below for how to do that.\n \n For example, imagine that you have been working on the `topic` branch in this\n history, and you want to \"catch up\" to the work done on the `master` branch.\n@@ -76,8 +76,8 @@ Here is a simplified description of what `git rebase <upstream>` does:\n 2. Check out `<upstream>` with the equivalent of\n    `git checkout --detach <upstream>`.\n 3. Replay the commits, one by one, in order. This is similar to running\n-   `git cherry-pick <commit>` for each commit. See REBASING MERGES for how merges\n-   are handled.\n+   `git cherry-pick <commit>` for each commit.\n+   See <<REBASING_MERGES,REBASING MERGES>> for how merges are handled.\n 4. Update your branch to point to the final commit with the equivalent\n    of `git checkout -B <branch>`.\n \n@@ -89,6 +89,7 @@ point to that commit at the end of the rebase if other commands that change\n tip, however, is accessible using the reflog of the current branch (i.e. `@{1}`,\n see linkgit:gitrevisions[7]).\n \n+[[TRANSPLANTING]]\n TRANSPLANTING A TOPIC BRANCH WITH --ONTO\n ----------------------------------------\n \n@@ -218,7 +219,8 @@ As a special case, you may use \"A\\...B\" as a shortcut for the\n merge base of A and B if there is exactly one merge base. You can\n leave out at most one of A and B, in which case it defaults to HEAD.\n \n-See TRANSPLANTING A TOPIC BRANCH WITH --ONTO above for examples.\n+See <<TRANSPLANTING,TRANSPLANTING A TOPIC BRANCH WITH --ONTO>>\n+above for examples.\n \n --keep-base::\n \tSet the starting point at which to create the new commits to the\n@@ -239,7 +241,7 @@ Although both this option and `--fork-point` find the merge base between\n point_ on which new commits will be created, whereas `--fork-point` uses\n the merge base to determine the _set of commits_ which will be rebased.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n <upstream>::\n \tUpstream branch to compare against.  May be any valid commit,\n@@ -254,7 +256,7 @@ See also INCOMPATIBLE OPTIONS below.\n \tinternally).  This option may become a no-op in the future\n \tonce the merge backend handles everything the apply one does.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n --empty=(drop|keep|stop)::\n \tHow to handle commits that are not empty to start and are not\n@@ -282,7 +284,7 @@ by `git log --cherry-mark ...`) are detected and dropped as a\n preliminary step (unless `--reapply-cherry-picks` or `--keep-base` is\n passed).\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n --no-keep-empty::\n --keep-empty::\n@@ -303,7 +305,7 @@ tools generate many empty commits and you want them all removed.\n For commits which do not start empty but become empty after rebasing,\n see the `--empty` flag.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n --reapply-cherry-picks::\n --no-reapply-cherry-picks::\n@@ -325,7 +327,7 @@ linkgit:git-config[1]).\n `--reapply-cherry-picks` allows rebase to forgo reading all upstream\n commits, potentially improving performance.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n --allow-empty-message::\n \tNo-op.  Rebasing commits with an empty message used to fail\n@@ -333,7 +335,7 @@ See also INCOMPATIBLE OPTIONS below.\n \twith empty messages to be rebased.  Now commits with an empty\n \tmessage do not cause rebasing to halt.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n -m::\n --merge::\n@@ -345,7 +347,7 @@ conflict happens, the side reported as 'ours' is the so-far rebased\n series, starting with `<upstream>`, and 'theirs' is the working branch.\n In other words, the sides are swapped.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n -s <strategy>::\n --strategy=<strategy>::\n@@ -357,7 +359,7 @@ on top of the `<upstream>` branch using the given strategy, using\n the `ours` strategy simply empties all patches from the `<branch>`,\n which makes little sense.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n -X <strategy-option>::\n --strategy-option=<strategy-option>::\n@@ -366,7 +368,7 @@ See also INCOMPATIBLE OPTIONS below.\n \tspecified, `-s ort`.  Note the reversal of 'ours' and\n \t'theirs' as noted above for the `-m` option.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n include::rerere-options.adoc[]\n \n@@ -408,7 +410,7 @@ include::rerere-options.adoc[]\n \tcontext exist they all must match.  By default no context is\n \tever ignored.  Implies `--apply`.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n --no-ff::\n --force-rebase::\n@@ -443,7 +445,7 @@ If your branch was based on `<upstream>` but `<upstream>` was rewound and\n your branch contains commits which were dropped, this option can be used\n with `--keep-base` in order to drop those commits from your branch.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n --ignore-whitespace::\n \tIgnore whitespace differences when trying to reconcile\n@@ -468,7 +470,7 @@ merge backend;;\n \t(see linkgit:git-apply[1]) that applies the patch.\n \tImplies `--apply`.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n --committer-date-is-author-date::\n \tInstead of using the current time as the committer date, use\n@@ -488,14 +490,14 @@ applying (in terms of the author date).\n \tthe current time as the\tauthor date of the rebased commit.  This\n \toption implies `--force-rebase`.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n --signoff::\n \tAdd a `Signed-off-by` trailer to all the rebased commits. Note\n \tthat if `--interactive` is given then only commits marked to be\n \tpicked, edited or reworded will have the trailer added.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n --trailer=<trailer>::\n \tAppend the given trailer to every rebased commit message, processed\n@@ -508,13 +510,13 @@ See also INCOMPATIBLE OPTIONS below.\n --interactive::\n \tMake a list of the commits which are about to be rebased.  Let the\n \tuser edit that list before rebasing.  This mode can also be used to\n-\tsplit commits (see SPLITTING COMMITS below).\n+\tsplit commits (see <<SPLITTING_COMMITS,SPLITTING COMMITS>> below).\n +\n The commit list format can be changed by setting the configuration option\n rebase.instructionFormat.  A customized instruction format will automatically\n have the commit hash prepended to the format.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n -r::\n --rebase-merges[=(rebase-cousins|no-rebase-cousins)]::\n@@ -542,7 +544,8 @@ It is currently only possible to recreate the merge commits using the\n `ort` merge strategy; different merge strategies can be used only via\n explicit `exec git merge -s <strategy> [...]` commands.\n +\n-See also REBASING MERGES and INCOMPATIBLE OPTIONS below.\n+See also <<REBASING_MERGES,REBASING MERGES>> and\n+<<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n -x <cmd>::\n --exec <cmd>::\n@@ -567,14 +570,14 @@ squash/fixup series.\n This uses the `--interactive` machinery internally, but it can be run\n without an explicit `--interactive`.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n --root::\n \tRebase all commits reachable from `<branch>`, instead of\n \tlimiting them with an `<upstream>`.  This allows you to rebase\n \tthe root commit(s) on a branch.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n --autosquash::\n --no-autosquash::\n@@ -600,7 +603,7 @@ Setting configuration variable `rebase.autoSquash` to true enables\n auto-squashing by default for interactive rebase.  The `--no-autosquash`\n option can be used to override that setting.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n --autostash::\n --no-autostash::\n@@ -617,8 +620,9 @@ See also INCOMPATIBLE OPTIONS below.\n +\n This option applies once a rebase is started. It is preserved for the whole\n rebase based on, in order, the command line option provided to the initial `git\n-rebase`, the `rebase.rescheduleFailedExec` configuration (see\n-linkgit:git-config[1] or \"CONFIGURATION\" below), or it defaults to false.\n+rebase`, the `rebase.rescheduleFailedExec` configuration\n+(see linkgit:git-config[1] or <<CONFIGURATION,\"CONFIGURATION\">> below),\n+or it defaults to false.\n +\n Recording this option for the whole rebase is a convenience feature. Otherwise\n an explicit `--no-reschedule-failed-exec` at the start would be overridden by\n@@ -635,8 +639,9 @@ rebase --continue` is invoked. Currently, you cannot pass\n If the configuration variable `rebase.updateRefs` is set, then this option\n can be used to override and disable this setting.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n+[[INCOMPATIBLE_OPTIONS]]\n INCOMPATIBLE OPTIONS\n --------------------\n \n@@ -813,7 +818,8 @@ NOTES\n -----\n \n You should understand the implications of using `git rebase` on a\n-repository that you share.  See also RECOVERING FROM UPSTREAM REBASE\n+repository that you share.\n+See also <<RECOVERING_FROM_UPSTREAM_REBASE,RECOVERING FROM UPSTREAM REBASE>>\n below.\n \n When the rebase is run, it will first execute a `pre-rebase` hook if one\n@@ -823,6 +829,7 @@ for an example.\n \n Upon completion, `<branch>` will be the current branch.\n \n+[[INTERACTIVE_MODE]]\n INTERACTIVE MODE\n ----------------\n \n@@ -978,6 +985,7 @@ pick f4593f9 four\n exec make test\n --------------------\n \n+[[SPLITTING_COMMITS]]\n SPLITTING COMMITS\n -----------------\n \n@@ -1013,6 +1021,7 @@ consistent (they compile, pass the testsuite, etc.) you should use\n after each commit, test, and amend the commit if fixes are necessary.\n \n \n+[[RECOVERING_FROM_UPSTREAM_REBASE]]\n RECOVERING FROM UPSTREAM REBASE\n -------------------------------\n \n@@ -1138,6 +1147,7 @@ The ripple effect of a \"hard case\" recovery is especially bad:\n 'everyone' downstream from 'topic' will now have to perform a \"hard\n case\" recovery too!\n \n+[[REBASING_MERGES]]\n REBASING MERGES\n ---------------\n \n@@ -1276,6 +1286,7 @@ merge tlsv1.3\n merge cmake\n ------------\n \n+[[CONFIGURATION]]\n CONFIGURATION\n -------------\n \ndiff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\nindex 58b4c0c470..f3ac875bb7 100644\n--- a/Documentation/git-replay.adoc\n+++ b/Documentation/git-replay.adoc\n@@ -20,7 +20,7 @@ the working tree and the index untouched. By default, updates the\n relevant references using an atomic transaction (all refs update or\n none). Use `--ref-action=print` to avoid automatic ref updates and\n instead get update commands that can be piped to `git update-ref --stdin`\n-(see the <<output,OUTPUT>> section below).\n+(see the <<OUTPUT,OUTPUT>> section below).\n \n THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.\n \n@@ -118,7 +118,7 @@ behavior of git-rebase(1)'s `--no-rebase-merges` option.)\n :git-replay: 1\n include::rev-list-options.adoc[]\n \n-[[output]]\n+[[OUTPUT]]\n OUTPUT\n ------\n \ndiff --git a/Documentation/git-repo.adoc b/Documentation/git-repo.adoc\nindex ed7d80c690..cb8c1e7292 100644\n--- a/Documentation/git-repo.adoc\n+++ b/Documentation/git-repo.adoc\n@@ -22,8 +22,8 @@ COMMANDS\n --------\n `info [--format=(lines|nul) | -z] [--all | <key>...]`::\n \tRetrieve metadata-related information about the current repository. Only\n-\tthe requested data will be returned based on their keys (see \"INFO KEYS\"\n-\tsection below).\n+\tthe requested data will be returned based on their keys\n+\t(see <<INFO_KEYS,\"INFO KEYS\">> section below).\n +\n The values are returned in the same order in which their respective keys were\n requested. The `--all` flag requests the values for all the available keys.\n@@ -89,6 +89,7 @@ supported:\n +\n `-z` is an alias for `--format=nul`.\n \n+[[INFO_KEYS]]\n INFO KEYS\n ---------\n In order to obtain a set of values from `git repo info`, you should provide\ndiff --git a/Documentation/git-rev-parse.adoc b/Documentation/git-rev-parse.adoc\nindex 5398691f3f..a6d4289e28 100644\n--- a/Documentation/git-rev-parse.adoc\n+++ b/Documentation/git-rev-parse.adoc\n@@ -38,12 +38,13 @@ Operation Modes\n Each of these options must appear first on the command line.\n \n --parseopt::\n-\tUse 'git rev-parse' in option parsing mode (see PARSEOPT section below).\n+\tUse 'git rev-parse' in option parsing mode\n+\t(see <<PARSEOPT,PARSEOPT>> section below).\n \tThe command in this mode can be used outside a repository or\n \ta working tree controlled by a repository.\n \n --sq-quote::\n-\tUse 'git rev-parse' in shell quoting mode (see SQ-QUOTE\n+\tUse 'git rev-parse' in shell quoting mode (see <<SQ_QUOTE,SQ-QUOTE>>\n \tsection below). In contrast to the `--sq` option below, this\n \tmode only does quoting. Nothing else is done to command input.\n \tThe command in this mode can be used outside a repository or\n@@ -354,6 +355,7 @@ Other Options\n \n include::revisions.adoc[]\n \n+[[PARSEOPT]]\n PARSEOPT\n --------\n \n@@ -460,6 +462,7 @@ An option group Header\n     -C[...]               option C with an optional argument\n ------------\n \n+[[SQ_QUOTE]]\n SQ-QUOTE\n --------\n \ndiff --git a/Documentation/git-send-email.adoc b/Documentation/git-send-email.adoc\nindex 5c9ab39944..4a5e0c359f 100644\n--- a/Documentation/git-send-email.adoc\n+++ b/Documentation/git-send-email.adoc\n@@ -50,7 +50,7 @@ Composing\n \n `--annotate`::\n \tReview and edit each patch you're about to send. Default is the value\n-\tof `sendemail.annotate`. See the CONFIGURATION section for\n+\tof `sendemail.annotate`. See the <<CONFIGURATION,CONFIGURATION>> section for\n \t`sendemail.multiEdit`.\n \n `--bcc=<address>,...`::\n@@ -78,7 +78,7 @@ removed.\n +\n Missing `From` or `In-Reply-To` headers will be prompted for.\n +\n-See the CONFIGURATION section for `sendemail.multiEdit`.\n+See the <<CONFIGURATION,CONFIGURATION>> section for `sendemail.multiEdit`.\n \n `--from=<address>`::\n \tSpecify the sender of the emails.  If not specified on the command line,\n@@ -559,6 +559,7 @@ Information\n \taddress to standard output, one per line. See `sendemail.aliasFile`\n \tfor more information about aliases.\n \n+[[CONFIGURATION]]\n CONFIGURATION\n -------------\n \ndiff --git a/Documentation/git-stash.adoc b/Documentation/git-stash.adoc\nindex fc6a9a008c..d6e8c4144c 100644\n--- a/Documentation/git-stash.adoc\n+++ b/Documentation/git-stash.adoc\n@@ -133,7 +133,7 @@ with no conflicts.\n `clear`::\n \tRemove all the stash entries. Note that those entries will then\n \tbe subject to pruning, and may be impossible to recover (see\n-\t'EXAMPLES' below for a possible strategy).\n+\t<<EXAMPLES,'EXAMPLES'>> below for a possible strategy).\n \n `drop [-q | --quiet] [<stash>]`::\n \tRemove a single stash entry from the list of stash entries.\n@@ -315,6 +315,7 @@ of the index, and `W` is a commit that records the state of the working\n tree.\n \n \n+[[EXAMPLES]]\n EXAMPLES\n --------\n \ndiff --git a/Documentation/git-svn.adoc b/Documentation/git-svn.adoc\nindex 2a7fa60465..baaf3bff4e 100644\n--- a/Documentation/git-svn.adoc\n+++ b/Documentation/git-svn.adoc\n@@ -126,7 +126,7 @@ your Perl's Getopt::Long is < v2.37).\n \tcommand-line argument.\n +\n This automatically updates the rev_map if needed (see\n-'$GIT_DIR/svn/\\**/.rev_map.*' in the FILES section below for details).\n+'$GIT_DIR/svn/\\**/.rev_map.*' in the <<FILES,FILES>> section below for details).\n \n --localtime;;\n \tStore Git commit times in the local time zone instead of UTC.  This\n@@ -239,7 +239,7 @@ Like 'git rebase'; this requires that the working tree be clean\n and have no uncommitted changes.\n +\n This automatically updates the rev_map if needed (see\n-'$GIT_DIR/svn/\\**/.rev_map.*' in the FILES section below for details).\n+'$GIT_DIR/svn/\\**/.rev_map.*' in the <<FILES,FILES>> section below for details).\n \n -l;;\n --local;;\n@@ -524,7 +524,7 @@ This will set the property 'svn:keywords' to 'FreeBSD=%H' for the file\n \tway to repair the repo is to use 'reset'.\n +\n Only the rev_map and refs/remotes/git-svn are changed (see\n-'$GIT_DIR/svn/\\**/.rev_map.*' in the FILES section below for details).\n+'$GIT_DIR/svn/\\**/.rev_map.*' in the <<FILES,FILES>> section below for details).\n Follow 'reset' with a 'fetch' and then 'git reset' or 'git rebase' to\n move local branches onto the new tree.\n \n@@ -946,7 +946,7 @@ copy history (including branches and tags) for repositories adopting a\n standard layout, it cannot yet represent merge history that happened\n inside git back upstream to SVN users.  Therefore it is advised that\n users keep history as linear as possible inside Git to ease\n-compatibility with SVN (see the CAVEATS section below).\n+compatibility with SVN (see the <<CAVEATS,CAVEATS>> section below).\n \n HANDLING OF SVN BRANCHES\n ------------------------\n@@ -994,6 +994,7 @@ to r.199 (one containing trunk/, one containing trunk/sub/). Finally,\n it will create a branch 'sub@200' pointing to the new parent commit of\n branch 'sub' (i.e. the commit for r.200 and trunk/sub/).\n \n+[[CAVEATS]]\n CAVEATS\n -------\n \n@@ -1135,6 +1136,7 @@ or tag has appeared. If the subset of branches or tags is changed after\n fetching, then $GIT_DIR/svn/.metadata must be manually edited to remove\n (or reset) branches-maxRev and/or tags-maxRev as appropriate.\n \n+[[FILES]]\n FILES\n -----\n $GIT_DIR/svn/\\**/.rev_map.*::\ndiff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc\nindex 32787eacc3..e6e77252ab 100644\n--- a/Documentation/git-worktree.adoc\n+++ b/Documentation/git-worktree.adoc\n@@ -50,8 +50,8 @@ at the same commit as the current branch.\n \n If a working tree is deleted without using `git worktree remove`, then\n its associated administrative files, which reside in the repository\n-(see \"DETAILS\" below), will eventually be removed automatically (see\n-`gc.worktreePruneExpire` in linkgit:git-config[1]), or you can run\n+(see <<DETAILS,\"DETAILS\">> below), will eventually be removed automatically\n+(see `gc.worktreePruneExpire` in linkgit:git-config[1]), or you can run\n `git worktree prune` in the main or any linked worktree to clean up any\n stale administrative files.\n \n@@ -360,6 +360,7 @@ share to all worktrees:\n See the documentation of `extensions.worktreeConfig` in\n linkgit:git-config[1] for more details.\n \n+[[DETAILS]]\n DETAILS\n -------\n Each linked worktree has a private sub-directory in the repository's\ndiff --git a/Documentation/gitremote-helpers.adoc b/Documentation/gitremote-helpers.adoc\nindex 39cdece16e..4d794f32ad 100644\n--- a/Documentation/gitremote-helpers.adoc\n+++ b/Documentation/gitremote-helpers.adoc\n@@ -86,7 +86,7 @@ Capabilities\n \n Each remote helper is expected to support only a subset of commands.\n The operations a helper supports are declared to Git in the response\n-to the `capabilities` command (see COMMANDS, below).\n+to the `capabilities` command (see <<COMMANDS,COMMANDS>>, below).\n \n In the following, we list all defined capabilities and for\n each we list which commands a helper with that capability\n@@ -124,7 +124,7 @@ Supported commands: 'list for-push', 'export'.\n \n If a helper advertises 'connect', Git will use it if possible and\n fall back to another capability if the helper requests so when\n-connecting (see the 'connect' command under COMMANDS).\n+connecting (see the 'connect' command under <<COMMANDS,COMMANDS>>).\n When choosing between 'push' and 'export', Git prefers 'push'.\n Other frontends may have some other order of preference.\n \n@@ -173,7 +173,7 @@ Supported commands: 'list', 'import'.\n \n If a helper advertises 'connect', Git will use it if possible and\n fall back to another capability if the helper requests so when\n-connecting (see the 'connect' command under COMMANDS).\n+connecting (see the 'connect' command under <<COMMANDS,COMMANDS>>).\n When choosing between 'fetch' and 'import', Git prefers 'fetch'.\n Other frontends may have some other order of preference.\n \n@@ -246,6 +246,7 @@ the remote repository.\n \tside using an explicit hash algorithm extension.\n \n \n+[[COMMANDS]]\n COMMANDS\n --------\n \n@@ -269,8 +270,10 @@ Support for this command is mandatory.\n \tunrecognized attributes are ignored. The list ends with a\n \tblank line.\n +\n-See REF LIST ATTRIBUTES for a list of currently defined attributes.\n-See REF LIST KEYWORDS for a list of currently defined keywords.\n+See <<REF_LIST_ATTRIBUTES,REF LIST ATTRIBUTES>> for a list of currently\n+defined attributes.\n+See <<REF_LIST_KEYWORDS,REF LIST KEYWORDS>> for a list of currently\n+defined keywords.\n +\n Supported if the helper has the \"fetch\" or \"import\" capability.\n \n@@ -435,6 +438,7 @@ completing a valid response for the current command.\n Additional commands may be supported, as may be determined from\n capabilities reported by the helper.\n \n+[[REF_LIST_ATTRIBUTES]]\n REF LIST ATTRIBUTES\n -------------------\n \n@@ -446,6 +450,7 @@ attributes are defined.\n \tThis ref is unchanged since the last import or fetch, although\n \tthe helper cannot necessarily determine what value that produced.\n \n+[[REF_LIST_KEYWORDS]]\n REF LIST KEYWORDS\n -----------------\n \ndiff --git a/Documentation/gitsubmodules.adoc b/Documentation/gitsubmodules.adoc\nindex 2082296199..8e8165637b 100644\n--- a/Documentation/gitsubmodules.adoc\n+++ b/Documentation/gitsubmodules.adoc\n@@ -21,7 +21,8 @@ A submodule is a repository embedded inside another repository.\n The submodule has its own history; the repository it is embedded\n in is called a superproject.\n \n-On the filesystem, a submodule usually (but not always - see FORMS below)\n+On the filesystem, a submodule usually\n+(but not always - see <<FORMS,FORMS>> below)\n consists of (i) a Git directory located under the `$GIT_DIR/modules/`\n directory of its superproject, (ii) a working directory inside the\n superproject's working directory, and a `.git` file at the root of\n@@ -102,8 +103,8 @@ remotes are configured in the submodule as usual in the `$GIT_DIR/config`\n file.\n \n  * The configuration file `$GIT_DIR/config` in the superproject.\n-   Git only recurses into active submodules (see \"ACTIVE SUBMODULES\"\n-   section below).\n+   Git only recurses into active submodules\n+   (see <<ACTIVE_SUBMODULES,\"ACTIVE SUBMODULES\">> section below).\n +\n If the submodule is not yet initialized, then the configuration\n inside the submodule does not exist yet, so where to\n@@ -122,6 +123,7 @@ If the submodule has never been initialized, this is the only place\n where submodule configuration is found. It serves as the last fallback\n to specify where to obtain the submodule from.\n \n+[[FORMS]]\n FORMS\n -----\n \n@@ -165,6 +167,7 @@ from another repository.\n To completely remove a submodule, manually delete\n `$GIT_DIR/modules/<name>/`.\n \n+[[ACTIVE_SUBMODULES]]\n ACTIVE SUBMODULES\n -----------------\n \ndiff --git a/Documentation/gitworkflows.adoc b/Documentation/gitworkflows.adoc\nindex 59305265c5..4a4aea9fb4 100644\n--- a/Documentation/gitworkflows.adoc\n+++ b/Documentation/gitworkflows.adoc\n@@ -245,8 +245,9 @@ tag to the tip of 'master' indicating the release version:\n `git tag -s -m \"Git X.Y.Z\" vX.Y.Z master`\n =====================================\n \n-You need to push the new tag to a public Git server (see\n-\"DISTRIBUTED WORKFLOWS\" below). This makes the tag available to\n+You need to push the new tag to a public Git server\n+(see <<DISTRIBUTED_WORKFLOWS,\"DISTRIBUTED WORKFLOWS\">> below).\n+This makes the tag available to\n others tracking your project. The push could also trigger a\n post-update hook to perform release-related items such as building\n release tarballs and preformatted documentation pages.\n@@ -324,6 +325,7 @@ announcement is not necessary since 'seen' is a throw-away branch, as\n described above.\n \n \n+[[DISTRIBUTED_WORKFLOWS]]\n DISTRIBUTED WORKFLOWS\n ---------------------\n \ndiff --git a/Documentation/howto/revert-a-faulty-merge.adoc b/Documentation/howto/revert-a-faulty-merge.adoc\nindex 19f59cc888..fc9a330e9c 100644\n--- a/Documentation/howto/revert-a-faulty-merge.adoc\n+++ b/Documentation/howto/revert-a-faulty-merge.adoc\n@@ -146,8 +146,8 @@ different resolution strategies:\n    revert of a merge was rebuilt from scratch (i.e. rebasing and fixing,\n    as you seem to have interpreted), then re-merging the result without\n    doing anything else fancy would be the right thing to do.\n-   (See the ADDENDUM below for how to rebuild a branch from scratch\n-   without changing its original branching-off point.)\n+   (See the <<ADDENDUM,ADDENDUM>> below for how to rebuild a branch\n+   from scratch without changing its original branching-off point.)\n \n However, there are things to keep in mind when reverting a merge (and\n reverting such a revert).\n@@ -184,6 +184,7 @@ ready yet, and I really need to undo _all_ of the merge\"). So then you\n really should revert the merge, but when you want to re-do the merge, you\n now need to do it by reverting the revert.\n \n+[[ADDENDUM]]\n ADDENDUM\n \n Sometimes you have to rewrite one of a topic branch's commits *and* you can't\ndiff --git a/Documentation/revisions.adoc b/Documentation/revisions.adoc\nindex 3fbfbd3d5f..3bb6dc85b6 100644\n--- a/Documentation/revisions.adoc\n+++ b/Documentation/revisions.adoc\n@@ -1,3 +1,4 @@\n+[[SPECIFYING_REVISIONS]]\n SPECIFYING REVISIONS\n --------------------\n \n@@ -300,7 +301,8 @@ Dotted Range Notations\n The '..' (two-dot) Range Notation::\n  The '{caret}r1 r2' set operation appears so often that there is a shorthand\n  for it.  When you have two commits 'r1' and 'r2' (named according\n- to the syntax explained in SPECIFYING REVISIONS above), you can ask\n+ to the syntax explained in\n+<<SPECIFYING_REVISIONS,SPECIFYING REVISIONS>> above), you can ask\n  for commits that are reachable from r2 excluding those that are reachable\n  from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.\n \n\nbase-commit: 3bc0341126508f78f5869cbfc0005e987efdf0c7\n-- \ngitgitgadget\n"},{"id":"553012","messageId":"xmqq4ifhdon2.fsf@gitster.g","threadId":"66371","inReplyTo":"pull.2416.git.git.1790105342890.gitgitgadget@gmail.com","subject":"Re: [PATCH] doc: add more AsciiDoc cross-references","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-09-22T20:20:17Z","receivedAt":"2026-09-22T20:20:25Z","isPatch":true,"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> From: Julia Evans <julia@jvns.ca>\n>\n> Instead of saying \"see EXAMPLES below\", say \"see <<EXAMPLES,EXAMPLES>>\n> below\" to make the man pages easier to navigate on the web.\n>\n> The reason for using the more verbose <<EXAMPLES,EXAMPLES>>\n> (instead of <<EXAMPLES>>) is that if the header that `<<EXAMPLES>>`\n> is referring to is in an included page (for example `REMOTES` in the\n> `git-push` man page), then AsciiDoc will think it's a broken link even\n> though it isn't. So it's easier to just make all of the links use the\n> form with two parts.\n>\n> Signed-off-by: Julia Evans <julia@jvns.ca>\n> ---\n\nOh, I love a change that is so sharply focused on a single issue and\ndescribes what the problem being solved is.\n\n>      * I tested it by running this script\n>        (https://gist.github.com/jvns/039c8ed0add092f2179f0dba52ebb896) which\n>        builds the previous and current views of all the man pages. I looked\n>        at the output to make sure there were no differences. You can see the\n>        output in that gist.\n>      * I believe that asciidoctor will automatically make sure that there\n>        are no broken links.\n>      * I also spot checked some of the HTML output to make sure it looked\n>        reasonable.\n\n> diff --git a/Documentation/fetch-options.adoc b/Documentation/fetch-options.adoc\n> index 035f780e58..47dea1de8e 100644\n> --- a/Documentation/fetch-options.adoc\n> +++ b/Documentation/fetch-options.adoc\n> @@ -199,7 +199,7 @@ endif::git-pull[]\n>  \tproviding the tag refspec.\n>  ifndef::git-pull[]\n>  +\n> -See the PRUNING section below for more details.\n> +See the <<PRUNING,PRUNING>> section below for more details.\n\nOK, we already see an example of the <<double,double>> reference\nnotation.  This needs to be in this form, intead of <<pruning>>,\nbecause it refers to the named section of a different file, namely\ngit-fetch.adoc (I am just trying to make sure I understood your\nexplanation correctly).\n\n> @@ -210,7 +210,7 @@ See the PRUNING section below for more details.\n>  \ta shorthand for providing the explicit tag refspec along with\n>  \t`--prune`, see the discussion about that in its documentation.\n>  +\n> -See the PRUNING section below for more details.\n> +See the <<PRUNING,PRUNING>> section below for more details.\n\nDitto.\n\n> diff --git a/Documentation/git-bundle.adoc b/Documentation/git-bundle.adoc\n> index 03cd36fe8d..cd722bd674 100644\n> --- a/Documentation/git-bundle.adoc\n> +++ b/Documentation/git-bundle.adoc\n> @@ -94,7 +94,8 @@ unbundle <file>::\n>  \n>  <git-rev-list-args>::\n>  \tA list of arguments, acceptable to 'git rev-parse' and\n> -\t'git rev-list' (and containing a named ref, see SPECIFYING REFERENCES\n> +\t'git rev-list' (and containing a named ref, see\n> +\t<<SPECIFYING_REFERENCES,SPECIFYING REFERENCES>>\n>  \tbelow), that specifies the specific objects and references\n>  \tto transport.  For example, `master~10..master` causes the\n>  \tcurrent master reference to be packaged along with all objects\n\nThis doubled reference is more for consistency (in other words, \"it\nis easier to just make all of the links use the form\") than the\n\"cross references from/to included page\" we saw earlier, since ...\n\n> @@ -127,6 +128,7 @@ unbundle <file>::\n>  \tThis flag makes the command not to report its progress\n>  \ton the standard error stream.\n>  \n> +[[SPECIFYING_REFERENCES]]\n>  SPECIFYING REFERENCES\n>  ---------------------\n\n... the target happens to live in the same file.  It of course\nfuture-proofs the reference in case the section gets split out of\nthe file into another included one.\n\nThanks, will queue.\n"},{"id":"553018","messageId":"665e8f8d-7bde-449b-a390-10875135cba2@app.fastmail.com","threadId":"66371","inReplyTo":"xmqq4ifhdon2.fsf@gitster.g","subject":"Re: [PATCH] doc: add more AsciiDoc cross-references","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-09-22T20:54:17Z","receivedAt":"2026-09-22T20:54:44Z","isPatch":true,"body":"\n> Oh, I love a change that is so sharply focused on a single issue and\n> describes what the problem being solved is.\n\n:)\n\n>>      * I tested it by running this script\n>>        (https://gist.github.com/jvns/039c8ed0add092f2179f0dba52ebb896) which\n>>        builds the previous and current views of all the man pages. I looked\n>>        at the output to make sure there were no differences. You can see the\n>>        output in that gist.\n>>      * I believe that asciidoctor will automatically make sure that there\n>>        are no broken links.\n>>      * I also spot checked some of the HTML output to make sure it looked\n>>        reasonable.\n>\n>> diff --git a/Documentation/fetch-options.adoc b/Documentation/fetch-options.adoc\n>> index 035f780e58..47dea1de8e 100644\n>> --- a/Documentation/fetch-options.adoc\n>> +++ b/Documentation/fetch-options.adoc\n>> @@ -199,7 +199,7 @@ endif::git-pull[]\n>>  \tproviding the tag refspec.\n>>  ifndef::git-pull[]\n>>  +\n>> -See the PRUNING section below for more details.\n>> +See the <<PRUNING,PRUNING>> section below for more details.\n>\n> OK, we already see an example of the <<double,double>> reference\n> notation.  This needs to be in this form, intead of <<pruning>>,\n> because it refers to the named section of a different file, namely\n> git-fetch.adoc (I am just trying to make sure I understood your\n> explanation correctly).\n\nThe reason I explained this in a bit of a confusing way is that I'm not\n100% sure in which exact cases we need to use <<double,double>\ninstead of <<single>.\n\nI double checked just now that if in `git-push.adoc`, I change:\n\n\tof a remote (see the section <<REMOTES,REMOTES>> below),\n\nto:\n\n\tof a remote (see the section <<REMOTES>> below),\n\nThen there's a problem where in the HTML version it displays as\n\"[REMOTES]\" instead of just \"REMOTES\".\n\nBut in the <<PRUNING,PRUNING>> example, just using <<PRUNING>>\nseems to work. I started working on this way back in December 2025 \nso I assume that something in this patch was affected by this issue\nand that's how I came across this problem but I'm not sure exactly\nwhat it was.\n"},{"id":"553098","messageId":"7532313e-4705-4e2f-b36d-f2329d70ac6a@app.fastmail.com","threadId":"66371","inReplyTo":"pull.2416.git.git.1790105342890.gitgitgadget@gmail.com","subject":"Re: [PATCH] doc: add more AsciiDoc cross-references","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-09-23T19:06:44Z","receivedAt":"2026-09-23T19:07:08Z","isPatch":true,"body":"On Tue, Sep 22, 2026, at 21:29, Julia Evans via GitGitGadget wrote:\n> From: Julia Evans <julia@jvns.ca>\n>\n> Instead of saying \"see EXAMPLES below\", say \"see <<EXAMPLES,EXAMPLES>>\n> below\" to make the man pages easier to navigate on the web.\n>\n> The reason for using the more verbose <<EXAMPLES,EXAMPLES>>\n> (instead of <<EXAMPLES>>) is that if the header that `<<EXAMPLES>>`\n> is referring to is in an included page (for example `REMOTES` in the\n> `git-push` man page), then AsciiDoc will think it's a broken link even\n> though it isn't. So it's easier to just make all of the links use the\n> form with two parts.\n>\n> Signed-off-by: Julia Evans <julia@jvns.ca>\n> ---\n>[snip]\n\nNow that I’ve read this commit message, it seems like an obvious idea\nin hindsight.\n"},{"id":"553120","messageId":"20260923214038.GA49087@coredump.intra.peff.net","threadId":"66371","inReplyTo":"665e8f8d-7bde-449b-a390-10875135cba2@app.fastmail.com","subject":"Re: [PATCH] doc: add more AsciiDoc cross-references","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2026-09-23T21:40:38Z","receivedAt":"2026-09-23T21:40:40Z","isPatch":true,"body":"On Tue, Sep 22, 2026 at 04:54:17PM -0400, Julia Evans wrote:\n\n> >> +See the <<PRUNING,PRUNING>> section below for more details.\n> >\n> > OK, we already see an example of the <<double,double>> reference\n> > notation.  This needs to be in this form, intead of <<pruning>>,\n> > because it refers to the named section of a different file, namely\n> > git-fetch.adoc (I am just trying to make sure I understood your\n> > explanation correctly).\n> \n> The reason I explained this in a bit of a confusing way is that I'm not\n> 100% sure in which exact cases we need to use <<double,double>\n> instead of <<single>.\n> \n> I double checked just now that if in `git-push.adoc`, I change:\n> \n> \tof a remote (see the section <<REMOTES,REMOTES>> below),\n> \n> to:\n> \n> \tof a remote (see the section <<REMOTES>> below),\n> \n> Then there's a problem where in the HTML version it displays as\n> \"[REMOTES]\" instead of just \"REMOTES\".\n\nReading the asciidoc docs, I'm not sure how this is affected by the\nlocation of the reference at all. AFAICT the syntax <<FOO,BAR>> just\nmeans \"link to FOO, using the text BAR\".\n\nThe single-item <<FOO>> more or less means the same as \"<<FOO,FOO>>\",\nbut as you noticed, vanilla asciidoc seems to pick the text \"[FOO]\"\nhere, whereas asciidoctor uses \"FOO\". I'm using asciidoc 10.2.1 and\nasciidoctor 2.0.26 to test, and I see it even with the PRUNING examples,\ntoo.\n\nEven weirder, in the manpage output both implementations actually expand\nthis to: the section called \"FOO\". So changing your patch like this:\n\n  -See the <<PRUNING,PRUNING>> section below for more details.\n  +See the <<PRUNING>> section below for more details.\n\ngives doc-diff output like this:\n\n  -         See the PRUNING section below for more details.\n  +         See the the section called “PRUNING” section below for more details.\n\nwhich is obviously nonsense.\n\nI could very well believe that some older versions did other weird\nthings in the presence of includes. ;) But AFAICT the real need for the\ndoubled text is to control what is in the expanded text (both because of\ndifferences between the versions, but also differences in output\nbackends).\n\nWhich is kind of a shame, because writing just <<PRUNING>> makes the\nsource a lot more readable. I wonder if we can configure these text\nfallbacks, which would let us use the single-item form reliably.\n\nAlternatively, I think this is all syntactic sugar over \"xref:FOO[BAR]\".\nWe already have our own linkgit: macro for linking to whole pages\n(which, btw, is something xref could do for us, too, though maybe not\nwithout the magic man section number). I wonder if it would be useful to\nhave a section-link macro that would give us more control, but again,\nthe syntax of <<PRUNING>> sure is nice.\n\n> But in the <<PRUNING,PRUNING>> example, just using <<PRUNING>>\n> seems to work. I started working on this way back in December 2025 \n> so I assume that something in this patch was affected by this issue\n> and that's how I came across this problem but I'm not sure exactly\n> what it was.\n\nSo I think using <<PRUNING,PRUNING>> is probably OK for a first pass\nhere, rather than getting bogged down in trying to configure both\nasciidoc implementations. We can shrink them later if we come up with a\ngood solution.\n\nI do think the explanation in the commit message might be misleading,\nthough (at least from what I can gather from the asciidoc reference and\nfrom a few experiments).\n\n-Peff\n"},{"id":"553125","messageId":"20260923220053.GB49087@coredump.intra.peff.net","threadId":"66371","inReplyTo":"pull.2416.git.git.1790105342890.gitgitgadget@gmail.com","subject":"Re: [PATCH] doc: add more AsciiDoc cross-references","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2026-09-23T22:00:53Z","receivedAt":"2026-09-23T22:00:54Z","isPatch":true,"body":"On Tue, Sep 22, 2026 at 07:29:02PM +0000, Julia Evans via GitGitGadget wrote:\n\n> diff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc\n> index 16b06e38e1..906db7ccf3 100644\n> --- a/Documentation/git-add.adoc\n> +++ b/Documentation/git-add.adoc\n> @@ -117,7 +117,7 @@ The intent of this option is to pick and choose lines of the patch to\n>  apply, or even to modify the contents of lines to be staged. This can be\n>  quicker and more flexible than using the interactive hunk selector.\n>  However, it is easy to confuse oneself and create a patch that does not\n> -apply to the index. See EDITING PATCHES below.\n> +apply to the index. See <<EDITING_PATCHES,EDITING PATCHES>> below.\n>  \n>  `-u`::\n>  `--update`::\n> @@ -375,6 +375,7 @@ diff::\n>    `HEAD` and index).\n>  \n>  \n> +[[EDITING_PATCHES]]\n>  EDITING PATCHES\n>  ---------------\n\nI think we have section auto-ids enabled these days, so I don't think\nit's strictly necessary to make our own ids like this. But the generated\nids are syntactically a little different, so you'd need:\n\n-apply to the index. See <<EDITING_PATCHES,EDITING PATCHES>> below.\n+apply to the index. See <<_editing_patches,EDITING PATCHES>> below.\n\nThe asciidoctor reference made some mention of linking to sections\ndirectly by title (a \"Natural cross reference\"). But it did not seem to\nwork for me in this case, and anyway I think it only works with the\nsingle-argument form (which has other headaches).\n\nSo we could probably get away with using the auto-generated ones, but\nit does mean using their syntax. Though there is another related issue\nthere: these ids are also somewhat user-visible, because they end up in\nthe final HTML documents and people link to them.\n\nRight now this works:\n\n  https://git-scm.com/docs/git-add#_editing_patches\n\nbut after your patch, I think it will have to be spelled as:\n\n  https://git-scm.com/docs/git-add#EDITING_PATCHES\n\nI think I prefer the all-caps one, but it is kind of gross that as we\nchange the docs we may break fragment links across the web. IIRC there\nare similar problems with linking to list items, where we auto-generate\nids to allow linking to specific options (this is custom code on\ngit-scm.com, not asciidoctor and not within git.git). The resulting\nfragment ids are long and gross and have changed a few times over the\nyears (I think we had to add in some disambiguation because multiple\nlists in the same file might generate the same id).\n\nSo I dunno what all that means. Your patch \"breaks\" existing links into\nthe HTML by assigning a new (but IMHO prettier) id. At some point I\ndon't know how much we want to care about that. But I thought it was\nworth ignoring consciously rather than accidentally. ;)\n\n> -See the \"OBJECT PREREQUISITES\" section below.\n> +See the <<OBJECT_PREREQUISITES,\"OBJECT PREREQUISITES\">> section below.\n\nI noticed a few interesting typographic bits, like this one. I'd have\nexpected:\n\n  \"<<OBJECT_PREREQUISITES,OBJECT PREREQUISITES>>\"\n\nbut I guess this is one of the inconsistencies you mentioned in the\ncover letter. I'm fine punting on those for now and fixing them later.\n\nEspecially this one:\n\n> -\t  `BATCH OUTPUT` below for details.\n> +\t  <<BATCH_OUTPUT,`BATCH OUTPUT`>> below for details.\n\nwhich can't move the backticks out (because they'd suppress the xref\nsyntax). But probably it ought to drop the backticks entirely (which\nagain can come later).\n\n-Peff\n"},{"id":"553176","messageId":"63520573-c8a7-41bd-aaeb-bfc2b5e43856@app.fastmail.com","threadId":"66371","inReplyTo":"20260923214038.GA49087@coredump.intra.peff.net","subject":"Re: [PATCH] doc: add more AsciiDoc cross-references","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-09-24T12:30:31Z","receivedAt":"2026-09-24T12:30:52Z","isPatch":true,"body":"\n> Even weirder, in the manpage output both implementations actually expand\n> this to: the section called \"FOO\". So changing your patch like this:\n>\n>   -See the <<PRUNING,PRUNING>> section below for more details.\n>   +See the <<PRUNING>> section below for more details.\n>\n> gives doc-diff output like this:\n>\n>   -         See the PRUNING section below for more details.\n>   +         See the the section called “PRUNING” section below for more details.\n>\n> which is obviously nonsense.\n>\n> I could very well believe that some older versions did other weird\n> things in the presence of includes. ;) But AFAICT the real need for the\n> doubled text is to control what is in the expanded text (both because of\n> differences between the versions, but also differences in output\n> backends).\n>\n> Which is kind of a shame, because writing just <<PRUNING>> makes the\n> source a lot more readable. I wonder if we can configure these text\n> fallbacks, which would let us use the single-item form reliably.\n\nThanks for investigating, I was really dreading looking into the guts of\nasciidoc to figure out exactly what was happening. It would be nice to be able\nto write just <<PRUNING>>, especially because I believe asciidoctor will check\nthat internal links are valid, so there's no concern about breaking links if we\nchange the title of a section.\n\nRe your other message about breaking links because we're changing the\nHTML IDs: the options I see right now are\n\n1. Leave it is as is and break some links\n2. manually enter the ID like `_editing_patches`, trying to make sure to always\nmatch the auto-generated ID (I'm not sure how to do that). I think this might\nalso cause some confusion for editors in the future as to why the section IDs\nare formatted like that\n3. Somehow fix it so that we can just do <<PRUNING>>\n\nI'm not sure if #1 or #2 is better, obviously I'm biased towards #1 because\nit's less work for me. #3 seems like the ideal but I don't know how to do that.\n\nHere's a revised commit message, can submit that as a v2 if it seems correct.\n\n    doc: add more AsciiDoc cross-references\n\n    Instead of saying \"see EXAMPLES below\", say \"see <<EXAMPLES,EXAMPLES>>\n    below\" to make the man pages easier to navigate on the web.\n\n    The reason for using the more verbose <<EXAMPLES,EXAMPLES>>\n    (instead of <<EXAMPLES>>) is in some cases, the HTML output is rendered\n    as `\"EXAMPLES\"` or `[EXAMPLES]` instead of just `EXAMPLES`.\n    So this gives us more control over how the output looks.\n\n    This also changes some of the HTML IDs of the headings from `_examples`\n    to `EXAMPLES`, which has the potential to break some links.\n"},{"id":"553202","messageId":"20260924155517.GB736248@coredump.intra.peff.net","threadId":"66371","inReplyTo":"63520573-c8a7-41bd-aaeb-bfc2b5e43856@app.fastmail.com","subject":"Re: [PATCH] doc: add more AsciiDoc cross-references","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2026-09-24T15:55:17Z","receivedAt":"2026-09-24T15:55:19Z","isPatch":true,"body":"On Thu, Sep 24, 2026 at 08:30:31AM -0400, Julia Evans wrote:\n\n> Thanks for investigating, I was really dreading looking into the guts of\n> asciidoc to figure out exactly what was happening. It would be nice to be able\n> to write just <<PRUNING>>, especially because I believe asciidoctor will check\n> that internal links are valid, so there's no concern about breaking links if we\n> change the title of a section.\n\nI think asciidoc(tor) doesn't do it itself, so HTML will be generated\nwith a broken link. But in the manpage flow, we pass through xml\ndocbook, which does complain loudly. So that will be enough to let us\nknow about the breakage.\n\n> 1. Leave it is as is and break some links\n> 2. manually enter the ID like `_editing_patches`, trying to make sure to always\n> match the auto-generated ID (I'm not sure how to do that). I think this might\n> also cause some confusion for editors in the future as to why the section IDs\n> are formatted like that\n> 3. Somehow fix it so that we can just do <<PRUNING>>\n> \n> I'm not sure if #1 or #2 is better, obviously I'm biased towards #1 because\n> it's less work for me. #3 seems like the ideal but I don't know how to do that.\n\nYeah, sorry I was a bit rambly in my other message, but I think #1 is\nOK. I'm not sure if asciidoctor allows us to configure the algorithm for\nconverting a title into a section id. If it does, it might be nice to\nhave a flag day where we make all of the auto-ids look like what we'd\nexpect. But that is a totally separate topic, and can happen later.\n\nI think #3 is sort-of orthogonal, as I couldn't get the \"natural\" xrefs\nto work. So we have to either declare the ids ourselves or use the\nauto-generated ones, at which point the use of single- or double-\n<<FOO>> xrefs is purely a matter for the linking site, not the linked-to\nsection.\n\n> Here's a revised commit message, can submit that as a v2 if it seems correct.\n> \n>     doc: add more AsciiDoc cross-references\n> \n>     Instead of saying \"see EXAMPLES below\", say \"see <<EXAMPLES,EXAMPLES>>\n>     below\" to make the man pages easier to navigate on the web.\n> \n>     The reason for using the more verbose <<EXAMPLES,EXAMPLES>>\n>     (instead of <<EXAMPLES>>) is in some cases, the HTML output is rendered\n>     as `\"EXAMPLES\"` or `[EXAMPLES]` instead of just `EXAMPLES`.\n>     So this gives us more control over how the output looks.\n> \n>     This also changes some of the HTML IDs of the headings from `_examples`\n>     to `EXAMPLES`, which has the potential to break some links.\n\nYeah, I think this is OK. If we want to be really pedantic, the\n\"EXAMPLES\" with quotes is only in the manpages, not the HTML (and also\nincludes extra text: \"the section called\"). But the point is the same.\nWe must use the doubled form to get consistent text output.\n\n-Peff\n"},{"id":"553212","messageId":"xmqqse2y371a.fsf@gitster.g","threadId":"66371","inReplyTo":"63520573-c8a7-41bd-aaeb-bfc2b5e43856@app.fastmail.com","subject":"Re: [PATCH] doc: add more AsciiDoc cross-references","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-09-24T17:15:13Z","receivedAt":"2026-09-24T17:15:16Z","isPatch":true,"body":"\"Julia Evans\" <julia@jvns.ca> writes:\n\n> Here's a revised commit message, can submit that as a v2 if it seems correct.\n>\n>     doc: add more AsciiDoc cross-references\n>\n>     Instead of saying \"see EXAMPLES below\", say \"see <<EXAMPLES,EXAMPLES>>\n>     below\" to make the man pages easier to navigate on the web.\n>\n>     The reason for using the more verbose <<EXAMPLES,EXAMPLES>>\n>     (instead of <<EXAMPLES>>) is in some cases, the HTML output is rendered\n>     as `\"EXAMPLES\"` or `[EXAMPLES]` instead of just `EXAMPLES`.\n>     So this gives us more control over how the output looks.\n>\n>     This also changes some of the HTML IDs of the headings from `_examples`\n>     to `EXAMPLES`, which has the potential to break some links.\n\nTo see if I understand correctly, let me rephrase the second\nparagraph a bit (not as an attempt to offer an improvement; by\nrestating the above differently while expressing what I take to be\nthe same thing, we will see whether I misunderstood what you wrote\nif my version ends up saying what you did not intend), as I found it\nsomewhat puzzling.\n\n    The short form <<EXAMPLES>> uses EXAMPLES as both the link\n    target (which is not shown to the end user except in the\n    browser's location bar when the link is visited) and the\n    clickable text.  In different parts of the document, however,\n    the text in HTML may need to be rendered as \"EXAMPLES\" or\n    [EXAMPLES], which can be achieved by using the\n    <<EXAMPLES,\"EXAMPLES\">> or <<EXAMPLES,[EXAMPLES]>> form.  For\n    consistency, always use the longer form, even when there are no\n    such typesetting constraints.\n\nI'll mark the topic as Expecting a reroll in my working copy of the\n\"What's cooking\" report of the next issue.\n\nThanks.\n\n"},{"id":"553214","messageId":"31577b6f-79b6-456f-9ecd-d1a3df6209e2@app.fastmail.com","threadId":"66371","inReplyTo":"xmqqse2y371a.fsf@gitster.g","subject":"Re: [PATCH] doc: add more AsciiDoc cross-references","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-09-24T17:22:49Z","receivedAt":"2026-09-24T17:23:10Z","isPatch":true,"body":"\n> To see if I understand correctly, let me rephrase the second\n> paragraph a bit (not as an attempt to offer an improvement; by\n> restating the above differently while expressing what I take to be\n> the same thing, we will see whether I misunderstood what you wrote\n> if my version ends up saying what you did not intend), as I found it\n> somewhat puzzling.\n>\n>     The short form <<EXAMPLES>> uses EXAMPLES as both the link\n>     target (which is not shown to the end user except in the\n>     browser's location bar when the link is visited) and the\n>     clickable text.  In different parts of the document, however,\n>     the text in HTML may need to be rendered as \"EXAMPLES\" or\n>     [EXAMPLES], which can be achieved by using the\n>     <<EXAMPLES,\"EXAMPLES\">> or <<EXAMPLES,[EXAMPLES]>> form.  For\n>     consistency, always use the longer form, even when there are no\n>     such typesetting constraints.\n\nI meant something different, let me try again (with Peff's corrections as well):\n\n    The reason for using the more verbose <<EXAMPLES,EXAMPLES>>\n    (instead of <<EXAMPLES>>) is that in some cases, <<EXAMPLES>> is\n    rendered as `the section called \"EXAMPLES\"` or `[EXAMPLES]`.\n    <<EXAMPLES,EXAMPLES>> is rendered as just `EXAMPLES`, which gives us\n    more control over the output.\n\n(\"in some cases\" is code for \"I still don't fully understand\nexactly when each one happens and why\")\n\n> I'll mark the topic as Expecting a reroll in my working copy of the\n> \"What's cooking\" report of the next issue.\n>\n> Thanks.\n"},{"id":"553220","messageId":"xmqq4ife344q.fsf@gitster.g","threadId":"66371","inReplyTo":"31577b6f-79b6-456f-9ecd-d1a3df6209e2@app.fastmail.com","subject":"Re: [PATCH] doc: add more AsciiDoc cross-references","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-09-24T18:17:57Z","receivedAt":"2026-09-24T18:18:00Z","isPatch":true,"body":"\"Julia Evans\" <julia@jvns.ca> writes:\n\n>> To see if I understand correctly, let me rephrase the second\n>> paragraph a bit (not as an attempt to offer an improvement; by\n>> restating the above differently while expressing what I take to be\n>> the same thing, we will see whether I misunderstood what you wrote\n>> if my version ends up saying what you did not intend), as I found it\n>> somewhat puzzling.\n>>\n>>     The short form <<EXAMPLES>> uses EXAMPLES as both the link\n>>     target (which is not shown to the end user except in the\n>>     browser's location bar when the link is visited) and the\n>>     clickable text.  In different parts of the document, however,\n>>     the text in HTML may need to be rendered as \"EXAMPLES\" or\n>>     [EXAMPLES], which can be achieved by using the\n>>     <<EXAMPLES,\"EXAMPLES\">> or <<EXAMPLES,[EXAMPLES]>> form.  For\n>>     consistency, always use the longer form, even when there are no\n>>     such typesetting constraints.\n>\n> I meant something different, let me try again (with Peff's corrections as well):\n>\n>     The reason for using the more verbose <<EXAMPLES,EXAMPLES>>\n>     (instead of <<EXAMPLES>>) is that in some cases, <<EXAMPLES>> is\n>     rendered as `the section called \"EXAMPLES\"` or `[EXAMPLES]`.\n>     <<EXAMPLES,EXAMPLES>> is rendered as just `EXAMPLES`, which gives us\n>     more control over the output.\n>\n> (\"in some cases\" is code for \"I still don't fully understand\n> exactly when each one happens and why\")\n\nI see.  I think I understand now.\n\nIn your example, \"leaving it vanilla without any extra adornment\" is\nthe control you want to gain by using the two-argument form, while in\nthe version that shows my (mis)understanding, it is \"you can mark up\nthe string that is shown in any way you want\".\n\nEither way, the shorthand form forces you to leave the rendering to\nthe toolchain, but the two-argument form gives you more control over\nhow the text is rendered.\n\nThanks.\n"},{"id":"553223","messageId":"20260924184220.GA747880@coredump.intra.peff.net","threadId":"66371","inReplyTo":"31577b6f-79b6-456f-9ecd-d1a3df6209e2@app.fastmail.com","subject":"Re: [PATCH] doc: add more AsciiDoc cross-references","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2026-09-24T18:42:20Z","receivedAt":"2026-09-24T18:42:24Z","isPatch":true,"body":"On Thu, Sep 24, 2026 at 01:22:49PM -0400, Julia Evans wrote:\n\n> I meant something different, let me try again (with Peff's corrections as well):\n> \n>     The reason for using the more verbose <<EXAMPLES,EXAMPLES>>\n>     (instead of <<EXAMPLES>>) is that in some cases, <<EXAMPLES>> is\n>     rendered as `the section called \"EXAMPLES\"` or `[EXAMPLES]`.\n>     <<EXAMPLES,EXAMPLES>> is rendered as just `EXAMPLES`, which gives us\n>     more control over the output.\n> \n> (\"in some cases\" is code for \"I still don't fully understand\n> exactly when each one happens and why\")\n\nI think it's just \"depending on the implementation and output backends\".\nThe complete table I saw is:\n\n              |  HTML   | manpage\n  ----------------------------------------------\n  asciidoc    |  [FOO]  | the section called \"FOO\"\n  asciidoctor |  FOO    | the section called \"FOO\"\n\nI'm not sure if the manpage expansion is asciidoc itself, though, or\ndocbook. I guess that should be easy to test...\n\nAh, yeah, it's docbook. Using <<PRUNING>>, the xml generated by asciidoc\nlooks like this:\n\n  and the <xref linkend=\"PRUNING\"/> section of\n\nand then the roff output from docbook becomes:\n\n  and the\n  the section called \\(lqPRUNING\\(rq\n  section of\n\nSo if we wanted to override that, we'd do it at the docbook layer. If\nyou use <<PRUNING,PRUNING>> instead, then the xml looks like:\n\n  and the <link linkend=\"PRUNING\">PRUNING</link> section of\n\nwhich takes the decision away from docbook and uses the text we provide.\n\nI don't think your commit message needs to go into that detail, but I\nthought it worth documenting in case we revisit this later.\n\n-Peff\n"},{"id":"553256","messageId":"pull.2416.v2.git.git.1790297546771.gitgitgadget@gmail.com","threadId":"66371","inReplyTo":"pull.2416.git.git.1790105342890.gitgitgadget@gmail.com","subject":"[PATCH v2] doc: add more AsciiDoc cross-references","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-09-25T00:52:26Z","receivedAt":"2026-09-25T00:52:34Z","isPatch":true,"body":"From: Julia Evans <julia@jvns.ca>\n\nInstead of saying \"see EXAMPLES below\", say \"see <<EXAMPLES,EXAMPLES>>\nbelow\" to make the man pages easier to navigate on the web.\n\nThe reason for using the more verbose <<EXAMPLES,EXAMPLES>>\n(instead of <<EXAMPLES>>) is that in some cases, <<EXAMPLES>> is\nrendered as `the section called \"EXAMPLES\"` or `[EXAMPLES]`.\n<<EXAMPLES,EXAMPLES>> is rendered as `EXAMPLES`, which gives us more\ncontrol over the output.\n\nThis also changes some of the HTML IDs of the headings from `_examples`\nto `EXAMPLES`, which has the potential to break some links.\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n    doc: add more AsciiDoc cross-references\n    \n    This version rewrites the commit message to be more accurate. The\n    original message said that the problem was to do with included pages\n    which wasn't true.\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2416%2Fjvns%2Fanchors-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2416/jvns/anchors-v2\nPull-Request: https://github.com/git/git/pull/2416\n\nRange-diff vs v1:\n\n 1:  419aa1259f ! 1:  8f4e7bae85 doc: add more AsciiDoc cross-references\n     @@ Commit message\n          below\" to make the man pages easier to navigate on the web.\n      \n          The reason for using the more verbose <<EXAMPLES,EXAMPLES>>\n     -    (instead of <<EXAMPLES>>) is that if the header that `<<EXAMPLES>>`\n     -    is referring to is in an included page (for example `REMOTES` in the\n     -    `git-push` man page), then AsciiDoc will think it's a broken link even\n     -    though it isn't. So it's easier to just make all of the links use the\n     -    form with two parts.\n     +    (instead of <<EXAMPLES>>) is that in some cases, <<EXAMPLES>> is\n     +    rendered as `the section called \"EXAMPLES\"` or `[EXAMPLES]`.\n     +    <<EXAMPLES,EXAMPLES>> is rendered as `EXAMPLES`, which gives us more\n     +    control over the output.\n     +\n     +    This also changes some of the HTML IDs of the headings from `_examples`\n     +    to `EXAMPLES`, which has the potential to break some links.\n      \n          Signed-off-by: Julia Evans <julia@jvns.ca>\n      \n\n\n Documentation/fetch-options.adoc              |  4 +-\n Documentation/git-add.adoc                    |  3 +-\n Documentation/git-bundle.adoc                 |  7 +-\n Documentation/git-cat-file.adoc               | 12 ++--\n Documentation/git-checkout.adoc               | 11 +--\n Documentation/git-credential-cache.adoc       |  3 +-\n Documentation/git-credential-store.adoc       |  3 +-\n Documentation/git-fast-export.adoc            |  5 +-\n Documentation/git-fast-import.adoc            |  7 +-\n Documentation/git-fetch.adoc                  |  1 +\n Documentation/git-filter-branch.adoc          |  3 +-\n Documentation/git-for-each-ref.adoc           |  4 +-\n Documentation/git-format-patch.adoc           |  4 +-\n Documentation/git-gc.adoc                     | 12 ++--\n Documentation/git-grep.adoc                   |  9 ++-\n Documentation/git-http-backend.adoc           |  6 +-\n Documentation/git-ls-files.adoc               |  8 ++-\n Documentation/git-ls-tree.adoc                |  3 +-\n Documentation/git-maintenance.adoc            |  3 +-\n Documentation/git-merge-tree.adoc             |  2 +-\n Documentation/git-notes.adoc                  | 14 ++--\n Documentation/git-p4.adoc                     | 12 ++--\n Documentation/git-pack-objects.adoc           |  5 +-\n Documentation/git-prune.adoc                  |  3 +-\n Documentation/git-push.adoc                   | 10 +--\n Documentation/git-rebase.adoc                 | 69 +++++++++++--------\n Documentation/git-replay.adoc                 |  4 +-\n Documentation/git-repo.adoc                   |  5 +-\n Documentation/git-rev-parse.adoc              |  7 +-\n Documentation/git-send-email.adoc             |  5 +-\n Documentation/git-stash.adoc                  |  3 +-\n Documentation/git-svn.adoc                    | 10 +--\n Documentation/git-worktree.adoc               |  5 +-\n Documentation/gitremote-helpers.adoc          | 15 ++--\n Documentation/gitsubmodules.adoc              |  9 ++-\n Documentation/gitworkflows.adoc               |  6 +-\n .../howto/revert-a-faulty-merge.adoc          |  5 +-\n Documentation/revisions.adoc                  |  4 +-\n 38 files changed, 190 insertions(+), 111 deletions(-)\n\ndiff --git a/Documentation/fetch-options.adoc b/Documentation/fetch-options.adoc\nindex 035f780e58..47dea1de8e 100644\n--- a/Documentation/fetch-options.adoc\n+++ b/Documentation/fetch-options.adoc\n@@ -199,7 +199,7 @@ endif::git-pull[]\n \tproviding the tag refspec.\n ifndef::git-pull[]\n +\n-See the PRUNING section below for more details.\n+See the <<PRUNING,PRUNING>> section below for more details.\n \n `-P`::\n `--prune-tags`::\n@@ -210,7 +210,7 @@ See the PRUNING section below for more details.\n \ta shorthand for providing the explicit tag refspec along with\n \t`--prune`, see the discussion about that in its documentation.\n +\n-See the PRUNING section below for more details.\n+See the <<PRUNING,PRUNING>> section below for more details.\n \n endif::git-pull[]\n \ndiff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc\nindex 16b06e38e1..906db7ccf3 100644\n--- a/Documentation/git-add.adoc\n+++ b/Documentation/git-add.adoc\n@@ -117,7 +117,7 @@ The intent of this option is to pick and choose lines of the patch to\n apply, or even to modify the contents of lines to be staged. This can be\n quicker and more flexible than using the interactive hunk selector.\n However, it is easy to confuse oneself and create a patch that does not\n-apply to the index. See EDITING PATCHES below.\n+apply to the index. See <<EDITING_PATCHES,EDITING PATCHES>> below.\n \n `-u`::\n `--update`::\n@@ -375,6 +375,7 @@ diff::\n   `HEAD` and index).\n \n \n+[[EDITING_PATCHES]]\n EDITING PATCHES\n ---------------\n \ndiff --git a/Documentation/git-bundle.adoc b/Documentation/git-bundle.adoc\nindex 03cd36fe8d..cd722bd674 100644\n--- a/Documentation/git-bundle.adoc\n+++ b/Documentation/git-bundle.adoc\n@@ -43,7 +43,7 @@ header indicating what references are contained within the bundle.\n \n Like the packed archive format itself bundles can either be\n self-contained, or be created using exclusions.\n-See the \"OBJECT PREREQUISITES\" section below.\n+See the <<OBJECT_PREREQUISITES,\"OBJECT PREREQUISITES\">> section below.\n \n Bundles created using revision exclusions are \"thin packs\" created\n using the `--thin` option to linkgit:git-pack-objects[1], and\n@@ -94,7 +94,8 @@ unbundle <file>::\n \n <git-rev-list-args>::\n \tA list of arguments, acceptable to 'git rev-parse' and\n-\t'git rev-list' (and containing a named ref, see SPECIFYING REFERENCES\n+\t'git rev-list' (and containing a named ref, see\n+\t<<SPECIFYING_REFERENCES,SPECIFYING REFERENCES>>\n \tbelow), that specifies the specific objects and references\n \tto transport.  For example, `master~10..master` causes the\n \tcurrent master reference to be packaged along with all objects\n@@ -127,6 +128,7 @@ unbundle <file>::\n \tThis flag makes the command not to report its progress\n \ton the standard error stream.\n \n+[[SPECIFYING_REFERENCES]]\n SPECIFYING REFERENCES\n ---------------------\n \n@@ -169,6 +171,7 @@ $ git bundle create master-yesterday.bundle master~10..master~5\n fatal: Refusing to create empty bundle.\n ----------------\n \n+[[OBJECT_PREREQUISITES]]\n OBJECT PREREQUISITES\n --------------------\n \ndiff --git a/Documentation/git-cat-file.adoc b/Documentation/git-cat-file.adoc\nindex 514bfc0032..c4ea2524cf 100644\n--- a/Documentation/git-cat-file.adoc\n+++ b/Documentation/git-cat-file.adoc\n@@ -115,7 +115,7 @@ are not of the requested type.\n --\n \t* When used with `--textconv` or `--filters`, the input lines\n \t  must specify the path, separated by whitespace. See the section\n-\t  `BATCH OUTPUT` below for details.\n+\t  <<BATCH_OUTPUT,`BATCH OUTPUT`>> below for details.\n \n \t* When used with `--use-mailmap`, for commit and tag objects, the\n \t  contents part of the output shows the identities replaced using the\n@@ -133,7 +133,7 @@ are not of the requested type.\n --\n \t* When used with `--textconv` or `--filters`, the input lines must\n \t specify the path, separated by whitespace. See the section\n-\t `BATCH OUTPUT` below for details.\n+\t <<BATCH_OUTPUT,`BATCH OUTPUT`>> below for details.\n \n \t* When used with `--use-mailmap`, for commit and tag objects, the\n \t  printed object information shows the size of the object as if the\n@@ -149,7 +149,7 @@ are not of the requested type.\n --\n \t* When used with `--textconv` or `--filters`, the input lines must\n \t  specify the path, separated by whitespace. See the section\n-\t  `BATCH OUTPUT` below for details.\n+\t  <<BATCH_OUTPUT,`BATCH OUTPUT`>> below for details.\n \n \t* When used with `--use-mailmap`, for commit and tag objects, the\n \t  `contents` command shows the identities replaced using the\n@@ -295,6 +295,7 @@ If `-p` is specified, the contents of `<object>` are pretty-printed.\n If `<type>` is specified, the raw (though uncompressed) contents of the `<object>`\n will be returned.\n \n+[[BATCH_OUTPUT]]\n BATCH OUTPUT\n ------------\n \n@@ -333,12 +334,12 @@ newline. The available atoms are:\n \n `objectsize:disk`::\n \tThe size, in bytes, that the object takes up on disk. See the\n-\tnote about on-disk sizes in the `CAVEATS` section below.\n+\tnote about on-disk sizes in the <<CAVEATS,`CAVEATS`>> section below.\n \n `deltabase`::\n \tIf the object is stored as a delta on-disk, this expands to the\n \tfull hex representation of the delta base object name.\n-\tOtherwise, expands to the null OID (all zeroes). See `CAVEATS`\n+\tOtherwise, expands to the null OID (all zeroes). See <<CAVEATS,`CAVEATS`>>\n \tbelow.\n \n `rest`::\n@@ -447,6 +448,7 @@ are replaced with NUL terminators. This ensures that output will be parsable if\n the output itself would contain a linefeed and is thus recommended for\n scripting purposes.\n \n+[[CAVEATS]]\n CAVEATS\n -------\n \ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex a8b3b8c2e2..2aefea0228 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -27,7 +27,8 @@ DESCRIPTION\n 2. **Restore a different version of a file**, for example with\n    `git checkout <commit> <filename>` or `git checkout <filename>`\n \n-See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.\n+See <<ARGUMENT_DISAMBIGUATION,ARGUMENT DISAMBIGUATION>> below\n+for how Git decides which one to do.\n \n `git checkout [<branch>]`::\n \tSwitch to _<branch>_. This sets the current branch to _<branch>_ and\n@@ -68,7 +69,7 @@ uncommitted changes.\n \n \tThe same as `git checkout <branch>`, except that instead of pointing\n \t`HEAD` at the branch, it points `HEAD` at the commit ID.\n-\tSee the \"DETACHED HEAD\" section below for more.\n+\tSee the <<DETACHED_HEAD,\"DETACHED HEAD\">> section below for more.\n +\n Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.\n \n@@ -210,8 +211,8 @@ variable.\n \tRather than checking out a branch to work on it, check out a\n \tcommit for inspection and discardable experiments.\n \tThis is the default behavior of `git checkout <commit>` when\n-\t_<commit>_ is not a branch name.  See the \"DETACHED HEAD\" section\n-\tbelow for details.\n+\t_<commit>_ is not a branch name.  See the\n+\t<<DETACHED_HEAD,\"DETACHED HEAD\">> section below for details.\n \n `--orphan <new-branch>`::\n \tCreate a new unborn branch, named _<new-branch>_, started from\n@@ -372,6 +373,7 @@ leave out at most one of _<rev-a>_ and _<rev-b>_, in which case it defaults to `\n +\n For more details, see the 'pathspec' entry in linkgit:gitglossary[7].\n \n+[[DETACHED_HEAD]]\n DETACHED HEAD\n -------------\n `HEAD` normally refers to a named branch (e.g. `master`). Meanwhile, each\n@@ -504,6 +506,7 @@ $ git reflog -2 HEAD # or\n $ git log -g -2 HEAD\n ------------\n \n+[[ARGUMENT_DISAMBIGUATION]]\n ARGUMENT DISAMBIGUATION\n -----------------------\n \ndiff --git a/Documentation/git-credential-cache.adoc b/Documentation/git-credential-cache.adoc\nindex 54fa7a27e1..2f6395937d 100644\n--- a/Documentation/git-credential-cache.adoc\n+++ b/Documentation/git-credential-cache.adoc\n@@ -24,7 +24,7 @@ user by filesystem permissions.\n \n You probably don't want to invoke this command directly; it is meant to\n be used as a credential helper by other parts of Git. See\n-linkgit:gitcredentials[7] or `EXAMPLES` below.\n+linkgit:gitcredentials[7] or <<EXAMPLES,`EXAMPLES`>> below.\n \n OPTIONS\n -------\n@@ -54,6 +54,7 @@ credentials before their timeout, you can issue an `exit` action:\n git credential-cache exit\n --------------------------------------\n \n+[[EXAMPLES]]\n EXAMPLES\n --------\n \ndiff --git a/Documentation/git-credential-store.adoc b/Documentation/git-credential-store.adoc\nindex 71864a8726..3f8a426f93 100644\n--- a/Documentation/git-credential-store.adoc\n+++ b/Documentation/git-credential-store.adoc\n@@ -24,7 +24,7 @@ Git programs.\n \n You probably don't want to invoke this command directly; it is meant to\n be used as a credential helper by other parts of git. See\n-linkgit:gitcredentials[7] or `EXAMPLES` below.\n+linkgit:gitcredentials[7] or <<EXAMPLES,`EXAMPLES`>> below.\n \n OPTIONS\n -------\n@@ -67,6 +67,7 @@ written to.\n \n When erasing credentials, matching credentials will be erased from all files.\n \n+[[EXAMPLES]]\n EXAMPLES\n --------\n \ndiff --git a/Documentation/git-fast-export.adoc b/Documentation/git-fast-export.adoc\nindex 719aeca244..0c2ce385c4 100644\n--- a/Documentation/git-fast-export.adoc\n+++ b/Documentation/git-fast-export.adoc\n@@ -148,12 +148,12 @@ by keeping the marks the same across runs.\n --anonymize::\n \tAnonymize the contents of the repository while still retaining\n \tthe shape of the history and stored tree.  See the section on\n-\t`ANONYMIZING` below.\n+\t<<ANONYMIZING,`ANONYMIZING`>> below.\n \n --anonymize-map=<from>[:<to>]::\n \tConvert token `<from>` to `<to>` in the anonymized output. If\n \t`<to>` is omitted, map `<from>` to itself (i.e., do not\n-\tanonymize it). See the section on `ANONYMIZING` below.\n+\tanonymize it). See the section on <<ANONYMIZING,`ANONYMIZING`>> below.\n \n --reference-excluded-parents::\n \tBy default, running a command such as `git fast-export\n@@ -219,6 +219,7 @@ referenced by that revision range contains the string\n 'refs/heads/master'.\n \n \n+[[ANONYMIZING]]\n ANONYMIZING\n -----------\n \ndiff --git a/Documentation/git-fast-import.adoc b/Documentation/git-fast-import.adoc\nindex fd165e11d2..c5e1cec1a5 100644\n--- a/Documentation/git-fast-import.adoc\n+++ b/Documentation/git-fast-import.adoc\n@@ -31,6 +31,7 @@ imports are supported from a particular foreign source depends on\n the frontend program in use.\n \n \n+[[OPTIONS]]\n OPTIONS\n -------\n \n@@ -456,7 +457,7 @@ and control the current import process.  More detailed discussion\n \tsupports the specified feature, and aborts if it does not.\n \n `option`::\n-\tSpecify any of the options listed under OPTIONS that do not\n+\tSpecify any of the options listed under <<OPTIONS,OPTIONS>> that do not\n \tchange stream semantic to suit the frontend's needs. This\n \tcommand is optional and is not needed to perform an import.\n \n@@ -1242,7 +1243,7 @@ no-relative-marks::\n force::\n \tAct as though the corresponding command-line option with\n \ta leading `--` was passed on the command line\n-\t(see OPTIONS, above).\n+\t(see <<OPTIONS,OPTIONS>>, above).\n \n import-marks::\n import-marks-if-exists::\n@@ -1291,7 +1292,7 @@ options the user may specify to git fast-import itself.\n ....\n \n The `<option>` part of the command may contain any of the options\n-listed in the OPTIONS section that do not change import semantics,\n+listed in the <<OPTIONS,OPTIONS>> section that do not change import semantics,\n without the leading `--` and is treated in the same way.\n \n Option commands must be the first commands on the input (not counting\ndiff --git a/Documentation/git-fetch.adoc b/Documentation/git-fetch.adoc\nindex db03541915..61fed797af 100644\n--- a/Documentation/git-fetch.adoc\n+++ b/Documentation/git-fetch.adoc\n@@ -103,6 +103,7 @@ The latter use of the `remote.<repository>.fetch` values can be\n overridden by giving the `--refmap=<refspec>` parameter(s) on the\n command line.\n \n+[[PRUNING]]\n PRUNING\n -------\n \ndiff --git a/Documentation/git-filter-branch.adoc b/Documentation/git-filter-branch.adoc\nindex 5a4f853785..80a55b3706 100644\n--- a/Documentation/git-filter-branch.adoc\n+++ b/Documentation/git-filter-branch.adoc\n@@ -125,7 +125,7 @@ OPTIONS\n \tThis is the filter for rewriting the index.  It is similar to the\n \ttree filter but does not check out the tree, which makes it much\n \tfaster.  Frequently used with `git rm --cached\n-\t--ignore-unmatch ...`, see EXAMPLES below.  For hairy\n+\t--ignore-unmatch ...`, see <<EXAMPLES,EXAMPLES>> below.  For hairy\n \tcases, see linkgit:git-update-index[1].\n \n --parent-filter <command>::\n@@ -243,6 +243,7 @@ rewrite, the exit status is `2`.  On any other error, the exit status may be\n any other non-zero value.\n \n \n+[[EXAMPLES]]\n EXAMPLES\n --------\n \ndiff --git a/Documentation/git-for-each-ref.adoc b/Documentation/git-for-each-ref.adoc\nindex c02cb7f886..a7b31e8aaf 100644\n--- a/Documentation/git-for-each-ref.adoc\n+++ b/Documentation/git-for-each-ref.adoc\n@@ -64,7 +64,8 @@ For all objects, the following names can be used:\n `objectsize`::\n \tThe size of the object (the same as 'git cat-file -s' reports).\n \tAppend `:disk` to get the size, in bytes, that the object takes up on\n-\tdisk. See the note about on-disk sizes in the 'CAVEATS' section below.\n+\tdisk. See the note about on-disk sizes in the\n+\t<<CAVEATS,'CAVEATS'>> section below.\n `objectname`::\n \tThe object name (aka SHA-1).\n \tFor a non-ambiguous abbreviation of the object name append `:short`.\n@@ -448,6 +449,7 @@ This prints the authorname, if present.\n git for-each-ref --format=\"%(refname)%(if)%(authorname)%(then) Authored by: %(authorname)%(end)\"\n ------------\n \n+[[CAVEATS]]\n CAVEATS\n -------\n \ndiff --git a/Documentation/git-format-patch.adoc b/Documentation/git-format-patch.adoc\nindex 191f64b77d..a78fe564f0 100644\n--- a/Documentation/git-format-patch.adoc\n+++ b/Documentation/git-format-patch.adoc\n@@ -430,7 +430,8 @@ you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`.\n `--no-base`::\n `--base[=<commit>]`::\n \tRecord the base tree information to identify the state the\n-\tpatch series applies to.  See the BASE TREE INFORMATION section\n+\tpatch series applies to.  See the\n+\t<<BASE_TREE_INFORMATION,BASE TREE INFORMATION>> section\n \tbelow for details. If _<commit>_ is `auto`, a base commit is\n \tautomatically chosen. The `--no-base` option overrides a\n \t`format.useAutoBase` configuration.\n@@ -702,6 +703,7 @@ This should help you to submit patches inline using KMail.\n 5. Back in the compose window: add whatever other text you wish to the\n    message, complete the addressing and subject fields, and press send.\n \n+[[BASE_TREE_INFORMATION]]\n BASE TREE INFORMATION\n ---------------------\n \ndiff --git a/Documentation/git-gc.adoc b/Documentation/git-gc.adoc\nindex 6fed646dd8..5788a43215 100644\n--- a/Documentation/git-gc.adoc\n+++ b/Documentation/git-gc.adoc\n@@ -39,14 +39,15 @@ OPTIONS\n \tspace utilization and performance.  This option will cause\n \t'git gc' to more aggressively optimize the repository at the expense\n \tof taking much more time.  The effects of this optimization are\n-\tmostly persistent. See the \"AGGRESSIVE\" section below for details.\n+\tmostly persistent. See the <<AGGRESSIVE,\"AGGRESSIVE\">>\n+\tsection below for details.\n \n --auto::\n \tWith this option, 'git gc' checks whether any housekeeping is\n \trequired; if not, it exits without performing any work.\n +\n-See the `gc.auto` option in the \"CONFIGURATION\" section below for how\n-this heuristic works.\n+See the `gc.auto` option in the <<CONFIGURATION,\"CONFIGURATION\">>\n+section below for how this heuristic works.\n +\n Once housekeeping is triggered by exceeding the limits of\n configuration options such as `gc.auto` and `gc.autoPackLimit`, all\n@@ -83,7 +84,7 @@ be performed as well.\n \toverridable by the config variable `gc.pruneExpire`).\n \t--prune=now prunes loose objects regardless of their age and\n \tincreases the risk of corruption if another process is writing to\n-\tthe repository concurrently; see \"NOTES\" below. --prune is on by\n+\tthe repository concurrently; see <<NOTES,\"NOTES\">> below. --prune is on by\n \tdefault.\n \n --no-prune::\n@@ -102,6 +103,7 @@ be performed as well.\n \ta single pack. When this option is used, `gc.bigPackThreshold`\n \tis ignored.\n \n+[[AGGRESSIVE]]\n AGGRESSIVE\n ----------\n \n@@ -128,6 +130,7 @@ more time, and the resulting space/delta optimization may or may not\n be worth it. Not using this at all is the right trade-off for most\n users and their repositories.\n \n+[[CONFIGURATION]]\n CONFIGURATION\n -------------\n \n@@ -135,6 +138,7 @@ include::includes/cmd-config-section-all.adoc[]\n \n include::config/gc.adoc[]\n \n+[[NOTES]]\n NOTES\n -----\n \ndiff --git a/Documentation/git-grep.adoc b/Documentation/git-grep.adoc\nindex 19b3ade16d..dd4a7cc9e9 100644\n--- a/Documentation/git-grep.adoc\n+++ b/Documentation/git-grep.adoc\n@@ -58,7 +58,7 @@ OPTIONS\n \tin linkgit:gitglossary[7] for more information.\n +\n This option cannot be used together with `--cached` or `--untracked`.\n-See also `grep.fallbackToNoIndex` in 'CONFIGURATION' below.\n+See also `grep.fallbackToNoIndex` in <<CONFIGURATION,'CONFIGURATION'>> below.\n \n `--no-exclude-standard`::\n \tAlso search in ignored files by not honoring the `.gitignore`\n@@ -256,8 +256,9 @@ providing this option will cause it to die.\n \ta non-zero status.\n \n `--threads <num>`::\n-\tNumber of `grep` worker threads to use.  See `NOTES ON THREADS`\n-\tand `grep.threads` in 'CONFIGURATION' for more information.\n+\tNumber of `grep` worker threads to use. See\n+\t<<NOTES_ON_THREADS,`NOTES ON THREADS`>> and `grep.threads` in\n+\t<<CONFIGURATION,'CONFIGURATION'>> for more information.\n \n `-f <file>`::\n \tRead patterns from _<file>_, one per line.\n@@ -337,6 +338,7 @@ EXAMPLES\n `git grep solution -- :^Documentation`::\n \tLooks for `solution`, excluding files in `Documentation`.\n \n+[[NOTES_ON_THREADS]]\n NOTES ON THREADS\n ----------------\n \n@@ -348,6 +350,7 @@ with multiple threads might perform slower than single-threaded if `--textconv`\n is given and there are too many text conversions.  Thus, if low performance is\n experienced in this case, it might be desirable to use `--threads=1`.\n \n+[[CONFIGURATION]]\n CONFIGURATION\n -------------\n \ndiff --git a/Documentation/git-http-backend.adoc b/Documentation/git-http-backend.adoc\nindex 1dea426852..5fabc85d12 100644\n--- a/Documentation/git-http-backend.adoc\n+++ b/Documentation/git-http-backend.adoc\n@@ -18,7 +18,7 @@ The program supports clients fetching using both the smart HTTP protocol\n and the backwards-compatible dumb HTTP protocol, as well as clients\n pushing using the smart HTTP protocol. It also supports Git's\n more-efficient \"v2\" protocol if properly configured; see the\n-discussion of `GIT_PROTOCOL` in the ENVIRONMENT section below.\n+discussion of `GIT_PROTOCOL` in the <<ENVIRONMENT,ENVIRONMENT>> section below.\n \n It verifies that the directory has the magic file\n \"git-daemon-export-ok\", and it will refuse to export any Git directory\n@@ -69,6 +69,7 @@ manually in the web server configuration.  If GIT_PROJECT_ROOT is not\n set, 'git http-backend' reads PATH_TRANSLATED, which is also set\n automatically by the web server.\n \n+[[EXAMPLES]]\n EXAMPLES\n --------\n All of the following examples map `http://$hostname/git/foo/bar.git`\n@@ -257,6 +258,7 @@ $HTTP[\"url\"] =~ \"^/git/private\" {\n ----------------------------------------------------------------\n \n \n+[[ENVIRONMENT]]\n ENVIRONMENT\n -----------\n 'git http-backend' relies upon the `CGI` environment variables set\n@@ -290,7 +292,7 @@ via the `HTTP_GIT_PROTOCOL` variable, and `git-http-backend` will\n automatically copy that to `GIT_PROTOCOL`. However, some webservers may\n be more selective about which headers they'll pass, in which case they\n need to be configured explicitly (see the mention of `Git-Protocol` in\n-the Apache config from the earlier EXAMPLES section).\n+the Apache config from the earlier <<EXAMPLES,EXAMPLES>> section).\n \n The backend process sets GIT_COMMITTER_NAME to '$REMOTE_USER' and\n GIT_COMMITTER_EMAIL to '$\\{REMOTE_USER}@http.$\\{REMOTE_ADDR\\}',\ndiff --git a/Documentation/git-ls-files.adoc b/Documentation/git-ls-files.adoc\nindex 2b175388e1..14ebad8b71 100644\n--- a/Documentation/git-ls-files.adoc\n+++ b/Documentation/git-ls-files.adoc\n@@ -98,7 +98,7 @@ OPTIONS\n \n -z::\n \t\\0 line termination on output and do not quote filenames.\n-\tSee OUTPUT below for more information.\n+\tSee <<OUTPUT,OUTPUT>> below for more information.\n \n --deduplicate::\n \tWhen only filenames are shown, suppress duplicates that may\n@@ -110,8 +110,8 @@ OPTIONS\n -x <pattern>::\n --exclude=<pattern>::\n \tSkip untracked files matching pattern.\n-\tNote that pattern is a shell wildcard pattern. See EXCLUDE PATTERNS\n-\tbelow for more information.\n+\tNote that pattern is a shell wildcard pattern.\n+\tSee <<EXCLUDE_PATTERNS,EXCLUDE PATTERNS>> below for more information.\n \n -X <file>::\n --exclude-from=<file>::\n@@ -231,6 +231,7 @@ followed by the  (\"attr/<eolattr>\").\n \tFiles to show. If no files are given all files which match the other\n \tspecified criteria are shown.\n \n+[[OUTPUT]]\n OUTPUT\n ------\n 'git ls-files' just outputs the filenames unless `--stage` is specified in\n@@ -292,6 +293,7 @@ eolattr::\n path::\n \tThe pathname of the file which is recorded in the index.\n \n+[[EXCLUDE_PATTERNS]]\n EXCLUDE PATTERNS\n ----------------\n \ndiff --git a/Documentation/git-ls-tree.adoc b/Documentation/git-ls-tree.adoc\nindex 6572095d8d..29bde9366d 100644\n--- a/Documentation/git-ls-tree.adoc\n+++ b/Documentation/git-ls-tree.adoc\n@@ -54,7 +54,7 @@ OPTIONS\n \n -z::\n \t\\0 line termination on output and do not quote filenames.\n-\tSee OUTPUT FORMAT below for more information.\n+\tSee <<OUTPUT_FORMAT,OUTPUT FORMAT>> below for more information.\n \n --name-only::\n --name-status::\n@@ -99,6 +99,7 @@ OPTIONS\n \timplicitly uses the root level of the tree as the sole path argument.\n \n \n+[[OUTPUT_FORMAT]]\n Output Format\n -------------\n \ndiff --git a/Documentation/git-maintenance.adoc b/Documentation/git-maintenance.adoc\nindex bda616f14c..85f208031c 100644\n--- a/Documentation/git-maintenance.adoc\n+++ b/Documentation/git-maintenance.adoc\n@@ -95,6 +95,7 @@ in that order. Otherwise, the tasks are determined by which\n `maintenance.<task>.enabled` config options are true. By default, only\n `maintenance.gc.enabled` is true.\n \n+[[TASKS]]\n TASKS\n -----\n \n@@ -215,7 +216,7 @@ OPTIONS\n \tspecified tasks in the specified order. If no `--task=<task>`\n \targuments are specified, then only the tasks with\n \t`maintenance.<task>.enabled` configured as `true` are considered.\n-\tSee the 'TASKS' section for the list of accepted `<task>` values.\n+\tSee the <<TASKS,'TASKS'>> section for the list of accepted `<task>` values.\n \n --scheduler=auto|crontab|systemd-timer|launchctl|schtasks::\n \tWhen combined with the `start` subcommand, specify the scheduler\ndiff --git a/Documentation/git-merge-tree.adoc b/Documentation/git-merge-tree.adoc\nindex 4391bbee47..c5351f9699 100644\n--- a/Documentation/git-merge-tree.adoc\n+++ b/Documentation/git-merge-tree.adoc\n@@ -35,7 +35,7 @@ linkgit:git-merge[1], including:\n   * etc.\n \n After the merge completes, a new toplevel tree object is created.  See\n-`OUTPUT` below for details.\n+<<OUTPUT,`OUTPUT`>> below for details.\n \n OPTIONS\n -------\ndiff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc\nindex 46a232ca71..22d59ada86 100644\n--- a/Documentation/git-notes.adoc\n+++ b/Documentation/git-notes.adoc\n@@ -28,8 +28,9 @@ Adds, removes, or reads notes attached to objects, without touching\n the objects themselves.\n \n By default, notes are saved to and read from `refs/notes/commits`, but\n-this default can be overridden.  See the OPTIONS, CONFIGURATION, and\n-ENVIRONMENT sections below.  If this ref does not exist, it will be\n+this default can be overridden.  See the <<OPTIONS,OPTIONS>>,\n+<<CONFIGURATION,CONFIGURATION>>, and <<ENVIRONMENT,ENVIRONMENT>>\n+sections below. If this ref does not exist, it will be\n quietly created when it is first needed to store a note.\n \n A typical use of notes is to supplement a commit message without\n@@ -114,7 +115,8 @@ line.\n \tany) into the current notes ref (called \"local\").\n +\n If conflicts arise and a strategy for automatically resolving\n-conflicting notes (see the \"NOTES MERGE STRATEGIES\" section) is not given,\n+conflicting notes (see the\n+<<NOTES_MERGE_STRATEGIES,\"NOTES MERGE STRATEGIES\">> section) is not given,\n the `manual` resolver is used. This resolver checks out the\n conflicting notes in a special worktree (`.git/NOTES_MERGE_WORKTREE`),\n and instructs the user to manually resolve the conflicts there.\n@@ -139,6 +141,7 @@ the command line.\n \tPrint the current notes ref. This provides an easy way to\n \tretrieve the current notes ref (e.g. from scripts).\n \n+[[OPTIONS]]\n OPTIONS\n -------\n `-f`::\n@@ -225,7 +228,8 @@ future.\n \tstrategy. The following strategies are recognized: `manual`\n \t(default), `ours`, `theirs`, `union` and `cat_sort_uniq`.\n \tThis option overrides the `notes.mergeStrategy` configuration setting.\n-\tSee the \"NOTES MERGE STRATEGIES\" section below for more\n+\tSee the <<NOTES_MERGE_STRATEGIES,\"NOTES MERGE STRATEGIES\">>\n+\tsection below for more\n \tinformation on each notes merge strategy.\n \n `--commit`::\n@@ -278,6 +282,7 @@ object, in which case the history of the notes can be read with\n `git log -p -g <refname>`.\n \n \n+[[NOTES_MERGE_STRATEGIES]]\n NOTES MERGE STRATEGIES\n ----------------------\n \n@@ -361,6 +366,7 @@ include::includes/cmd-config-section-rest.adoc[]\n include::config/notes.adoc[]\n \n \n+[[ENVIRONMENT]]\n ENVIRONMENT\n -----------\n \ndiff --git a/Documentation/git-p4.adoc b/Documentation/git-p4.adoc\nindex 59edd24134..acf14cd03d 100644\n--- a/Documentation/git-p4.adoc\n+++ b/Documentation/git-p4.adoc\n@@ -119,7 +119,8 @@ importing directly from p4 is considerably slower than pulling changes\n from a Git remote, this can be useful in a multi-developer environment.\n \n If there are multiple branches, doing 'git p4 sync' will automatically\n-use the \"BRANCH DETECTION\" algorithm to try to partition new changes\n+use the <<BRANCH_DETECTION,\"BRANCH DETECTION\">> algorithm\n+to try to partition new changes\n into the right branch.  This can be overridden with the `--branch`\n option to specify just a single branch to update.\n \n@@ -245,7 +246,7 @@ Git repository:\n \n --detect-branches::\n \tUse the branch detection algorithm to find new paths in p4.  It is\n-\tdocumented below in \"BRANCH DETECTION\".\n+\tdocumented below in <<BRANCH_DETECTION,\"BRANCH DETECTION\">>.\n \n --changesfile <file>::\n \tImport exactly the p4 change numbers listed in 'file', one per\n@@ -297,7 +298,7 @@ Git repository:\n \n --use-client-spec::\n \tUse a client spec to find the list of interesting files in p4.\n-\tSee the \"CLIENT SPEC\" section below.\n+\tSee the <<CLIENT_SPEC,\"CLIENT SPEC\">> section below.\n \n -/ <path>::\n \tExclude selected depot paths when cloning or syncing.\n@@ -475,6 +476,7 @@ p4 revision specifier on the end:\n See 'p4 help revisions' for the full syntax of p4 revision specifiers.\n \n \n+[[CLIENT_SPEC]]\n CLIENT SPEC\n -----------\n The p4 client specification is maintained with the 'p4 client' command\n@@ -505,6 +507,7 @@ normal p4 mechanisms of determining the client are used:  environment\n variable `P4CLIENT`, a file referenced by `P4CONFIG`, or the local host name.\n \n \n+[[BRANCH_DETECTION]]\n BRANCH DETECTION\n ----------------\n P4 does not have the same concept of a branch as Git.  Instead,\n@@ -643,7 +646,8 @@ git-p4.labelImportRegexp::\n git-p4.useClientSpec::\n \tSpecify that the p4 client spec should be used to identify p4\n \tdepot paths of interest.  This is equivalent to specifying the\n-\toption `--use-client-spec`.  See the \"CLIENT SPEC\" section above.\n+\toption `--use-client-spec`.\n+\tSee the <<CLIENT_SPEC,\"CLIENT SPEC\">> section above.\n \tThis variable is a boolean, not the name of a p4 client.\n \n git-p4.pathEncoding::\ndiff --git a/Documentation/git-pack-objects.adoc b/Documentation/git-pack-objects.adoc\nindex 65cd00c152..ccad938c5b 100644\n--- a/Documentation/git-pack-objects.adoc\n+++ b/Documentation/git-pack-objects.adoc\n@@ -363,8 +363,8 @@ raise an error.\n \tKeep unreachable objects in loose form. This implies `--revs`.\n \n --delta-islands::\n-\tRestrict delta matches based on \"islands\". See DELTA ISLANDS\n-\tbelow.\n+\tRestrict delta matches based on \"islands\".\n+\tSee <<DELTA_ISLANDS,DELTA ISLANDS>> below.\n \n --name-hash-version=<n>::\n \tWhile performing delta compression, Git groups objects that may be\n@@ -411,6 +411,7 @@ request. The `--path-walk` option supports the `--filter=<spec>` forms\n `combine:<spec>+<spec>` form.\n \n \n+[[DELTA_ISLANDS]]\n DELTA ISLANDS\n -------------\n \ndiff --git a/Documentation/git-prune.adoc b/Documentation/git-prune.adoc\nindex 9a45571b90..d7836e625f 100644\n--- a/Documentation/git-prune.adoc\n+++ b/Documentation/git-prune.adoc\n@@ -15,7 +15,7 @@ DESCRIPTION\n -----------\n \n NOTE: In most cases, users should run 'git gc', which calls\n-'git prune'. See the section \"NOTES\", below.\n+'git prune'. See the section <<NOTES,\"NOTES\">>, below.\n \n This runs 'git fsck --unreachable' using all the refs\n available in `refs/`, optionally with an additional set of\n@@ -67,6 +67,7 @@ borrows from your repository via its\n $ git prune $(cd ../another && git rev-parse --all)\n ------------\n \n+[[NOTES]]\n NOTES\n -----\n \ndiff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc\nindex aa221c3909..e5b1023855 100644\n--- a/Documentation/git-push.adoc\n+++ b/Documentation/git-push.adoc\n@@ -132,7 +132,8 @@ as well as various other special refspec forms:\n     linkgit:git-config[1]) suggest what refs/ namespace you may have\n     wanted to push to.\n \n-Not all updates are allowed: see PUSH RULES below for the details.\n+Not all updates are allowed: see\n+<<PUSH_RULES,PUSH RULES>> below for the details.\n \n `--all`::\n `--branches`::\n@@ -337,9 +338,9 @@ allowing a forced update.\n \tUsually, `git push` will refuse to update a branch that is not an\n \tancestor of the commit being pushed.\n +\n-This flag disables that check, the other safety checks in PUSH RULES\n-below, and the checks in `--force-with-lease`. It can cause the remote\n-repository to lose commits; use it with care.\n+This flag disables that check, the other safety checks in\n+<<PUSH_RULES,PUSH RULES>> below, and the checks in `--force-with-lease`.\n+It can cause the remote repository to lose commits; use it with care.\n +\n Note that `--force` applies to all the refs that are pushed, hence\n using it with `push.default` set to `matching` or with multiple push\n@@ -568,6 +569,7 @@ reason::\n \trefs, no explanation is needed. For a failed ref, the reason for\n \tfailure is described.\n \n+[[PUSH_RULES]]\n PUSH RULES\n ----------\n \ndiff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc\nindex f6c22d1598..6536ebdc90 100644\n--- a/Documentation/git-rebase.adoc\n+++ b/Documentation/git-rebase.adoc\n@@ -17,8 +17,8 @@ SYNOPSIS\n DESCRIPTION\n -----------\n Transplant a series of commits onto a different starting point.\n-You can also use `git rebase` to reorder or combine commits: see INTERACTIVE\n-MODE below for how to do that.\n+You can also use `git rebase` to reorder or combine commits: see\n+<<INTERACTIVE_MODE,INTERACTIVE MODE>> below for how to do that.\n \n For example, imagine that you have been working on the `topic` branch in this\n history, and you want to \"catch up\" to the work done on the `master` branch.\n@@ -76,8 +76,8 @@ Here is a simplified description of what `git rebase <upstream>` does:\n 2. Check out `<upstream>` with the equivalent of\n    `git checkout --detach <upstream>`.\n 3. Replay the commits, one by one, in order. This is similar to running\n-   `git cherry-pick <commit>` for each commit. See REBASING MERGES for how merges\n-   are handled.\n+   `git cherry-pick <commit>` for each commit.\n+   See <<REBASING_MERGES,REBASING MERGES>> for how merges are handled.\n 4. Update your branch to point to the final commit with the equivalent\n    of `git checkout -B <branch>`.\n \n@@ -89,6 +89,7 @@ point to that commit at the end of the rebase if other commands that change\n tip, however, is accessible using the reflog of the current branch (i.e. `@{1}`,\n see linkgit:gitrevisions[7]).\n \n+[[TRANSPLANTING]]\n TRANSPLANTING A TOPIC BRANCH WITH --ONTO\n ----------------------------------------\n \n@@ -218,7 +219,8 @@ As a special case, you may use \"A\\...B\" as a shortcut for the\n merge base of A and B if there is exactly one merge base. You can\n leave out at most one of A and B, in which case it defaults to HEAD.\n \n-See TRANSPLANTING A TOPIC BRANCH WITH --ONTO above for examples.\n+See <<TRANSPLANTING,TRANSPLANTING A TOPIC BRANCH WITH --ONTO>>\n+above for examples.\n \n --keep-base::\n \tSet the starting point at which to create the new commits to the\n@@ -239,7 +241,7 @@ Although both this option and `--fork-point` find the merge base between\n point_ on which new commits will be created, whereas `--fork-point` uses\n the merge base to determine the _set of commits_ which will be rebased.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n <upstream>::\n \tUpstream branch to compare against.  May be any valid commit,\n@@ -254,7 +256,7 @@ See also INCOMPATIBLE OPTIONS below.\n \tinternally).  This option may become a no-op in the future\n \tonce the merge backend handles everything the apply one does.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n --empty=(drop|keep|stop)::\n \tHow to handle commits that are not empty to start and are not\n@@ -282,7 +284,7 @@ by `git log --cherry-mark ...`) are detected and dropped as a\n preliminary step (unless `--reapply-cherry-picks` or `--keep-base` is\n passed).\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n --no-keep-empty::\n --keep-empty::\n@@ -303,7 +305,7 @@ tools generate many empty commits and you want them all removed.\n For commits which do not start empty but become empty after rebasing,\n see the `--empty` flag.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n --reapply-cherry-picks::\n --no-reapply-cherry-picks::\n@@ -325,7 +327,7 @@ linkgit:git-config[1]).\n `--reapply-cherry-picks` allows rebase to forgo reading all upstream\n commits, potentially improving performance.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n --allow-empty-message::\n \tNo-op.  Rebasing commits with an empty message used to fail\n@@ -333,7 +335,7 @@ See also INCOMPATIBLE OPTIONS below.\n \twith empty messages to be rebased.  Now commits with an empty\n \tmessage do not cause rebasing to halt.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n -m::\n --merge::\n@@ -345,7 +347,7 @@ conflict happens, the side reported as 'ours' is the so-far rebased\n series, starting with `<upstream>`, and 'theirs' is the working branch.\n In other words, the sides are swapped.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n -s <strategy>::\n --strategy=<strategy>::\n@@ -357,7 +359,7 @@ on top of the `<upstream>` branch using the given strategy, using\n the `ours` strategy simply empties all patches from the `<branch>`,\n which makes little sense.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n -X <strategy-option>::\n --strategy-option=<strategy-option>::\n@@ -366,7 +368,7 @@ See also INCOMPATIBLE OPTIONS below.\n \tspecified, `-s ort`.  Note the reversal of 'ours' and\n \t'theirs' as noted above for the `-m` option.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n include::rerere-options.adoc[]\n \n@@ -408,7 +410,7 @@ include::rerere-options.adoc[]\n \tcontext exist they all must match.  By default no context is\n \tever ignored.  Implies `--apply`.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n --no-ff::\n --force-rebase::\n@@ -443,7 +445,7 @@ If your branch was based on `<upstream>` but `<upstream>` was rewound and\n your branch contains commits which were dropped, this option can be used\n with `--keep-base` in order to drop those commits from your branch.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n --ignore-whitespace::\n \tIgnore whitespace differences when trying to reconcile\n@@ -468,7 +470,7 @@ merge backend;;\n \t(see linkgit:git-apply[1]) that applies the patch.\n \tImplies `--apply`.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n --committer-date-is-author-date::\n \tInstead of using the current time as the committer date, use\n@@ -488,14 +490,14 @@ applying (in terms of the author date).\n \tthe current time as the\tauthor date of the rebased commit.  This\n \toption implies `--force-rebase`.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n --signoff::\n \tAdd a `Signed-off-by` trailer to all the rebased commits. Note\n \tthat if `--interactive` is given then only commits marked to be\n \tpicked, edited or reworded will have the trailer added.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n --trailer=<trailer>::\n \tAppend the given trailer to every rebased commit message, processed\n@@ -508,13 +510,13 @@ See also INCOMPATIBLE OPTIONS below.\n --interactive::\n \tMake a list of the commits which are about to be rebased.  Let the\n \tuser edit that list before rebasing.  This mode can also be used to\n-\tsplit commits (see SPLITTING COMMITS below).\n+\tsplit commits (see <<SPLITTING_COMMITS,SPLITTING COMMITS>> below).\n +\n The commit list format can be changed by setting the configuration option\n rebase.instructionFormat.  A customized instruction format will automatically\n have the commit hash prepended to the format.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n -r::\n --rebase-merges[=(rebase-cousins|no-rebase-cousins)]::\n@@ -542,7 +544,8 @@ It is currently only possible to recreate the merge commits using the\n `ort` merge strategy; different merge strategies can be used only via\n explicit `exec git merge -s <strategy> [...]` commands.\n +\n-See also REBASING MERGES and INCOMPATIBLE OPTIONS below.\n+See also <<REBASING_MERGES,REBASING MERGES>> and\n+<<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n -x <cmd>::\n --exec <cmd>::\n@@ -567,14 +570,14 @@ squash/fixup series.\n This uses the `--interactive` machinery internally, but it can be run\n without an explicit `--interactive`.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n --root::\n \tRebase all commits reachable from `<branch>`, instead of\n \tlimiting them with an `<upstream>`.  This allows you to rebase\n \tthe root commit(s) on a branch.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n --autosquash::\n --no-autosquash::\n@@ -600,7 +603,7 @@ Setting configuration variable `rebase.autoSquash` to true enables\n auto-squashing by default for interactive rebase.  The `--no-autosquash`\n option can be used to override that setting.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n --autostash::\n --no-autostash::\n@@ -617,8 +620,9 @@ See also INCOMPATIBLE OPTIONS below.\n +\n This option applies once a rebase is started. It is preserved for the whole\n rebase based on, in order, the command line option provided to the initial `git\n-rebase`, the `rebase.rescheduleFailedExec` configuration (see\n-linkgit:git-config[1] or \"CONFIGURATION\" below), or it defaults to false.\n+rebase`, the `rebase.rescheduleFailedExec` configuration\n+(see linkgit:git-config[1] or <<CONFIGURATION,\"CONFIGURATION\">> below),\n+or it defaults to false.\n +\n Recording this option for the whole rebase is a convenience feature. Otherwise\n an explicit `--no-reschedule-failed-exec` at the start would be overridden by\n@@ -635,8 +639,9 @@ rebase --continue` is invoked. Currently, you cannot pass\n If the configuration variable `rebase.updateRefs` is set, then this option\n can be used to override and disable this setting.\n +\n-See also INCOMPATIBLE OPTIONS below.\n+See also <<INCOMPATIBLE_OPTIONS,INCOMPATIBLE OPTIONS>> below.\n \n+[[INCOMPATIBLE_OPTIONS]]\n INCOMPATIBLE OPTIONS\n --------------------\n \n@@ -813,7 +818,8 @@ NOTES\n -----\n \n You should understand the implications of using `git rebase` on a\n-repository that you share.  See also RECOVERING FROM UPSTREAM REBASE\n+repository that you share.\n+See also <<RECOVERING_FROM_UPSTREAM_REBASE,RECOVERING FROM UPSTREAM REBASE>>\n below.\n \n When the rebase is run, it will first execute a `pre-rebase` hook if one\n@@ -823,6 +829,7 @@ for an example.\n \n Upon completion, `<branch>` will be the current branch.\n \n+[[INTERACTIVE_MODE]]\n INTERACTIVE MODE\n ----------------\n \n@@ -978,6 +985,7 @@ pick f4593f9 four\n exec make test\n --------------------\n \n+[[SPLITTING_COMMITS]]\n SPLITTING COMMITS\n -----------------\n \n@@ -1013,6 +1021,7 @@ consistent (they compile, pass the testsuite, etc.) you should use\n after each commit, test, and amend the commit if fixes are necessary.\n \n \n+[[RECOVERING_FROM_UPSTREAM_REBASE]]\n RECOVERING FROM UPSTREAM REBASE\n -------------------------------\n \n@@ -1138,6 +1147,7 @@ The ripple effect of a \"hard case\" recovery is especially bad:\n 'everyone' downstream from 'topic' will now have to perform a \"hard\n case\" recovery too!\n \n+[[REBASING_MERGES]]\n REBASING MERGES\n ---------------\n \n@@ -1276,6 +1286,7 @@ merge tlsv1.3\n merge cmake\n ------------\n \n+[[CONFIGURATION]]\n CONFIGURATION\n -------------\n \ndiff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\nindex 58b4c0c470..f3ac875bb7 100644\n--- a/Documentation/git-replay.adoc\n+++ b/Documentation/git-replay.adoc\n@@ -20,7 +20,7 @@ the working tree and the index untouched. By default, updates the\n relevant references using an atomic transaction (all refs update or\n none). Use `--ref-action=print` to avoid automatic ref updates and\n instead get update commands that can be piped to `git update-ref --stdin`\n-(see the <<output,OUTPUT>> section below).\n+(see the <<OUTPUT,OUTPUT>> section below).\n \n THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.\n \n@@ -118,7 +118,7 @@ behavior of git-rebase(1)'s `--no-rebase-merges` option.)\n :git-replay: 1\n include::rev-list-options.adoc[]\n \n-[[output]]\n+[[OUTPUT]]\n OUTPUT\n ------\n \ndiff --git a/Documentation/git-repo.adoc b/Documentation/git-repo.adoc\nindex ed7d80c690..cb8c1e7292 100644\n--- a/Documentation/git-repo.adoc\n+++ b/Documentation/git-repo.adoc\n@@ -22,8 +22,8 @@ COMMANDS\n --------\n `info [--format=(lines|nul) | -z] [--all | <key>...]`::\n \tRetrieve metadata-related information about the current repository. Only\n-\tthe requested data will be returned based on their keys (see \"INFO KEYS\"\n-\tsection below).\n+\tthe requested data will be returned based on their keys\n+\t(see <<INFO_KEYS,\"INFO KEYS\">> section below).\n +\n The values are returned in the same order in which their respective keys were\n requested. The `--all` flag requests the values for all the available keys.\n@@ -89,6 +89,7 @@ supported:\n +\n `-z` is an alias for `--format=nul`.\n \n+[[INFO_KEYS]]\n INFO KEYS\n ---------\n In order to obtain a set of values from `git repo info`, you should provide\ndiff --git a/Documentation/git-rev-parse.adoc b/Documentation/git-rev-parse.adoc\nindex 5398691f3f..a6d4289e28 100644\n--- a/Documentation/git-rev-parse.adoc\n+++ b/Documentation/git-rev-parse.adoc\n@@ -38,12 +38,13 @@ Operation Modes\n Each of these options must appear first on the command line.\n \n --parseopt::\n-\tUse 'git rev-parse' in option parsing mode (see PARSEOPT section below).\n+\tUse 'git rev-parse' in option parsing mode\n+\t(see <<PARSEOPT,PARSEOPT>> section below).\n \tThe command in this mode can be used outside a repository or\n \ta working tree controlled by a repository.\n \n --sq-quote::\n-\tUse 'git rev-parse' in shell quoting mode (see SQ-QUOTE\n+\tUse 'git rev-parse' in shell quoting mode (see <<SQ_QUOTE,SQ-QUOTE>>\n \tsection below). In contrast to the `--sq` option below, this\n \tmode only does quoting. Nothing else is done to command input.\n \tThe command in this mode can be used outside a repository or\n@@ -354,6 +355,7 @@ Other Options\n \n include::revisions.adoc[]\n \n+[[PARSEOPT]]\n PARSEOPT\n --------\n \n@@ -460,6 +462,7 @@ An option group Header\n     -C[...]               option C with an optional argument\n ------------\n \n+[[SQ_QUOTE]]\n SQ-QUOTE\n --------\n \ndiff --git a/Documentation/git-send-email.adoc b/Documentation/git-send-email.adoc\nindex 5c9ab39944..4a5e0c359f 100644\n--- a/Documentation/git-send-email.adoc\n+++ b/Documentation/git-send-email.adoc\n@@ -50,7 +50,7 @@ Composing\n \n `--annotate`::\n \tReview and edit each patch you're about to send. Default is the value\n-\tof `sendemail.annotate`. See the CONFIGURATION section for\n+\tof `sendemail.annotate`. See the <<CONFIGURATION,CONFIGURATION>> section for\n \t`sendemail.multiEdit`.\n \n `--bcc=<address>,...`::\n@@ -78,7 +78,7 @@ removed.\n +\n Missing `From` or `In-Reply-To` headers will be prompted for.\n +\n-See the CONFIGURATION section for `sendemail.multiEdit`.\n+See the <<CONFIGURATION,CONFIGURATION>> section for `sendemail.multiEdit`.\n \n `--from=<address>`::\n \tSpecify the sender of the emails.  If not specified on the command line,\n@@ -559,6 +559,7 @@ Information\n \taddress to standard output, one per line. See `sendemail.aliasFile`\n \tfor more information about aliases.\n \n+[[CONFIGURATION]]\n CONFIGURATION\n -------------\n \ndiff --git a/Documentation/git-stash.adoc b/Documentation/git-stash.adoc\nindex fc6a9a008c..d6e8c4144c 100644\n--- a/Documentation/git-stash.adoc\n+++ b/Documentation/git-stash.adoc\n@@ -133,7 +133,7 @@ with no conflicts.\n `clear`::\n \tRemove all the stash entries. Note that those entries will then\n \tbe subject to pruning, and may be impossible to recover (see\n-\t'EXAMPLES' below for a possible strategy).\n+\t<<EXAMPLES,'EXAMPLES'>> below for a possible strategy).\n \n `drop [-q | --quiet] [<stash>]`::\n \tRemove a single stash entry from the list of stash entries.\n@@ -315,6 +315,7 @@ of the index, and `W` is a commit that records the state of the working\n tree.\n \n \n+[[EXAMPLES]]\n EXAMPLES\n --------\n \ndiff --git a/Documentation/git-svn.adoc b/Documentation/git-svn.adoc\nindex 2a7fa60465..baaf3bff4e 100644\n--- a/Documentation/git-svn.adoc\n+++ b/Documentation/git-svn.adoc\n@@ -126,7 +126,7 @@ your Perl's Getopt::Long is < v2.37).\n \tcommand-line argument.\n +\n This automatically updates the rev_map if needed (see\n-'$GIT_DIR/svn/\\**/.rev_map.*' in the FILES section below for details).\n+'$GIT_DIR/svn/\\**/.rev_map.*' in the <<FILES,FILES>> section below for details).\n \n --localtime;;\n \tStore Git commit times in the local time zone instead of UTC.  This\n@@ -239,7 +239,7 @@ Like 'git rebase'; this requires that the working tree be clean\n and have no uncommitted changes.\n +\n This automatically updates the rev_map if needed (see\n-'$GIT_DIR/svn/\\**/.rev_map.*' in the FILES section below for details).\n+'$GIT_DIR/svn/\\**/.rev_map.*' in the <<FILES,FILES>> section below for details).\n \n -l;;\n --local;;\n@@ -524,7 +524,7 @@ This will set the property 'svn:keywords' to 'FreeBSD=%H' for the file\n \tway to repair the repo is to use 'reset'.\n +\n Only the rev_map and refs/remotes/git-svn are changed (see\n-'$GIT_DIR/svn/\\**/.rev_map.*' in the FILES section below for details).\n+'$GIT_DIR/svn/\\**/.rev_map.*' in the <<FILES,FILES>> section below for details).\n Follow 'reset' with a 'fetch' and then 'git reset' or 'git rebase' to\n move local branches onto the new tree.\n \n@@ -946,7 +946,7 @@ copy history (including branches and tags) for repositories adopting a\n standard layout, it cannot yet represent merge history that happened\n inside git back upstream to SVN users.  Therefore it is advised that\n users keep history as linear as possible inside Git to ease\n-compatibility with SVN (see the CAVEATS section below).\n+compatibility with SVN (see the <<CAVEATS,CAVEATS>> section below).\n \n HANDLING OF SVN BRANCHES\n ------------------------\n@@ -994,6 +994,7 @@ to r.199 (one containing trunk/, one containing trunk/sub/). Finally,\n it will create a branch 'sub@200' pointing to the new parent commit of\n branch 'sub' (i.e. the commit for r.200 and trunk/sub/).\n \n+[[CAVEATS]]\n CAVEATS\n -------\n \n@@ -1135,6 +1136,7 @@ or tag has appeared. If the subset of branches or tags is changed after\n fetching, then $GIT_DIR/svn/.metadata must be manually edited to remove\n (or reset) branches-maxRev and/or tags-maxRev as appropriate.\n \n+[[FILES]]\n FILES\n -----\n $GIT_DIR/svn/\\**/.rev_map.*::\ndiff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc\nindex 32787eacc3..e6e77252ab 100644\n--- a/Documentation/git-worktree.adoc\n+++ b/Documentation/git-worktree.adoc\n@@ -50,8 +50,8 @@ at the same commit as the current branch.\n \n If a working tree is deleted without using `git worktree remove`, then\n its associated administrative files, which reside in the repository\n-(see \"DETAILS\" below), will eventually be removed automatically (see\n-`gc.worktreePruneExpire` in linkgit:git-config[1]), or you can run\n+(see <<DETAILS,\"DETAILS\">> below), will eventually be removed automatically\n+(see `gc.worktreePruneExpire` in linkgit:git-config[1]), or you can run\n `git worktree prune` in the main or any linked worktree to clean up any\n stale administrative files.\n \n@@ -360,6 +360,7 @@ share to all worktrees:\n See the documentation of `extensions.worktreeConfig` in\n linkgit:git-config[1] for more details.\n \n+[[DETAILS]]\n DETAILS\n -------\n Each linked worktree has a private sub-directory in the repository's\ndiff --git a/Documentation/gitremote-helpers.adoc b/Documentation/gitremote-helpers.adoc\nindex 39cdece16e..4d794f32ad 100644\n--- a/Documentation/gitremote-helpers.adoc\n+++ b/Documentation/gitremote-helpers.adoc\n@@ -86,7 +86,7 @@ Capabilities\n \n Each remote helper is expected to support only a subset of commands.\n The operations a helper supports are declared to Git in the response\n-to the `capabilities` command (see COMMANDS, below).\n+to the `capabilities` command (see <<COMMANDS,COMMANDS>>, below).\n \n In the following, we list all defined capabilities and for\n each we list which commands a helper with that capability\n@@ -124,7 +124,7 @@ Supported commands: 'list for-push', 'export'.\n \n If a helper advertises 'connect', Git will use it if possible and\n fall back to another capability if the helper requests so when\n-connecting (see the 'connect' command under COMMANDS).\n+connecting (see the 'connect' command under <<COMMANDS,COMMANDS>>).\n When choosing between 'push' and 'export', Git prefers 'push'.\n Other frontends may have some other order of preference.\n \n@@ -173,7 +173,7 @@ Supported commands: 'list', 'import'.\n \n If a helper advertises 'connect', Git will use it if possible and\n fall back to another capability if the helper requests so when\n-connecting (see the 'connect' command under COMMANDS).\n+connecting (see the 'connect' command under <<COMMANDS,COMMANDS>>).\n When choosing between 'fetch' and 'import', Git prefers 'fetch'.\n Other frontends may have some other order of preference.\n \n@@ -246,6 +246,7 @@ the remote repository.\n \tside using an explicit hash algorithm extension.\n \n \n+[[COMMANDS]]\n COMMANDS\n --------\n \n@@ -269,8 +270,10 @@ Support for this command is mandatory.\n \tunrecognized attributes are ignored. The list ends with a\n \tblank line.\n +\n-See REF LIST ATTRIBUTES for a list of currently defined attributes.\n-See REF LIST KEYWORDS for a list of currently defined keywords.\n+See <<REF_LIST_ATTRIBUTES,REF LIST ATTRIBUTES>> for a list of currently\n+defined attributes.\n+See <<REF_LIST_KEYWORDS,REF LIST KEYWORDS>> for a list of currently\n+defined keywords.\n +\n Supported if the helper has the \"fetch\" or \"import\" capability.\n \n@@ -435,6 +438,7 @@ completing a valid response for the current command.\n Additional commands may be supported, as may be determined from\n capabilities reported by the helper.\n \n+[[REF_LIST_ATTRIBUTES]]\n REF LIST ATTRIBUTES\n -------------------\n \n@@ -446,6 +450,7 @@ attributes are defined.\n \tThis ref is unchanged since the last import or fetch, although\n \tthe helper cannot necessarily determine what value that produced.\n \n+[[REF_LIST_KEYWORDS]]\n REF LIST KEYWORDS\n -----------------\n \ndiff --git a/Documentation/gitsubmodules.adoc b/Documentation/gitsubmodules.adoc\nindex 2082296199..8e8165637b 100644\n--- a/Documentation/gitsubmodules.adoc\n+++ b/Documentation/gitsubmodules.adoc\n@@ -21,7 +21,8 @@ A submodule is a repository embedded inside another repository.\n The submodule has its own history; the repository it is embedded\n in is called a superproject.\n \n-On the filesystem, a submodule usually (but not always - see FORMS below)\n+On the filesystem, a submodule usually\n+(but not always - see <<FORMS,FORMS>> below)\n consists of (i) a Git directory located under the `$GIT_DIR/modules/`\n directory of its superproject, (ii) a working directory inside the\n superproject's working directory, and a `.git` file at the root of\n@@ -102,8 +103,8 @@ remotes are configured in the submodule as usual in the `$GIT_DIR/config`\n file.\n \n  * The configuration file `$GIT_DIR/config` in the superproject.\n-   Git only recurses into active submodules (see \"ACTIVE SUBMODULES\"\n-   section below).\n+   Git only recurses into active submodules\n+   (see <<ACTIVE_SUBMODULES,\"ACTIVE SUBMODULES\">> section below).\n +\n If the submodule is not yet initialized, then the configuration\n inside the submodule does not exist yet, so where to\n@@ -122,6 +123,7 @@ If the submodule has never been initialized, this is the only place\n where submodule configuration is found. It serves as the last fallback\n to specify where to obtain the submodule from.\n \n+[[FORMS]]\n FORMS\n -----\n \n@@ -165,6 +167,7 @@ from another repository.\n To completely remove a submodule, manually delete\n `$GIT_DIR/modules/<name>/`.\n \n+[[ACTIVE_SUBMODULES]]\n ACTIVE SUBMODULES\n -----------------\n \ndiff --git a/Documentation/gitworkflows.adoc b/Documentation/gitworkflows.adoc\nindex 59305265c5..4a4aea9fb4 100644\n--- a/Documentation/gitworkflows.adoc\n+++ b/Documentation/gitworkflows.adoc\n@@ -245,8 +245,9 @@ tag to the tip of 'master' indicating the release version:\n `git tag -s -m \"Git X.Y.Z\" vX.Y.Z master`\n =====================================\n \n-You need to push the new tag to a public Git server (see\n-\"DISTRIBUTED WORKFLOWS\" below). This makes the tag available to\n+You need to push the new tag to a public Git server\n+(see <<DISTRIBUTED_WORKFLOWS,\"DISTRIBUTED WORKFLOWS\">> below).\n+This makes the tag available to\n others tracking your project. The push could also trigger a\n post-update hook to perform release-related items such as building\n release tarballs and preformatted documentation pages.\n@@ -324,6 +325,7 @@ announcement is not necessary since 'seen' is a throw-away branch, as\n described above.\n \n \n+[[DISTRIBUTED_WORKFLOWS]]\n DISTRIBUTED WORKFLOWS\n ---------------------\n \ndiff --git a/Documentation/howto/revert-a-faulty-merge.adoc b/Documentation/howto/revert-a-faulty-merge.adoc\nindex 19f59cc888..fc9a330e9c 100644\n--- a/Documentation/howto/revert-a-faulty-merge.adoc\n+++ b/Documentation/howto/revert-a-faulty-merge.adoc\n@@ -146,8 +146,8 @@ different resolution strategies:\n    revert of a merge was rebuilt from scratch (i.e. rebasing and fixing,\n    as you seem to have interpreted), then re-merging the result without\n    doing anything else fancy would be the right thing to do.\n-   (See the ADDENDUM below for how to rebuild a branch from scratch\n-   without changing its original branching-off point.)\n+   (See the <<ADDENDUM,ADDENDUM>> below for how to rebuild a branch\n+   from scratch without changing its original branching-off point.)\n \n However, there are things to keep in mind when reverting a merge (and\n reverting such a revert).\n@@ -184,6 +184,7 @@ ready yet, and I really need to undo _all_ of the merge\"). So then you\n really should revert the merge, but when you want to re-do the merge, you\n now need to do it by reverting the revert.\n \n+[[ADDENDUM]]\n ADDENDUM\n \n Sometimes you have to rewrite one of a topic branch's commits *and* you can't\ndiff --git a/Documentation/revisions.adoc b/Documentation/revisions.adoc\nindex 3fbfbd3d5f..3bb6dc85b6 100644\n--- a/Documentation/revisions.adoc\n+++ b/Documentation/revisions.adoc\n@@ -1,3 +1,4 @@\n+[[SPECIFYING_REVISIONS]]\n SPECIFYING REVISIONS\n --------------------\n \n@@ -300,7 +301,8 @@ Dotted Range Notations\n The '..' (two-dot) Range Notation::\n  The '{caret}r1 r2' set operation appears so often that there is a shorthand\n  for it.  When you have two commits 'r1' and 'r2' (named according\n- to the syntax explained in SPECIFYING REVISIONS above), you can ask\n+ to the syntax explained in\n+<<SPECIFYING_REVISIONS,SPECIFYING REVISIONS>> above), you can ask\n  for commits that are reachable from r2 excluding those that are reachable\n  from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.\n \n\nbase-commit: 3bc0341126508f78f5869cbfc0005e987efdf0c7\n-- \ngitgitgadget\n"},{"id":"553268","messageId":"20260925082723.GB1493716@coredump.intra.peff.net","threadId":"66371","inReplyTo":"pull.2416.v2.git.git.1790297546771.gitgitgadget@gmail.com","subject":"Re: [PATCH v2] doc: add more AsciiDoc cross-references","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2026-09-25T08:27:23Z","receivedAt":"2026-09-25T08:27:25Z","isPatch":true,"body":"On Fri, Sep 25, 2026 at 12:52:26AM +0000, Julia Evans via GitGitGadget wrote:\n\n>     This version rewrites the commit message to be more accurate. The\n>     original message said that the problem was to do with included pages\n>     which wasn't true.\n\nThanks, it looks good to me.\n\n-Peff\n"},{"id":"553289","messageId":"bd5d9451-ac5a-4274-9a7a-57ae99864fe9@app.fastmail.com","threadId":"66371","inReplyTo":"20260925082723.GB1493716@coredump.intra.peff.net","subject":"Rewriting the Git tutorial to cover less content","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-09-25T16:08:51Z","receivedAt":"2026-09-25T16:09:14Z","isPatch":false,"body":"Hello!\n\nI'm working on a patch series to replace `gittutorial.adoc` with a completely\nrewritten tutorial, since a lot has changed since it was originally written.\n\nThe new tutorial will cover much less material: just `git init`, `git add`,\n`git commit`, `git status`,  `git diff`, `git push`, `git config`, and `git remote add`. \nOne choice that might be controversial is that I'm not covering branches, \nthough I think it would probably make sense to write a second tutorial on\nbranches and using Git to collaborate later.\n\nThe reason to cover fewer commands is that even this smaller set of commands\nis a lot for beginners to absorb. I've already gotten feedback from a test\nreader that they appreciated the \"you can stop here!\" in the middle of the\ntutorial, since they didn't feel like they could absorb any more information at\nthat point.\n\nIf you'd like, you can read the current draft here: \nhttps://github.com/jvns/git/blob/git-tutorial/Documentation/gittutorial.adoc\nI'm not looking for detailed feedback at this stage since I expect a lot of\nthe details to change, and since right now I'm prioritizing feedback from Git\nbeginners who are trying to learn Git for the first time from the tutorial.\n\nBut if folks have major objections to the high-level structure, let me know!\n\nI'm excited about this direction, I've already gotten some positive feedback from\ntest readers, like:\n\n> I can say I liked this tutorial better than any of the other git tutorials I've tried.\n\nand\n\n> I really like the tutorial, it's easy to follow and I learned a lot!\n\nI have some ideas for what to do with `gittutorial-2` too but I'll leave\nthat for another discussion.\n\nthanks!\nJulia\n"},{"id":"553301","messageId":"xmqq7bk9wa4y.fsf@gitster.g","threadId":"66371","inReplyTo":"bd5d9451-ac5a-4274-9a7a-57ae99864fe9@app.fastmail.com","subject":"Re: Rewriting the Git tutorial to cover less content","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-09-25T16:47:41Z","receivedAt":"2026-09-25T16:47:46Z","isPatch":false,"body":"\"Julia Evans\" <julia@jvns.ca> writes:\n\n> I'm working on a patch series to replace `gittutorial.adoc` with a completely\n> rewritten tutorial, since a lot has changed since it was originally written.\n> ...\n> I'm excited about this direction, I've already gotten some positive feedback from\n> test readers, like:\n>\n>> I can say I liked this tutorial better than any of the other git tutorials I've tried.\n>\n> and\n>\n>> I really like the tutorial, it's easy to follow and I learned a lot!\n>\n> I have some ideas for what to do with `gittutorial-2` too but I'll leave\n> that for another discussion.\n\nAs long as it does not mean that learners now have to read three\ndocuments instead of two (i.e., your replacement, gittutorial.adoc,\nand gittutorial-2.adoc), I am also excited.\n\nOmitting some material that is covered in the current tutorial from\nthe new one would mean that the topics covered by the remainder of\nthe current tutorial have to be sifted into three buckets: one that\nis to be discarded because it is no longer useful to the target\naudience, another that needs to be described somewhere in our\ndocumentation set, and the rest that need to be taught elsewhere,\nthough that may be beyond the scope of the project documentation\nand better left to other projects that produce \"books on Git\".  It\nis somewhat unclear from your description what your plan is to cover\nother topics that should still be taught.\n\nAs we reached consensus at the contributors' summit, we should wean\nourselves away from the mindset that these tutorial materials can be\nincrementally polished to match today's needs, so if the plan for\n'the rest' is also to write on these topics from the ground up, that\nwould be very good.\n\nThanks.\n"},{"id":"553305","messageId":"4c9f0480-768a-48ba-9753-b4d34188b1a1@app.fastmail.com","threadId":"66371","inReplyTo":"xmqq7bk9wa4y.fsf@gitster.g","subject":"Re: Rewriting the Git tutorial to cover less content","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-09-25T17:25:10Z","receivedAt":"2026-09-25T17:25:31Z","isPatch":false,"body":"> Omitting some material that is covered in the current tutorial from\n> the new one would mean that the topics covered by the remainder of\n> the current tutorial have to be sifted into three buckets: one that\n> is to be discarded because it is no longer useful to the target\n> audience, another that needs to be described somewhere in our\n> documentation set, and the rest that need to be taught elsewhere,\n\nI do think there's a cost to keeping guides around that are outdated\nand difficult for users to understand.\n\nFor example right now `man git` says:\n\n> See gittutorial(7) to get started, then see giteveryday(7) for\n> a useful minimum set of commands.\n\nThis is a nice friendly statement, but in my opinion `gittutorial` and\n`giteveryday` really do not live up to what it promises, and I think\nit undermines trust in the documentation.\n\n> though that may be beyond the scope of the project documentation\n> and better left to other projects that produce \"books on Git\".  It\n> is somewhat unclear from your description what your plan is to cover\n> other topics that should still be taught.\n\nI see a couple of possible strategies.\n\n* We can write new guides which are clearer\n* We can link to outside resources (via https://git-scm.com/learn)\n  which we think do a good job. Right now that page is pretty\n  out of date and it would be very easy to improve.\n\nI think a mix of both is probably most realistic right now.\n"},{"id":"553308","messageId":"xmqqh5jdur4c.fsf@gitster.g","threadId":"66371","inReplyTo":"4c9f0480-768a-48ba-9753-b4d34188b1a1@app.fastmail.com","subject":"Re: Rewriting the Git tutorial to cover less content","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-09-25T18:23:47Z","receivedAt":"2026-09-25T18:23:50Z","isPatch":false,"body":"\"Julia Evans\" <julia@jvns.ca> writes:\n\n>> See gittutorial(7) to get started, then see giteveryday(7) for\n>> a useful minimum set of commands.\n>\n> This is a nice friendly statement, but in my opinion `gittutorial` and\n> `giteveryday` really do not live up to what it promises, ...\n\nYes, it outlived its time and the world has moved on.\n\n> I see a couple of possible strategies.\n>\n> * We can write new guides which are clearer\n> * We can link to outside resources (via https://git-scm.com/learn)\n>   which we think do a good job. Right now that page is pretty\n>   out of date and it would be very easy to improve.\n>\n> I think a mix of both is probably most realistic right now.\n\nWhatever we do, it is not enough that new guides are more clear than\nthe current one.  The goal should be that it also is sufficient to\nreplace the current one.  Removing the stale and unuseful document\ncan be made the primary goal, and a new document may be a means to\ndo so ;-).\n\nI do not know if we have bandwidth to keep external links fresh, and\nhaving a set of links to stale pages ourselves may hurt more than\nhelp.\n\nThanks.\n"},{"id":"553312","messageId":"17c46e4e-a4f6-433e-8eea-c1e4eb28fdfd@app.fastmail.com","threadId":"66371","inReplyTo":"xmqqh5jdur4c.fsf@gitster.g","subject":"Re: Rewriting the Git tutorial to cover less content","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-09-25T19:22:29Z","receivedAt":"2026-09-25T19:22:50Z","isPatch":false,"body":"\n\nOn Fri, Sep 25, 2026, at 2:23 PM, Junio C Hamano wrote:\n> \"Julia Evans\" <julia@jvns.ca> writes:\n>\n>>> See gittutorial(7) to get started, then see giteveryday(7) for\n>>> a useful minimum set of commands.\n>>\n>> This is a nice friendly statement, but in my opinion `gittutorial` and\n>> `giteveryday` really do not live up to what it promises, ...\n>\n> Yes, it outlived its time and the world has moved on.\n>\n>> I see a couple of possible strategies.\n>>\n>> * We can write new guides which are clearer\n>> * We can link to outside resources (via https://git-scm.com/learn)\n>>   which we think do a good job. Right now that page is pretty\n>>   out of date and it would be very easy to improve.\n>>\n>> I think a mix of both is probably most realistic right now.\n>\n> Whatever we do, it is not enough that new guides are more clear than\n> the current one.  The goal should be that it also is sufficient to\n> replace the current one. \n\nI don't understand what you mean by \"replace the current one\". \nSome interpretations I can imagine:\n\n1. The documentation remains internally consistent, like if it says\n   \"see <page> for <information>\", then the information is in fact on that page\n2. Any information explained in a guide must always be explained a\n    in some guide in the future\n3. We should aim to make guides more _useful_ over time: on average,\n    a user reading the new version of the guide should come away having\n    learned more relevant-to-them information about Git than with the\n    old guide.\n4. The original intent of a guide needs to be maintained.\n\nI imagine everyone agrees that #1 is important. I spend most of my\ntime thinking about how to do a good job of #3.\n\n> I do not know if we have bandwidth to keep external links fresh, and\n> having a set of links to stale pages ourselves may hurt more than\n> help.\n\nWe've had a list of links like this since 2013, at https://git-scm.com/doc/ext. \nIt definitely has broken links and it would be pretty easy to update\nsome of them once, which would help in the short term.\n"},{"id":"553316","messageId":"xmqqv77tt9a4.fsf@gitster.g","threadId":"66371","inReplyTo":"17c46e4e-a4f6-433e-8eea-c1e4eb28fdfd@app.fastmail.com","subject":"Re: Rewriting the Git tutorial to cover less content","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-09-25T19:34:27Z","receivedAt":"2026-09-25T19:34:31Z","isPatch":false,"body":"\"Julia Evans\" <julia@jvns.ca> writes:\n\n> I don't understand what you mean by \"replace the current one\". \n\nIf giteveryday for example is so stale and unusable, we should drop\nthe entire file.  If there were some topics in there that can be\nsalvagd, we should freshly explain these topics elsewhere in our\ndocumentation, and starting a new document is one way to do so.\nThen we \"replaced\" the current \"giteveryday\" with something else.\n\n> Some interpretations I can imagine:\n>\n> 1. The documentation remains internally consistent, like if it says\n>    \"see <page> for <information>\", then the information is in fact on that page\n> 2. Any information explained in a guide must always be explained a\n>     in some guide in the future\n> 3. We should aim to make guides more _useful_ over time: on average,\n>     a user reading the new version of the guide should come away having\n>     learned more relevant-to-them information about Git than with the\n>     old guide.\n> 4. The original intent of a guide needs to be maintained.\n\n>> I do not know if we have bandwidth to keep external links fresh, and\n>> having a set of links to stale pages ourselves may hurt more than\n>> help.\n>\n> We've had a list of links like this since 2013, at https://git-scm.com/doc/ext. \n> It definitely has broken links and it would be pretty easy to update\n> some of them once, which would help in the short term.\n\nDealing with broken links is easier as we can just remove them.\nNoticing a link that points at an unmaintained stale document that\ndescribes what used to be relevant but no longer in today's\nenvironment and replacing it with something more relevant was what I\nam worried about.\n"},{"id":"553455","messageId":"7004c3b1-2100-4a90-9815-2a679ceb25b2@app.fastmail.com","threadId":"66371","inReplyTo":"xmqqv77tt9a4.fsf@gitster.g","subject":"Re: Rewriting the Git tutorial to cover less content","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-09-28T12:21:11Z","receivedAt":"2026-09-28T12:21:32Z","isPatch":false,"body":"> Dealing with broken links is easier as we can just remove them.\n> Noticing a link that points at an unmaintained stale document that\n> describes what used to be relevant but no longer in today's\n> environment and replacing it with something more relevant was what I\n> am worried about.\n\nThanks, this is helpful. Let me try to rephrase to see if I understand,\nlet me know if I'm understanding wrong.\n\nWhen possible, it's better to split up changes into smaller pieces so\nthat they can be reviewed more easily.\n\nFor this change, it would help to split it up into two different patch series:\n\"remove tutorial\" and \"add new tutorial\", where the first patch series\ndeletes all references to the tutorial. If we do it this way, we can\nboth make sure that there isn't any content that we regret deleting,\nand lets us take a look at the documents that reference the tutorial too.\n\n- Julia\n"},{"id":"553487","messageId":"xmqqh5j9o18e.fsf@gitster.g","threadId":"66371","inReplyTo":"7004c3b1-2100-4a90-9815-2a679ceb25b2@app.fastmail.com","subject":"Re: Rewriting the Git tutorial to cover less content","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-09-28T15:16:17Z","receivedAt":"2026-09-28T15:16:21Z","isPatch":false,"body":"\"Julia Evans\" <julia@jvns.ca> writes:\n\n>> Dealing with broken links is easier as we can just remove them.\n>> Noticing a link that points at an unmaintained stale document that\n>> describes what used to be relevant but no longer in today's\n>> environment and replacing it with something more relevant was what I\n>> am worried about.\n>\n> Thanks, this is helpful. Let me try to rephrase to see if I understand,\n> let me know if I'm understanding wrong.\n\nIn the above, I was talking about the reference links that are stale\nat https://git-scm.com/doc/ext which you mentioned.  You said that\nit is easy to update broken links there.  I wanted to point out that\nthere are two kinds of staleness, one that you can validate by\nclicking on the link and seeing 404 (your \"easy\" kind), and the\nother that you have to read what you are given by clicking on the\nlink and evaluate its relevance in today's world (which is much\nharder).\n\nSo, while I do agree with everything you said in the two paragraphs\nbelow, I do not think these two paragraphs have any rephrased\nversion of what I wanted to say ?-).\n\n> When possible, it's better to split up changes into smaller pieces so\n> that they can be reviewed more easily.\n>\n> For this change, it would help to split it up into two different patch series:\n> \"remove tutorial\" and \"add new tutorial\", where the first patch series\n> deletes all references to the tutorial. If we do it this way, we can\n> both make sure that there isn't any content that we regret deleting,\n> and lets us take a look at the documents that reference the tutorial too.\n\nYes, feeding smaller independent pieces is a format that is easier\nto review.  If the end result is that the old tutorial is gone and\nreplaced by the new tutorial, that would be what we want.  When we\nadded gittutorial-2, we did not remove gittutorial, probably because\nnobody had the guts to say \"let's rip out what Linus wrote, it is so\nout of date and gives much less relevant information useful in\ntoday's world\".\n\nI do not want to repeat that; it is like https://xkcd.com/927/.\n"}]}