From: Julia Evans via GitGitGadget Date: Fri, 16 Oct 2026 19:15:03 GMT Subject: [PATCH v3] doc: use `man git` to teach users how to navigate the docs Message-ID: In-Reply-To: From: Julia Evans Rewrite `man git` to give a more realistic view of what the documentation actually provides. 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 direct references to all the guides, for the following reasons: * gittutorial and giteveryday are 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 goal is to mention the tutorial again when when we have a tutorial we're happy with. * gitcli is not very useful for users. A lot of it is about scripting and internal details about the option parser. * the user manual is outdated. The chapter on "Sharing development with others" explains how to use `git format-patch` which is not how most Git users collaborate with git. * mentioning the data model feels out of place once everything else is removed Mention `git help` instead of `giteveryday` for now, which does a better job of giving an overview of everyday commands. Mention `git help --guides` and `git help --user-interfaces`, since there are some important guides in there (like `submodules`) that are hard to discover. Do not mention `git help --developer-interfaces` since it's not relevant to users. Remove https://git.github.io/htmldocs/git.html since it points to the `master` version of the documentation. https://git-scm.com/ has the version from the latest release which is more likely to be useful. Signed-off-by: Julia Evans --- [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. * some minor wording changes * fix commit message style (doc: not [doc]) Changes in v3: (just updates to the commit message) * Add a sentence summarizing the goals "give a more realistic view of what the documentation actually provides." * Explain why we're removing https://git.github.io/htmldocs/git.html, gitcli, and the user manual, and the data model * Mention the plan to include the tutorial again here once we have one we're happy with Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2242%2Fjvns%2Fupdate-git-v3 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2242/jvns/update-git-v3 Pull-Request: https://github.com/gitgitgadget/git/pull/2242 Range-diff vs v2: 1: 18f373a8f3 ! 1: 6cb4390e53 doc: use `man git` to teach users how to navigate the docs @@ Metadata ## Commit message ## doc: use `man git` to teach users how to navigate the docs - 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. + Rewrite `man git` to give a more realistic view of what the + documentation actually provides. 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. + Remove the direct references to all the guides, for the following + reasons: + + * gittutorial and giteveryday are 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 goal is to mention the tutorial again when when we have a tutorial + we're happy with. + * gitcli is not very useful for users. A lot of it is about scripting + and internal details about the option parser. + * the user manual is outdated. The chapter on "Sharing development with + others" explains how to use `git format-patch` which is not how most + Git users collaborate with git. + * mentioning the data model feels out of place once everything else is + removed 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. + Mention `git help --guides` and `git help --user-interfaces`, + since there are some important guides in there (like `submodules`) that + are hard to discover. Do not mention `git help --developer-interfaces` since it's not relevant to users. + Remove https://git.github.io/htmldocs/git.html since it points to the + `master` version of the documentation. https://git-scm.com/ has the + version from the latest release which is more likely to be useful. + Signed-off-by: Julia Evans ## Documentation/git.adoc ## Documentation/git.adoc | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/Documentation/git.adoc b/Documentation/git.adoc index 6f0075f918..6dfb829a7e 100644 --- a/Documentation/git.adoc +++ b/Documentation/git.adoc @@ -22,21 +22,21 @@ Git is a fast, scalable, distributed revision control system with an unusually rich command set that provides both high-level operations and full access to internals. -See linkgit:gittutorial[7] to get started, then see -linkgit:giteveryday[7] for a useful minimum set of -commands. The link:user-manual.html[Git User's Manual] has a more -in-depth introduction. See linkgit:gitdatamodel[7] if you want to -learn about the data model and important terminology. +There are two ways to get help with any Git subcommand (replace "push" +with the command you want help with): -After you mastered the basic concepts, you can come back to this -page to learn what commands Git offers. You can learn more about -individual Git commands with "git help command". linkgit:gitcli[7] -manual page gives you an overview of the command-line command syntax. +- `git push -h` for a short help +- `git push --help` or `git help push` for the full documentation -A formatted and hyperlinked copy of the latest Git documentation -can be viewed at https://git.github.io/htmldocs/git.html -or https://git-scm.com/docs. +There are also guides explaining Git's concepts and more: +- `git help` shows the most frequently used Git subcommands +- `git help --guides` lists Git's concept guides +- `git help --user-interfaces` lists guides for various + special files you can use to change Git's behaviour + +You can view an HTML version of the documentation with `git help --web` +(for example `git help --web push`) or at https://git-scm.com/docs. OPTIONS ------- base-commit: 0f8e75abebff0877cae681a3d5ff31ac47f54220 -- gitgitgadget