Re: [PATCH v2] doc: use `man git` to teach users how to navigate the docs

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 7, 2026, 19:13 UTC
Message-ID: <xmqqfqyh728j.fsf@gitster.g>
In-Reply-To: <pull.2242.v2.git.1791317163584.gitgitgadget@gmail.com>

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

Show 15 quoted lines

> From: Julia Evans <julia@jvns.ca>
>
> Many existing users of Git don't know how Git's documentation is
> structured, and a lot of folks have expressed frustration that `man git`
> doesn't make it easy to find out how to get help with using Git.
>
> Explain how Git's help system works in `man git`
> (`git push -h` gives a short help, `git push --help` is the full docs),
> since it's a slightly unusual approach.
>
> Remove the references to gittutorial and giteveryday since they're
> unlikely to help new users learn Git. Currently they feel very
> aspirational (it would be nice to have a tutorial and a guide to
> everyday Git commands!), but we should give users a realistic view of
> what the documentation actually provides.

The text mentions removing 'tutorial' and 'everyday', but does not explain why we no longer reference 'user-manual', 'datamodel', and 'cli'. The third iteration should justify this. At least, I recall that adding a reference to 'cli' early in the document was a deliberate decision, and we should explain why it is no longer relevant. It would not be surprising if it has become obsolete over the last decade, but we still need to spell out why it is no longer appropriate to reference here.

I wholeheartedly agree with dropping 'everyday', which was written before Git 1.0 back when we did not have much introductory material. It was not aspirational, and while its choice of twenty commands suited the workflows of the time, it outlived its usefulness long ago.

Thanks.