From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-dy2-f12.google.com (mail-dy2-f12.google.com [74.125.229.12]) (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 BCA78149C7B for ; Fri, 25 Sep 2026 00:52:34 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=74.125.229.12 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1790297558; cv=none; b=CPQV1y85MabhW7Y24FX2/+IC7iKUyCmy0YuSPBWogodxZS6hDPALUT8lvcDiFSUMWxt0LxjZVscmOVoS9gYONJYT9ibawYwu65iH6DKU7VuOCYAhtYl8B6627dkroTtzc3gQVddYRb6wF42Qwz+pOmBYw6EOXPJXiic3mqepyfM= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1790297558; c=relaxed/simple; bh=TzxVePSVfSShERd00lqVb+LrXOIwxl6niEGTq/vamLs=; h=Message-Id:In-Reply-To:References:From:Date:Subject:Content-Type: MIME-Version:To:Cc; b=JsnYXMddSoJZxYjo2YZTtdQaFTnDADtLBsWnCaeR+B4ZNR1LntPOrTcH0yG+2kNOU0f0Pn6j0l0w37GGE1/CLwgXq6loNTP+IFqpTT3CIFvd9ITn/acft4o02NkEATjmvIDvLzfg9hwiz6Y3S3k9iakVGRBbu3wO11iqtZb65JQ= 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=ZWDwB9sF; arc=none smtp.client-ip=74.125.229.12 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="ZWDwB9sF" Received: by mail-dy2-f12.google.com with SMTP id 5a478bee46e88-328664e051fso378743eec.1 for ; Thu, 24 Sep 2026 17:52:34 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1790297554; x=1790902354; darn=vger.kernel.org; h=cc:to:mime-version:content-transfer-encoding:content-type:fcc :subject:date:from:references:in-reply-to:message-id:from:to:cc :subject:date:message-id:reply-to:content-type; bh=BUGN7sAyIE3m4md55jzXhKmvpUfEFCRSD6mcMzn7DS0=; b=ZWDwB9sFGQq2DG+RRezaZsOLjwPJSYunf2e1WR2hTKXL28iId2RbuqOO5JndAq1j6x yUetJUweXdpfZqmR4qKY5k97osW3EWCH6i1t+Ds2gtjVG/6JBWXfARXhewpxkH/aN4yG JL9OTrKx8w5HzEueXCw3ve8wf7B3MmVE5q7gfgk7cENirfF2VTPKrHV84QYc8qa7bi/1 sOWq5T+u2wpKpuFyO0IddGcszRCbfN3yDhCzfxaddj3mdt9mGLBX1RKs37lyqwBTjMqN POIxrYavpQEXyUDhoPBmHQMGQhijXbrfZVQ3/4OFztyRXZCVKKUHHVLMNVD4VmNlxGAB iqKg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20260707; t=1790297554; x=1790902354; h=cc:to:mime-version:content-transfer-encoding:content-type:fcc :subject:date:from:references:in-reply-to:message-id:x-gm-gg :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to :content-type; bh=BUGN7sAyIE3m4md55jzXhKmvpUfEFCRSD6mcMzn7DS0=; b=fTsQCepzf26jk4fbsASlgdqZMZFX8ufSOHy4YUewMDI044dTB7hxsHbXPewSvIpMup T0PEYPqeWE5g3R2IT+AQdQu3JH6qstXzFv1iGaaxFkvz5bchz7V5VOaDR7j2ddeBNqzQ 3Ce2Mm39872b3C5ON1aEpOBCXmt3rypjmBeDD8Z5EO117fKmm6jEhkXs9q8GgP+wGqNR JAktgZa57LIhtAOhklMTx5VyAyKw0R6NtYpRlKRbYFLiN51QjE/DaVRU+HVNWopx0RGA zzUMNgVlYJCUmDK161+KckHVnW8HP47ti+FS7fv1eybOXlQy6ayBSJaeprx4/XZO9Z/9 oSIg== X-Gm-Message-State: AFuF++lV0Icguzyv4cWvktsB+hn52ymLNko7/n8XrUy4bXOrjIStbiXf VBmhD1QE72asj60e1yFfZgGGNYo6Ss514JL13JRRIV37cODNC332CeWboy4uIaMw X-Gm-Gg: AYBFou2smo40eVPSS3LBkrrMuLXy+0HCAwXl4cgTlSI+pK5Tddx5ArXz9HyWpOn1nCs nCc4o+X9luDfLhSxiPuS+cFyu+vfW/99WjTNjdKOPI9qGpQsOEgjvQ5FkrxNn5NviiJtGzJDz1X xyZhRFN3yAhoxjNcKCUkFiw4jac+cB+vALGKxcXpqPr1ycoG2lRIDYryaPFLR+9AjHh130Spb8z vDX+aqcOA5bGYcMY5Z0AQzR5ImpghDxxS3lvFesT1Zfy1+RY4bwUWkWC/UA8vuAUrwn+CBqTnX9 ki5bOlTmStnU6k8QEexxs+4e2w5bS9gmfPmB7b8lCd1MkkVgfW/2xLqSgFfpk133eG17zXJ0RoP 0re2qLm6jlxgpaptOGmhcaJD6rp8C5ouUbPGN7oxE9vP68m2mRdLt9YJYmc9mXIviSXvSlFxAB3 eTkhz+u2EMoLMx93pQObyl6Tv3XglUH8P77M0mx/KNvUyQAFhJyARZ3WB25tbeM7LfTrqMpDHkw iRk X-Received: by 2002:a05:7300:cf90:b0:339:7b3b:236d with SMTP id 5a478bee46e88-34001f081bcmr3267210eec.15.1790297548505; Thu, 24 Sep 2026 17:52:28 -0700 (PDT) Received: from [127.0.0.1] ([172.184.219.156]) by smtp.gmail.com with ESMTPSA id 5a478bee46e88-3414456b496sm1968193eec.11.2026.09.24.17.52.27 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 24 Sep 2026 17:52:27 -0700 (PDT) Message-Id: In-Reply-To: References: From: "Julia Evans via GitGitGadget" Date: Fri, 25 Sep 2026 00:52:26 +0000 Subject: [PATCH v2] 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: Kristoffer Haugsbakk , Jeff King , 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 in some cases, <> is rendered as `the section called "EXAMPLES"` or `[EXAMPLES]`. <> is rendered as `EXAMPLES`, which gives us more control over the output. This also changes some of the HTML IDs of the headings from `_examples` to `EXAMPLES`, which has the potential to break some links. Signed-off-by: Julia Evans --- doc: add more AsciiDoc cross-references This version rewrites the commit message to be more accurate. The original message said that the problem was to do with included pages which wasn't true. Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2416%2Fjvns%2Fanchors-v2 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2416/jvns/anchors-v2 Pull-Request: https://github.com/git/git/pull/2416 Range-diff vs v1: 1: 419aa1259f ! 1: 8f4e7bae85 doc: add more AsciiDoc cross-references @@ Commit message 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. + (instead of <>) is that in some cases, <> is + rendered as `the section called "EXAMPLES"` or `[EXAMPLES]`. + <> is rendered as `EXAMPLES`, which gives us more + control over the output. + + This also changes some of the HTML IDs of the headings from `_examples` + to `EXAMPLES`, which has the potential to break some links. Signed-off-by: Julia Evans 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 `