[PATCH v3] doc: use `man git` to teach users how to navigate the docs
- From
Julia Evans via GitGitGadget <gitgitgadget@gmail.com>
- Date
- Oct 16, 2026, 19:15 UTC
- Message-ID
- <pull.2242.v3.git.1792178103727.gitgitgadget@gmail.com>
- In-Reply-To
- <pull.2242.git.1790627574093.gitgitgadget@gmail.com>
From: Julia Evans <julia@jvns.ca>
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 <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.
* 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 withPublished-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 <julia@jvns.ca>
## 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