From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-qk2-f13.google.com (mail-qk2-f13.google.com [74.125.230.205]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id BB8B748988D for ; Tue, 22 Sep 2026 19:29:05 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=74.125.230.205 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1790105349; cv=none; b=GvF7hxT+J9yilGPO9TWquvFRF26JYdkApwv7X95znfTxqS6K9LAygS9KkP4N9GJXhJ/Rt4WLs6Lc8ragovHg1Syb9styZrBnlrpzCC18Ml77gasfkhoUZULYyOBCE3eBy9Tdf6Fj+9DGe5iHvt1HBaVLmI6EqcFKQx+Arzu0i7c= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1790105349; c=relaxed/simple; bh=7rnHmUB21pzWHjpofP+g7i2gdlr3X0591a3FsKExlKU=; h=Message-Id:From:Date:Subject:Content-Type:MIME-Version:To:Cc; b=hfllAj9iSVgYagH8jFswUnq/BT5hCj/Ll7mExiUfOpbAJGdcYiIFVvRyCBD0CRLGyqrWc1j7B+jCIubzhxN/JyhCC73KwRj596QrefE2CqOpZ1XCn3AAZ57dQZg8RAK+QG9PAS2Im2ZAiWN/70g2HtATUnqpTs1AdtXnZDgSVCw= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=ibDN0qu7; arc=none smtp.client-ip=74.125.230.205 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="ibDN0qu7" Received: by mail-qk2-f13.google.com with SMTP id af79cd13be357-93a0299c787so20275085a.1 for ; Tue, 22 Sep 2026 12:29:05 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1790105344; x=1790710144; darn=vger.kernel.org; h=cc:to:mime-version:content-transfer-encoding:content-type:fcc :subject:date:from:message-id:from:to:cc:subject:date:message-id :reply-to:content-type; bh=9NqL8zPdmgHbbbpyX3xnXTQWCDDbX/elg81o0tI2iPY=; b=ibDN0qu7C6WMmc3oK3m36WZkEBMLbtWNU3Nh2oKgPP92c8quBd/5F/y/p6CimXF0hX 4VcLFlOUS8TzcS2Ki1vu1oZXM47EFthzfpmVhXwFvsZdkkWm4HdYy4w1vUqUtSA9XVjd Svvx7RRNIb8k77ejdGcBdZCvVtzDiUQJNBGF9LMAu0qnptUEk+G6qyLB9LTKJe2bjWps HfYLKZ8EPD6uSVIzs8XlvGIEZPVDEEmuVkZy8NP/vgXT7MLJofmedo4d8eoEC01j+htY jT9fkH3h3EHipP4epxADTkiVpyszKYB2sZzc29m9naQUsGz83iG1hyHZ1GUBHR6i4wcv LOfQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20260707; t=1790105344; x=1790710144; h=cc:to:mime-version:content-transfer-encoding:content-type:fcc :subject:date:from:message-id:x-gm-gg:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to:content-type; bh=9NqL8zPdmgHbbbpyX3xnXTQWCDDbX/elg81o0tI2iPY=; b=TLKiSvEA0pNB7wNXB0nQVdmm6wf6fz3jQRkideU0iSASOcTc0wMd8hO7KXVdsubi6S kD2ZC0EqMymSHnA1O2oesrlRYXEisa4VlFzMpapY5PjInY8EUJL3IaY/yvbgBmMYj+QA AWQ5XgjZwdKBQ9ojkVdyRqNqO/xVlDnGscwOxuav8/pmY5mffyaIPXJp3bRXEVBcGgWp SUlXcSm205XU6UU5PaVrP8SxJNGvPIJltTnYeJ9DteG+9Q/BZjXt/m51huwQfbghs+oM CtE1N2w5KBFe77ADsSRZ8NSxdfL+TFBLug3UOTMgSv78oHsCPg3wmNeqPCjdPFRuPaU+ d0OA== X-Gm-Message-State: AFuF++lh+b7c6FOLyysx6C8ZsCBrXwp2+YKWArbU1oq0wNKGfz9uF5hU HruGECcGs+Rl8KmFzVEPjLi6NQaaZOEcbadvCfJa40b8hyrYapZy91hcWtDKhw== X-Gm-Gg: AYBFou16v1ujgmA36n8+CQeQLoOPQVY1vXP+dXjD5WlEpMswe2EWPvzgmjgIRMJ5tZM JwPJTr3fQdTXgGUvTMOxODIYmBGjHd82iMOgEdtyAxb8nYL3o7htuuH88ebGF+e6TkBw37OsUjr E5WAU79y4Jv30I8QrMZYA2pVxuwwrbS7sWhCSoRyvIUyKupAsyzaKaJmpLSjRsS7ERxsv6RbFBM SHSQ74E46XoZCXklryxX3BLpumR9XdRaKFX2s4ULwluZPcVwkIijJ8jskeGh8vHupO9gcwY8m5x R0gz+ZN8FySLb7CRs0tPqqiQej0ONZMFwGWtjQdhBKXQCt+z5FA89Wad0Zgbo0UvEQQx1cZGiHh YWNMhYHEtOc8u5HF5sUYYEq1BHN7Yge8n1Fy1PzrxywUgeBaOAIqKNrWPiAjIHTCnmfnxMp+GZG GgL6PDONer90cpGYUgYgu2P9JrOS6Bk097vQHo1stXs/6PvyP1Sedh/2bTsZFOcdxJuf/5p9QMV g== X-Received: by 2002:a05:620a:618a:b0:93b:c332:3d96 with SMTP id af79cd13be357-93c251c9c04mr60719785a.40.1790105344083; Tue, 22 Sep 2026 12:29:04 -0700 (PDT) Received: from [127.0.0.1] ([74.235.142.16]) by smtp.gmail.com with ESMTPSA id d75a77b69052e-532eb32fe82sm3958451cf.18.2026.09.22.12.29.03 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 22 Sep 2026 12:29:03 -0700 (PDT) Message-Id: From: "Julia Evans via GitGitGadget" Date: Tue, 22 Sep 2026 19:29:02 +0000 Subject: [PATCH] doc: add more AsciiDoc cross-references Fcc: Sent Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Precedence: bulk X-Mailing-List: git@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 To: git@vger.kernel.org Cc: Julia Evans , Julia Evans From: Julia Evans Instead of saying "see EXAMPLES below", say "see <> below" to make the man pages easier to navigate on the web. The reason for using the more verbose <> (instead of <>) is that if the header that `<>` is referring to is in an included page (for example `REMOTES` in the `git-push` man page), then AsciiDoc will think it's a broken link even though it isn't. So it's easier to just make all of the links use the form with two parts. Signed-off-by: Julia Evans --- doc: add more AsciiDoc cross-references This patch is a bit long so it's hard to review manually. A few notes about testing: * I tested it by running this script (https://gist.github.com/jvns/039c8ed0add092f2179f0dba52ebb896) which builds the previous and current views of all the man pages. I looked at the output to make sure there were no differences. You can see the output in that gist. * I believe that asciidoctor will automatically make sure that there are no broken links. * I also spot checked some of the HTML output to make sure it looked reasonable. There are some inconsistencies in how the cross-references are formatted but I left in all of the inconsistencies for now because it makes it easier to test that we're not introducing mistakes. Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2416%2Fjvns%2Fanchors-v1 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2416/jvns/anchors-v1 Pull-Request: https://github.com/git/git/pull/2416 Documentation/fetch-options.adoc | 4 +- Documentation/git-add.adoc | 3 +- Documentation/git-bundle.adoc | 7 +- Documentation/git-cat-file.adoc | 12 ++-- Documentation/git-checkout.adoc | 11 +-- Documentation/git-credential-cache.adoc | 3 +- Documentation/git-credential-store.adoc | 3 +- Documentation/git-fast-export.adoc | 5 +- Documentation/git-fast-import.adoc | 7 +- Documentation/git-fetch.adoc | 1 + Documentation/git-filter-branch.adoc | 3 +- Documentation/git-for-each-ref.adoc | 4 +- Documentation/git-format-patch.adoc | 4 +- Documentation/git-gc.adoc | 12 ++-- Documentation/git-grep.adoc | 9 ++- Documentation/git-http-backend.adoc | 6 +- Documentation/git-ls-files.adoc | 8 ++- Documentation/git-ls-tree.adoc | 3 +- Documentation/git-maintenance.adoc | 3 +- Documentation/git-merge-tree.adoc | 2 +- Documentation/git-notes.adoc | 14 ++-- Documentation/git-p4.adoc | 12 ++-- Documentation/git-pack-objects.adoc | 5 +- Documentation/git-prune.adoc | 3 +- Documentation/git-push.adoc | 10 +-- Documentation/git-rebase.adoc | 69 +++++++++++-------- Documentation/git-replay.adoc | 4 +- Documentation/git-repo.adoc | 5 +- Documentation/git-rev-parse.adoc | 7 +- Documentation/git-send-email.adoc | 5 +- Documentation/git-stash.adoc | 3 +- Documentation/git-svn.adoc | 10 +-- Documentation/git-worktree.adoc | 5 +- Documentation/gitremote-helpers.adoc | 15 ++-- Documentation/gitsubmodules.adoc | 9 ++- Documentation/gitworkflows.adoc | 6 +- .../howto/revert-a-faulty-merge.adoc | 5 +- Documentation/revisions.adoc | 4 +- 38 files changed, 190 insertions(+), 111 deletions(-) diff --git a/Documentation/fetch-options.adoc b/Documentation/fetch-options.adoc index 035f780e58..47dea1de8e 100644 --- a/Documentation/fetch-options.adoc +++ b/Documentation/fetch-options.adoc @@ -199,7 +199,7 @@ endif::git-pull[] providing the tag refspec. ifndef::git-pull[] + -See the PRUNING section below for more details. +See the <> section below for more details. `-P`:: `--prune-tags`:: @@ -210,7 +210,7 @@ See the PRUNING section below for more details. a shorthand for providing the explicit tag refspec along with `--prune`, see the discussion about that in its documentation. + -See the PRUNING section below for more details. +See the <> section below for more details. endif::git-pull[] diff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc index 16b06e38e1..906db7ccf3 100644 --- a/Documentation/git-add.adoc +++ b/Documentation/git-add.adoc @@ -117,7 +117,7 @@ The intent of this option is to pick and choose lines of the patch to apply, or even to modify the contents of lines to be staged. This can be quicker and more flexible than using the interactive hunk selector. However, it is easy to confuse oneself and create a patch that does not -apply to the index. See EDITING PATCHES below. +apply to the index. See <> below. `-u`:: `--update`:: @@ -375,6 +375,7 @@ diff:: `HEAD` and index). +[[EDITING_PATCHES]] EDITING PATCHES --------------- diff --git a/Documentation/git-bundle.adoc b/Documentation/git-bundle.adoc index 03cd36fe8d..cd722bd674 100644 --- a/Documentation/git-bundle.adoc +++ b/Documentation/git-bundle.adoc @@ -43,7 +43,7 @@ header indicating what references are contained within the bundle. Like the packed archive format itself bundles can either be self-contained, or be created using exclusions. -See the "OBJECT PREREQUISITES" section below. +See the <> section below. Bundles created using revision exclusions are "thin packs" created using the `--thin` option to linkgit:git-pack-objects[1], and @@ -94,7 +94,8 @@ unbundle :: :: A list of arguments, acceptable to 'git rev-parse' and - 'git rev-list' (and containing a named ref, see SPECIFYING REFERENCES + 'git rev-list' (and containing a named ref, see + <> below), that specifies the specific objects and references to transport. For example, `master~10..master` causes the current master reference to be packaged along with all objects @@ -127,6 +128,7 @@ unbundle :: This flag makes the command not to report its progress on the standard error stream. +[[SPECIFYING_REFERENCES]] SPECIFYING REFERENCES --------------------- @@ -169,6 +171,7 @@ $ git bundle create master-yesterday.bundle master~10..master~5 fatal: Refusing to create empty bundle. ---------------- +[[OBJECT_PREREQUISITES]] OBJECT PREREQUISITES -------------------- diff --git a/Documentation/git-cat-file.adoc b/Documentation/git-cat-file.adoc index 514bfc0032..c4ea2524cf 100644 --- a/Documentation/git-cat-file.adoc +++ b/Documentation/git-cat-file.adoc @@ -115,7 +115,7 @@ are not of the requested type. -- * When used with `--textconv` or `--filters`, the input lines must specify the path, separated by whitespace. See the section - `BATCH OUTPUT` below for details. + <> below for details. * When used with `--use-mailmap`, for commit and tag objects, the contents part of the output shows the identities replaced using the @@ -133,7 +133,7 @@ are not of the requested type. -- * When used with `--textconv` or `--filters`, the input lines must specify the path, separated by whitespace. See the section - `BATCH OUTPUT` below for details. + <> below for details. * When used with `--use-mailmap`, for commit and tag objects, the printed object information shows the size of the object as if the @@ -149,7 +149,7 @@ are not of the requested type. -- * When used with `--textconv` or `--filters`, the input lines must specify the path, separated by whitespace. See the section - `BATCH OUTPUT` below for details. + <> below for details. * When used with `--use-mailmap`, for commit and tag objects, the `contents` command shows the identities replaced using the @@ -295,6 +295,7 @@ If `-p` is specified, the contents of `` are pretty-printed. If `` is specified, the raw (though uncompressed) contents of the `` will be returned. +[[BATCH_OUTPUT]] BATCH OUTPUT ------------ @@ -333,12 +334,12 @@ newline. The available atoms are: `objectsize:disk`:: The size, in bytes, that the object takes up on disk. See the - note about on-disk sizes in the `CAVEATS` section below. + note about on-disk sizes in the <> section below. `deltabase`:: If the object is stored as a delta on-disk, this expands to the full hex representation of the delta base object name. - Otherwise, expands to the null OID (all zeroes). See `CAVEATS` + Otherwise, expands to the null OID (all zeroes). See <> below. `rest`:: @@ -447,6 +448,7 @@ are replaced with NUL terminators. This ensures that output will be parsable if the output itself would contain a linefeed and is thus recommended for scripting purposes. +[[CAVEATS]] CAVEATS ------- diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc index a8b3b8c2e2..2aefea0228 100644 --- a/Documentation/git-checkout.adoc +++ b/Documentation/git-checkout.adoc @@ -27,7 +27,8 @@ DESCRIPTION 2. **Restore a different version of a file**, for example with `git checkout ` or `git checkout ` -See ARGUMENT DISAMBIGUATION below for how Git decides which one to do. +See <> below +for how Git decides which one to do. `git checkout []`:: Switch to __. This sets the current branch to __ and @@ -68,7 +69,7 @@ uncommitted changes. The same as `git checkout `, except that instead of pointing `HEAD` at the branch, it points `HEAD` at the commit ID. - See the "DETACHED HEAD" section below for more. + See the <> section below for more. + Omitting __ detaches `HEAD` at the tip of the current branch. @@ -210,8 +211,8 @@ variable. Rather than checking out a branch to work on it, check out a commit for inspection and discardable experiments. This is the default behavior of `git checkout ` when - __ is not a branch name. See the "DETACHED HEAD" section - below for details. + __ is not a branch name. See the + <> section below for details. `--orphan `:: Create a new unborn branch, named __, started from @@ -372,6 +373,7 @@ leave out at most one of __ and __, in which case it defaults to ` + For more details, see the 'pathspec' entry in linkgit:gitglossary[7]. +[[DETACHED_HEAD]] DETACHED HEAD ------------- `HEAD` normally refers to a named branch (e.g. `master`). Meanwhile, each @@ -504,6 +506,7 @@ $ git reflog -2 HEAD # or $ git log -g -2 HEAD ------------ +[[ARGUMENT_DISAMBIGUATION]] ARGUMENT DISAMBIGUATION ----------------------- diff --git a/Documentation/git-credential-cache.adoc b/Documentation/git-credential-cache.adoc index 54fa7a27e1..2f6395937d 100644 --- a/Documentation/git-credential-cache.adoc +++ b/Documentation/git-credential-cache.adoc @@ -24,7 +24,7 @@ user by filesystem permissions. You probably don't want to invoke this command directly; it is meant to be used as a credential helper by other parts of Git. See -linkgit:gitcredentials[7] or `EXAMPLES` below. +linkgit:gitcredentials[7] or <> below. OPTIONS ------- @@ -54,6 +54,7 @@ credentials before their timeout, you can issue an `exit` action: git credential-cache exit -------------------------------------- +[[EXAMPLES]] EXAMPLES -------- diff --git a/Documentation/git-credential-store.adoc b/Documentation/git-credential-store.adoc index 71864a8726..3f8a426f93 100644 --- a/Documentation/git-credential-store.adoc +++ b/Documentation/git-credential-store.adoc @@ -24,7 +24,7 @@ Git programs. You probably don't want to invoke this command directly; it is meant to be used as a credential helper by other parts of git. See -linkgit:gitcredentials[7] or `EXAMPLES` below. +linkgit:gitcredentials[7] or <> below. OPTIONS ------- @@ -67,6 +67,7 @@ written to. When erasing credentials, matching credentials will be erased from all files. +[[EXAMPLES]] EXAMPLES -------- diff --git a/Documentation/git-fast-export.adoc b/Documentation/git-fast-export.adoc index 719aeca244..0c2ce385c4 100644 --- a/Documentation/git-fast-export.adoc +++ b/Documentation/git-fast-export.adoc @@ -148,12 +148,12 @@ by keeping the marks the same across runs. --anonymize:: Anonymize the contents of the repository while still retaining the shape of the history and stored tree. See the section on - `ANONYMIZING` below. + <> below. --anonymize-map=[:]:: Convert token `` to `` in the anonymized output. If `` is omitted, map `` to itself (i.e., do not - anonymize it). See the section on `ANONYMIZING` below. + anonymize it). See the section on <> below. --reference-excluded-parents:: By default, running a command such as `git fast-export @@ -219,6 +219,7 @@ referenced by that revision range contains the string 'refs/heads/master'. +[[ANONYMIZING]] ANONYMIZING ----------- diff --git a/Documentation/git-fast-import.adoc b/Documentation/git-fast-import.adoc index fd165e11d2..c5e1cec1a5 100644 --- a/Documentation/git-fast-import.adoc +++ b/Documentation/git-fast-import.adoc @@ -31,6 +31,7 @@ imports are supported from a particular foreign source depends on the frontend program in use. +[[OPTIONS]] OPTIONS ------- @@ -456,7 +457,7 @@ and control the current import process. More detailed discussion supports the specified feature, and aborts if it does not. `option`:: - Specify any of the options listed under OPTIONS that do not + Specify any of the options listed under <> that do not change stream semantic to suit the frontend's needs. This command is optional and is not needed to perform an import. @@ -1242,7 +1243,7 @@ no-relative-marks:: force:: Act as though the corresponding command-line option with a leading `--` was passed on the command line - (see OPTIONS, above). + (see <>, above). import-marks:: import-marks-if-exists:: @@ -1291,7 +1292,7 @@ options the user may specify to git fast-import itself. .... The `