doc: add more AsciiDoc cross-references - #2416

"Julia Evans via GitGitGadget" <[email protected]> writes:

> From: Julia Evans <[email protected]>
>
> Instead of saying "see EXAMPLES below", say "see <<EXAMPLES,EXAMPLES>>
> below" to make the man pages easier to navigate on the web.
>
> The reason for using the more verbose <<EXAMPLES,EXAMPLES>>
> (instead of <<EXAMPLES>>) is that if the header that `<<EXAMPLES>>`
> 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 <[email protected]>
> ---

Oh, I love a change that is so sharply focused on a single issue and
describes what the problem being solved is.

>      * 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.

> 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 <<PRUNING,PRUNING>> section below for more details.

OK, we already see an example of the <<double,double>> reference
notation.  This needs to be in this form, intead of <<pruning>>,
because it refers to the named section of a different file, namely
git-fetch.adoc (I am just trying to make sure I understood your
explanation correctly).

> @@ -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 <<PRUNING,PRUNING>> section below for more details.

Ditto.

> 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
> @@ -94,7 +94,8 @@ unbundle <file>::
>  
>  <git-rev-list-args>::
>  	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
> +	<<SPECIFYING_REFERENCES,SPECIFYING REFERENCES>>
>  	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

This doubled reference is more for consistency (in other words, "it
is easier to just make all of the links use the form") than the
"cross references from/to included page" we saw earlier, since ...

> @@ -127,6 +128,7 @@ unbundle <file>::
>  	This flag makes the command not to report its progress
>  	on the standard error stream.
>  
> +[[SPECIFYING_REFERENCES]]
>  SPECIFYING REFERENCES
>  ---------------------

... the target happens to live in the same file.  It of course
future-proofs the reference in case the section gets split out of
the file into another included one.

Thanks, will queue.

> Oh, I love a change that is so sharply focused on a single issue and
> describes what the problem being solved is.

:)

>>      * 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.
>
>> 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 <<PRUNING,PRUNING>> section below for more details.
>
> OK, we already see an example of the <<double,double>> reference
> notation.  This needs to be in this form, intead of <<pruning>>,
> because it refers to the named section of a different file, namely
> git-fetch.adoc (I am just trying to make sure I understood your
> explanation correctly).

The reason I explained this in a bit of a confusing way is that I'm not
100% sure in which exact cases we need to use <<double,double>
instead of <<single>.

I double checked just now that if in `git-push.adoc`, I change:

	of a remote (see the section <<REMOTES,REMOTES>> below),

to:

	of a remote (see the section <<REMOTES>> below),

Then there's a problem where in the HTML version it displays as
"[REMOTES]" instead of just "REMOTES".

But in the <<PRUNING,PRUNING>> example, just using <<PRUNING>>
seems to work. I started working on this way back in December 2025 
so I assume that something in this patch was affected by this issue
and that's how I came across this problem but I'm not sure exactly
what it was.

On Tue, Sep 22, 2026, at 21:29, Julia Evans via GitGitGadget wrote:
> From: Julia Evans <[email protected]>
>
> Instead of saying "see EXAMPLES below", say "see <<EXAMPLES,EXAMPLES>>
> below" to make the man pages easier to navigate on the web.
>
> The reason for using the more verbose <<EXAMPLES,EXAMPLES>>
> (instead of <<EXAMPLES>>) is that if the header that `<<EXAMPLES>>`
> 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 <[email protected]>
> ---
>[snip]

Now that I’ve read this commit message, it seems like an obvious idea
in hindsight.

On Tue, Sep 22, 2026 at 04:54:17PM -0400, Julia Evans wrote:

> >> +See the <<PRUNING,PRUNING>> section below for more details.
> >
> > OK, we already see an example of the <<double,double>> reference
> > notation.  This needs to be in this form, intead of <<pruning>>,
> > because it refers to the named section of a different file, namely
> > git-fetch.adoc (I am just trying to make sure I understood your
> > explanation correctly).
> 
> The reason I explained this in a bit of a confusing way is that I'm not
> 100% sure in which exact cases we need to use <<double,double>
> instead of <<single>.
> 
> I double checked just now that if in `git-push.adoc`, I change:
> 
> 	of a remote (see the section <<REMOTES,REMOTES>> below),
> 
> to:
> 
> 	of a remote (see the section <<REMOTES>> below),
> 
> Then there's a problem where in the HTML version it displays as
> "[REMOTES]" instead of just "REMOTES".

Reading the asciidoc docs, I'm not sure how this is affected by the
location of the reference at all. AFAICT the syntax <<FOO,BAR>> just
means "link to FOO, using the text BAR".

The single-item <<FOO>> more or less means the same as "<<FOO,FOO>>",
but as you noticed, vanilla asciidoc seems to pick the text "[FOO]"
here, whereas asciidoctor uses "FOO". I'm using asciidoc 10.2.1 and
asciidoctor 2.0.26 to test, and I see it even with the PRUNING examples,
too.

Even weirder, in the manpage output both implementations actually expand
this to: the section called "FOO". So changing your patch like this:

  -See the <<PRUNING,PRUNING>> section below for more details.
  +See the <<PRUNING>> section below for more details.

gives doc-diff output like this:

  -         See the PRUNING section below for more details.
  +         See the the section called “PRUNING” section below for more details.

which is obviously nonsense.

I could very well believe that some older versions did other weird
things in the presence of includes. ;) But AFAICT the real need for the
doubled text is to control what is in the expanded text (both because of
differences between the versions, but also differences in output
backends).

Which is kind of a shame, because writing just <<PRUNING>> makes the
source a lot more readable. I wonder if we can configure these text
fallbacks, which would let us use the single-item form reliably.

Alternatively, I think this is all syntactic sugar over "xref:FOO[BAR]".
We already have our own linkgit: macro for linking to whole pages
(which, btw, is something xref could do for us, too, though maybe not
without the magic man section number). I wonder if it would be useful to
have a section-link macro that would give us more control, but again,
the syntax of <<PRUNING>> sure is nice.

> But in the <<PRUNING,PRUNING>> example, just using <<PRUNING>>
> seems to work. I started working on this way back in December 2025 
> so I assume that something in this patch was affected by this issue
> and that's how I came across this problem but I'm not sure exactly
> what it was.

So I think using <<PRUNING,PRUNING>> is probably OK for a first pass
here, rather than getting bogged down in trying to configure both
asciidoc implementations. We can shrink them later if we come up with a
good solution.

I do think the explanation in the commit message might be misleading,
though (at least from what I can gather from the asciidoc reference and
from a few experiments).

-Peff

On Tue, Sep 22, 2026 at 07:29:02PM +0000, Julia Evans via GitGitGadget wrote:

> 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 <<EDITING_PATCHES,EDITING PATCHES>> below.
>  
>  `-u`::
>  `--update`::
> @@ -375,6 +375,7 @@ diff::
>    `HEAD` and index).
>  
>  
> +[[EDITING_PATCHES]]
>  EDITING PATCHES
>  ---------------

I think we have section auto-ids enabled these days, so I don't think
it's strictly necessary to make our own ids like this. But the generated
ids are syntactically a little different, so you'd need:

-apply to the index. See <<EDITING_PATCHES,EDITING PATCHES>> below.
+apply to the index. See <<_editing_patches,EDITING PATCHES>> below.

The asciidoctor reference made some mention of linking to sections
directly by title (a "Natural cross reference"). But it did not seem to
work for me in this case, and anyway I think it only works with the
single-argument form (which has other headaches).

So we could probably get away with using the auto-generated ones, but
it does mean using their syntax. Though there is another related issue
there: these ids are also somewhat user-visible, because they end up in
the final HTML documents and people link to them.

Right now this works:

  https://git-scm.com/docs/git-add#_editing_patches

but after your patch, I think it will have to be spelled as:

  https://git-scm.com/docs/git-add#EDITING_PATCHES

I think I prefer the all-caps one, but it is kind of gross that as we
change the docs we may break fragment links across the web. IIRC there
are similar problems with linking to list items, where we auto-generate
ids to allow linking to specific options (this is custom code on
git-scm.com, not asciidoctor and not within git.git). The resulting
fragment ids are long and gross and have changed a few times over the
years (I think we had to add in some disambiguation because multiple
lists in the same file might generate the same id).

So I dunno what all that means. Your patch "breaks" existing links into
the HTML by assigning a new (but IMHO prettier) id. At some point I
don't know how much we want to care about that. But I thought it was
worth ignoring consciously rather than accidentally. ;)

> -See the "OBJECT PREREQUISITES" section below.
> +See the <<OBJECT_PREREQUISITES,"OBJECT PREREQUISITES">> section below.

I noticed a few interesting typographic bits, like this one. I'd have
expected:

  "<<OBJECT_PREREQUISITES,OBJECT PREREQUISITES>>"

but I guess this is one of the inconsistencies you mentioned in the
cover letter. I'm fine punting on those for now and fixing them later.

Especially this one:

> -	  `BATCH OUTPUT` below for details.
> +	  <<BATCH_OUTPUT,`BATCH OUTPUT`>> below for details.

which can't move the backticks out (because they'd suppress the xref
syntax). But probably it ought to drop the backticks entirely (which
again can come later).

-Peff

> Even weirder, in the manpage output both implementations actually expand
> this to: the section called "FOO". So changing your patch like this:
>
>   -See the <<PRUNING,PRUNING>> section below for more details.
>   +See the <<PRUNING>> section below for more details.
>
> gives doc-diff output like this:
>
>   -         See the PRUNING section below for more details.
>   +         See the the section called “PRUNING” section below for more details.
>
> which is obviously nonsense.
>
> I could very well believe that some older versions did other weird
> things in the presence of includes. ;) But AFAICT the real need for the
> doubled text is to control what is in the expanded text (both because of
> differences between the versions, but also differences in output
> backends).
>
> Which is kind of a shame, because writing just <<PRUNING>> makes the
> source a lot more readable. I wonder if we can configure these text
> fallbacks, which would let us use the single-item form reliably.

Thanks for investigating, I was really dreading looking into the guts of
asciidoc to figure out exactly what was happening. It would be nice to be able
to write just <<PRUNING>>, especially because I believe asciidoctor will check
that internal links are valid, so there's no concern about breaking links if we
change the title of a section.

Re your other message about breaking links because we're changing the
HTML IDs: the options I see right now are

1. Leave it is as is and break some links
2. manually enter the ID like `_editing_patches`, trying to make sure to always
match the auto-generated ID (I'm not sure how to do that). I think this might
also cause some confusion for editors in the future as to why the section IDs
are formatted like that
3. Somehow fix it so that we can just do <<PRUNING>>

I'm not sure if #1 or #2 is better, obviously I'm biased towards #1 because
it's less work for me. #3 seems like the ideal but I don't know how to do that.

Here's a revised commit message, can submit that as a v2 if it seems correct.

    doc: add more AsciiDoc cross-references

    Instead of saying "see EXAMPLES below", say "see <<EXAMPLES,EXAMPLES>>
    below" to make the man pages easier to navigate on the web.

    The reason for using the more verbose <<EXAMPLES,EXAMPLES>>
    (instead of <<EXAMPLES>>) is in some cases, the HTML output is rendered
    as `"EXAMPLES"` or `[EXAMPLES]` instead of just `EXAMPLES`.
    So this gives us more control over how the output looks.

    This also changes some of the HTML IDs of the headings from `_examples`
    to `EXAMPLES`, which has the potential to break some links.

On Thu, Sep 24, 2026 at 08:30:31AM -0400, Julia Evans wrote:

> Thanks for investigating, I was really dreading looking into the guts of
> asciidoc to figure out exactly what was happening. It would be nice to be able
> to write just <<PRUNING>>, especially because I believe asciidoctor will check
> that internal links are valid, so there's no concern about breaking links if we
> change the title of a section.

I think asciidoc(tor) doesn't do it itself, so HTML will be generated
with a broken link. But in the manpage flow, we pass through xml
docbook, which does complain loudly. So that will be enough to let us
know about the breakage.

> 1. Leave it is as is and break some links
> 2. manually enter the ID like `_editing_patches`, trying to make sure to always
> match the auto-generated ID (I'm not sure how to do that). I think this might
> also cause some confusion for editors in the future as to why the section IDs
> are formatted like that
> 3. Somehow fix it so that we can just do <<PRUNING>>
> 
> I'm not sure if #1 or #2 is better, obviously I'm biased towards #1 because
> it's less work for me. #3 seems like the ideal but I don't know how to do that.

Yeah, sorry I was a bit rambly in my other message, but I think #1 is
OK. I'm not sure if asciidoctor allows us to configure the algorithm for
converting a title into a section id. If it does, it might be nice to
have a flag day where we make all of the auto-ids look like what we'd
expect. But that is a totally separate topic, and can happen later.

I think #3 is sort-of orthogonal, as I couldn't get the "natural" xrefs
to work. So we have to either declare the ids ourselves or use the
auto-generated ones, at which point the use of single- or double-
<<FOO>> xrefs is purely a matter for the linking site, not the linked-to
section.

> Here's a revised commit message, can submit that as a v2 if it seems correct.
> 
>     doc: add more AsciiDoc cross-references
> 
>     Instead of saying "see EXAMPLES below", say "see <<EXAMPLES,EXAMPLES>>
>     below" to make the man pages easier to navigate on the web.
> 
>     The reason for using the more verbose <<EXAMPLES,EXAMPLES>>
>     (instead of <<EXAMPLES>>) is in some cases, the HTML output is rendered
>     as `"EXAMPLES"` or `[EXAMPLES]` instead of just `EXAMPLES`.
>     So this gives us more control over how the output looks.
> 
>     This also changes some of the HTML IDs of the headings from `_examples`
>     to `EXAMPLES`, which has the potential to break some links.

Yeah, I think this is OK. If we want to be really pedantic, the
"EXAMPLES" with quotes is only in the manpages, not the HTML (and also
includes extra text: "the section called"). But the point is the same.
We must use the doubled form to get consistent text output.

-Peff

"Julia Evans" <[email protected]> writes:

> Here's a revised commit message, can submit that as a v2 if it seems correct.
>
>     doc: add more AsciiDoc cross-references
>
>     Instead of saying "see EXAMPLES below", say "see <<EXAMPLES,EXAMPLES>>
>     below" to make the man pages easier to navigate on the web.
>
>     The reason for using the more verbose <<EXAMPLES,EXAMPLES>>
>     (instead of <<EXAMPLES>>) is in some cases, the HTML output is rendered
>     as `"EXAMPLES"` or `[EXAMPLES]` instead of just `EXAMPLES`.
>     So this gives us more control over how the output looks.
>
>     This also changes some of the HTML IDs of the headings from `_examples`
>     to `EXAMPLES`, which has the potential to break some links.

To see if I understand correctly, let me rephrase the second
paragraph a bit (not as an attempt to offer an improvement; by
restating the above differently while expressing what I take to be
the same thing, we will see whether I misunderstood what you wrote
if my version ends up saying what you did not intend), as I found it
somewhat puzzling.

    The short form <<EXAMPLES>> uses EXAMPLES as both the link
    target (which is not shown to the end user except in the
    browser's location bar when the link is visited) and the
    clickable text.  In different parts of the document, however,
    the text in HTML may need to be rendered as "EXAMPLES" or
    [EXAMPLES], which can be achieved by using the
    <<EXAMPLES,"EXAMPLES">> or <<EXAMPLES,[EXAMPLES]>> form.  For
    consistency, always use the longer form, even when there are no
    such typesetting constraints.

I'll mark the topic as Expecting a reroll in my working copy of the
"What's cooking" report of the next issue.

Thanks.

> To see if I understand correctly, let me rephrase the second
> paragraph a bit (not as an attempt to offer an improvement; by
> restating the above differently while expressing what I take to be
> the same thing, we will see whether I misunderstood what you wrote
> if my version ends up saying what you did not intend), as I found it
> somewhat puzzling.
>
>     The short form <<EXAMPLES>> uses EXAMPLES as both the link
>     target (which is not shown to the end user except in the
>     browser's location bar when the link is visited) and the
>     clickable text.  In different parts of the document, however,
>     the text in HTML may need to be rendered as "EXAMPLES" or
>     [EXAMPLES], which can be achieved by using the
>     <<EXAMPLES,"EXAMPLES">> or <<EXAMPLES,[EXAMPLES]>> form.  For
>     consistency, always use the longer form, even when there are no
>     such typesetting constraints.

I meant something different, let me try again (with Peff's corrections as well):

    The reason for using the more verbose <<EXAMPLES,EXAMPLES>>
    (instead of <<EXAMPLES>>) is that in some cases, <<EXAMPLES>> is
    rendered as `the section called "EXAMPLES"` or `[EXAMPLES]`.
    <<EXAMPLES,EXAMPLES>> is rendered as just `EXAMPLES`, which gives us
    more control over the output.

("in some cases" is code for "I still don't fully understand
exactly when each one happens and why")

> I'll mark the topic as Expecting a reroll in my working copy of the
> "What's cooking" report of the next issue.
>
> Thanks.

"Julia Evans" <[email protected]> writes:

>> To see if I understand correctly, let me rephrase the second
>> paragraph a bit (not as an attempt to offer an improvement; by
>> restating the above differently while expressing what I take to be
>> the same thing, we will see whether I misunderstood what you wrote
>> if my version ends up saying what you did not intend), as I found it
>> somewhat puzzling.
>>
>>     The short form <<EXAMPLES>> uses EXAMPLES as both the link
>>     target (which is not shown to the end user except in the
>>     browser's location bar when the link is visited) and the
>>     clickable text.  In different parts of the document, however,
>>     the text in HTML may need to be rendered as "EXAMPLES" or
>>     [EXAMPLES], which can be achieved by using the
>>     <<EXAMPLES,"EXAMPLES">> or <<EXAMPLES,[EXAMPLES]>> form.  For
>>     consistency, always use the longer form, even when there are no
>>     such typesetting constraints.
>
> I meant something different, let me try again (with Peff's corrections as well):
>
>     The reason for using the more verbose <<EXAMPLES,EXAMPLES>>
>     (instead of <<EXAMPLES>>) is that in some cases, <<EXAMPLES>> is
>     rendered as `the section called "EXAMPLES"` or `[EXAMPLES]`.
>     <<EXAMPLES,EXAMPLES>> is rendered as just `EXAMPLES`, which gives us
>     more control over the output.
>
> ("in some cases" is code for "I still don't fully understand
> exactly when each one happens and why")

I see.  I think I understand now.

In your example, "leaving it vanilla without any extra adornment" is
the control you want to gain by using the two-argument form, while in
the version that shows my (mis)understanding, it is "you can mark up
the string that is shown in any way you want".

Either way, the shorthand form forces you to leave the rendering to
the toolchain, but the two-argument form gives you more control over
how the text is rendered.

Thanks.

On Thu, Sep 24, 2026 at 01:22:49PM -0400, Julia Evans wrote:

> I meant something different, let me try again (with Peff's corrections as well):
> 
>     The reason for using the more verbose <<EXAMPLES,EXAMPLES>>
>     (instead of <<EXAMPLES>>) is that in some cases, <<EXAMPLES>> is
>     rendered as `the section called "EXAMPLES"` or `[EXAMPLES]`.
>     <<EXAMPLES,EXAMPLES>> is rendered as just `EXAMPLES`, which gives us
>     more control over the output.
> 
> ("in some cases" is code for "I still don't fully understand
> exactly when each one happens and why")

I think it's just "depending on the implementation and output backends".
The complete table I saw is:

              |  HTML   | manpage
  ----------------------------------------------
  asciidoc    |  [FOO]  | the section called "FOO"
  asciidoctor |  FOO    | the section called "FOO"

I'm not sure if the manpage expansion is asciidoc itself, though, or
docbook. I guess that should be easy to test...

Ah, yeah, it's docbook. Using <<PRUNING>>, the xml generated by asciidoc
looks like this:

  and the <xref linkend="PRUNING"/> section of

and then the roff output from docbook becomes:

  and the
  the section called \(lqPRUNING\(rq
  section of

So if we wanted to override that, we'd do it at the docbook layer. If
you use <<PRUNING,PRUNING>> instead, then the xml looks like:

  and the <link linkend="PRUNING">PRUNING</link> section of

which takes the decision away from docbook and uses the text we provide.

I don't think your commit message needs to go into that detail, but I
thought it worth documenting in case we revisit this later.

-Peff

On Fri, Sep 25, 2026 at 12:52:26AM +0000, Julia Evans via GitGitGadget wrote:

>     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.

Thanks, it looks good to me.

-Peff

Hello!

I'm working on a patch series to replace `gittutorial.adoc` with a completely
rewritten tutorial, since a lot has changed since it was originally written.

The new tutorial will cover much less material: just `git init`, `git add`,
`git commit`, `git status`,  `git diff`, `git push`, `git config`, and `git remote add`. 
One choice that might be controversial is that I'm not covering branches, 
though I think it would probably make sense to write a second tutorial on
branches and using Git to collaborate later.

The reason to cover fewer commands is that even this smaller set of commands
is a lot for beginners to absorb. I've already gotten feedback from a test
reader that they appreciated the "you can stop here!" in the middle of the
tutorial, since they didn't feel like they could absorb any more information at
that point.

If you'd like, you can read the current draft here: 
https://github.com/jvns/git/blob/git-tutorial/Documentation/gittutorial.adoc
I'm not looking for detailed feedback at this stage since I expect a lot of
the details to change, and since right now I'm prioritizing feedback from Git
beginners who are trying to learn Git for the first time from the tutorial.

But if folks have major objections to the high-level structure, let me know!

I'm excited about this direction, I've already gotten some positive feedback from
test readers, like:

> I can say I liked this tutorial better than any of the other git tutorials I've tried.

and

> I really like the tutorial, it's easy to follow and I learned a lot!

I have some ideas for what to do with `gittutorial-2` too but I'll leave
that for another discussion.

thanks!
Julia

"Julia Evans" <[email protected]> writes:

> I'm working on a patch series to replace `gittutorial.adoc` with a completely
> rewritten tutorial, since a lot has changed since it was originally written.
> ...
> I'm excited about this direction, I've already gotten some positive feedback from
> test readers, like:
>
>> I can say I liked this tutorial better than any of the other git tutorials I've tried.
>
> and
>
>> I really like the tutorial, it's easy to follow and I learned a lot!
>
> I have some ideas for what to do with `gittutorial-2` too but I'll leave
> that for another discussion.

As long as it does not mean that learners now have to read three
documents instead of two (i.e., your replacement, gittutorial.adoc,
and gittutorial-2.adoc), I am also excited.

Omitting some material that is covered in the current tutorial from
the new one would mean that the topics covered by the remainder of
the current tutorial have to be sifted into three buckets: one that
is to be discarded because it is no longer useful to the target
audience, another that needs to be described somewhere in our
documentation set, and the rest that need to be taught elsewhere,
though that may be beyond the scope of the project documentation
and better left to other projects that produce "books on Git".  It
is somewhat unclear from your description what your plan is to cover
other topics that should still be taught.

As we reached consensus at the contributors' summit, we should wean
ourselves away from the mindset that these tutorial materials can be
incrementally polished to match today's needs, so if the plan for
'the rest' is also to write on these topics from the ground up, that
would be very good.

Thanks.

> Omitting some material that is covered in the current tutorial from
> the new one would mean that the topics covered by the remainder of
> the current tutorial have to be sifted into three buckets: one that
> is to be discarded because it is no longer useful to the target
> audience, another that needs to be described somewhere in our
> documentation set, and the rest that need to be taught elsewhere,

I do think there's a cost to keeping guides around that are outdated
and difficult for users to understand.

For example right now `man git` says:

> See gittutorial(7) to get started, then see giteveryday(7) for
> a useful minimum set of commands.

This is a nice friendly statement, but in my opinion `gittutorial` and
`giteveryday` really do not live up to what it promises, and I think
it undermines trust in the documentation.

> though that may be beyond the scope of the project documentation
> and better left to other projects that produce "books on Git".  It
> is somewhat unclear from your description what your plan is to cover
> other topics that should still be taught.

I see a couple of possible strategies.

* We can write new guides which are clearer
* We can link to outside resources (via https://git-scm.com/learn)
  which we think do a good job. Right now that page is pretty
  out of date and it would be very easy to improve.

I think a mix of both is probably most realistic right now.

"Julia Evans" <[email protected]> writes:

>> See gittutorial(7) to get started, then see giteveryday(7) for
>> a useful minimum set of commands.
>
> This is a nice friendly statement, but in my opinion `gittutorial` and
> `giteveryday` really do not live up to what it promises, ...

Yes, it outlived its time and the world has moved on.

> I see a couple of possible strategies.
>
> * We can write new guides which are clearer
> * We can link to outside resources (via https://git-scm.com/learn)
>   which we think do a good job. Right now that page is pretty
>   out of date and it would be very easy to improve.
>
> I think a mix of both is probably most realistic right now.

Whatever we do, it is not enough that new guides are more clear than
the current one.  The goal should be that it also is sufficient to
replace the current one.  Removing the stale and unuseful document
can be made the primary goal, and a new document may be a means to
do so ;-).

I do not know if we have bandwidth to keep external links fresh, and
having a set of links to stale pages ourselves may hurt more than
help.

Thanks.

On Fri, Sep 25, 2026, at 2:23 PM, Junio C Hamano wrote:
> "Julia Evans" <[email protected]> writes:
>
>>> See gittutorial(7) to get started, then see giteveryday(7) for
>>> a useful minimum set of commands.
>>
>> This is a nice friendly statement, but in my opinion `gittutorial` and
>> `giteveryday` really do not live up to what it promises, ...
>
> Yes, it outlived its time and the world has moved on.
>
>> I see a couple of possible strategies.
>>
>> * We can write new guides which are clearer
>> * We can link to outside resources (via https://git-scm.com/learn)
>>   which we think do a good job. Right now that page is pretty
>>   out of date and it would be very easy to improve.
>>
>> I think a mix of both is probably most realistic right now.
>
> Whatever we do, it is not enough that new guides are more clear than
> the current one.  The goal should be that it also is sufficient to
> replace the current one. 

I don't understand what you mean by "replace the current one". 
Some interpretations I can imagine:

1. The documentation remains internally consistent, like if it says
   "see <page> for <information>", then the information is in fact on that page
2. Any information explained in a guide must always be explained a
    in some guide in the future
3. We should aim to make guides more _useful_ over time: on average,
    a user reading the new version of the guide should come away having
    learned more relevant-to-them information about Git than with the
    old guide.
4. The original intent of a guide needs to be maintained.

I imagine everyone agrees that #1 is important. I spend most of my
time thinking about how to do a good job of #3.

> I do not know if we have bandwidth to keep external links fresh, and
> having a set of links to stale pages ourselves may hurt more than
> help.

We've had a list of links like this since 2013, at https://git-scm.com/doc/ext. 
It definitely has broken links and it would be pretty easy to update
some of them once, which would help in the short term.

"Julia Evans" <[email protected]> writes:

> I don't understand what you mean by "replace the current one". 

If giteveryday for example is so stale and unusable, we should drop
the entire file.  If there were some topics in there that can be
salvagd, we should freshly explain these topics elsewhere in our
documentation, and starting a new document is one way to do so.
Then we "replaced" the current "giteveryday" with something else.

> Some interpretations I can imagine:
>
> 1. The documentation remains internally consistent, like if it says
>    "see <page> for <information>", then the information is in fact on that page
> 2. Any information explained in a guide must always be explained a
>     in some guide in the future
> 3. We should aim to make guides more _useful_ over time: on average,
>     a user reading the new version of the guide should come away having
>     learned more relevant-to-them information about Git than with the
>     old guide.
> 4. The original intent of a guide needs to be maintained.

>> I do not know if we have bandwidth to keep external links fresh, and
>> having a set of links to stale pages ourselves may hurt more than
>> help.
>
> We've had a list of links like this since 2013, at https://git-scm.com/doc/ext. 
> It definitely has broken links and it would be pretty easy to update
> some of them once, which would help in the short term.

Dealing with broken links is easier as we can just remove them.
Noticing a link that points at an unmaintained stale document that
describes what used to be relevant but no longer in today's
environment and replacing it with something more relevant was what I
am worried about.