Re: [PATCH v2] doc: use `man git` to teach users how to navigate the docs
On Wed, Oct 7, 2026, at 3:13 PM, Junio C Hamano wrote:
Show 26 quoted lines
> "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> 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.
Thanks, can do. Here's my thought process:
- Removed 'cli' because (from my perspective as a user) it seems like
something that's written for Git developers and not users, like
with "Commands that support the enhanced option parser",
how is a user supposed to know which commands support
the enhanced parser? I think it makes sense as a guide to
scripting Git but not for interactive use. Some of the bits on `diff`
feel like they might belong in the `git diff` man page, not sure.
- Removed "user-manual" because it's outdated. The chapter on
"Sharing development with others" explains how to use
`git format-patch` which is not how most people collaborate with
git.
- Once all the others were removed it seemed a bit out of place
to mention `gitdatamodel`.
Julia Evans <julia@jvns.ca>