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, 20:08 UTC
Message-ID: <xmqq4iex6zox.fsf@gitster.g>
In-Reply-To: <3a665230-b221-410b-9a58-96c01210aea0@app.fastmail.com>

"Julia Evans" <julia@jvns.ca> writes:

Show 7 quoted lines

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

Perhaps updating cli so that it does not give a false smell of getting written for a wrong audiences is a more productive direction, though? I do not think there is any other document that tells users the simple "options first and then revs and then paths" rule, for example.

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

Yes, the was written in a very early days, and by a person who worked in the Linux kernel circle. I do not know about "not how most people" part, but I would agree that "many users do not use" would be a fair description of the modern world order.

> - Once all the others were removed it seemed a bit out of place
>   to mention `gitdatamodel`.

Not limited to the issue of where `gitdatamodel` should fit, I think we probably should explain the goal of these change at a bit higher level. The original intention to refer to these things very early in the documentation was to direct those readers who are not ready to go into the list of git subcommands to those "introductory" text and concepts guides, and encourage them to come back once they are equipped with basic concepts and workflows. I do not know if that design actually helped or was harmful for the real-world learners, but if we are shuffling the material we present early by removing some and introducing others, we should explain what our overall design of the presentation order is, for example.

Thanks.