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

From: Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com>
Date: Oct 7, 2026, 06:06 UTC
Message-ID: <ea29fe74-7f76-440c-9597-fdbc173be90f@app.fastmail.com>
In-Reply-To: <pull.2242.v2.git.1791317163584.gitgitgadget@gmail.com>

On Tue, Oct 6, 2026, at 22:06, Julia Evans via GitGitGadget wrote:

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

Yeah I can imagine.

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

I recall only relatively recently learning that `-h` is not just a shorter way to type `--help`.

Show 5 quoted lines

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

Right, aspirations are not good enough when it comes to the bread and butter everyday howtos.

Show 8 quoted lines

> Mention `git help` instead of `giteveryday` for now, which does a better
> job of giving an overview of everyday commands.
>
> Also mention `git help --guides` and `git help --user-interfaces`,
> since those parts of the documentation are useful and hard to discover.
>
> Do not mention `git help --developer-interfaces` since it's not relevant
> to users.

Okay, so now we don’t have to list out every guide that might be of interest. That’s cool.

I see that this would conflict with my topic kh/doc-gitbreaking-changes7.[1] Just would since my topic hasn’t been integrated yet (RFC). I use the old style of mentioning the new gitbreaking-changes(7) (“see <here> for ...”. I will remove that change in order to stay consistent with this topic.

🔗 1: https://lore.kernel.org/git/CV_gitbrchanges7_please.d1c@m5gid.xyz/

Show 13 quoted lines

>
> Signed-off-by: Julia Evans <julia@jvns.ca>
> ---
>     [doc] Use man git to teach users how to navigate the docs
>
>     Changes in v2:
>
>      * mention the git help push form too
>      * mention you can get HTML docs with git help --web push at the end to
>        advertise git help's great features, and remove
>        https://git.github.io/htmldocs/git.html since
>        https://git-scm.com/docs has a nicer view and 3 different options is
>        a lot.

Nitpick: Okay, but with the current commit message I don’t really
understand why the git.github.io link is gone. I have to guess that it
is an effective duplicate of git-scm or something since git-scm does
remain after this change.

>      * some minor wording changes
>      * fix commit message style (doc: not [doc])
>
>[snip]