From 6cb4390e53823cbef18afa9972d8131774032e85 Mon Sep 17 00:00:00 2001 From: Julia Evans Date: Mon, 28 Sep 2026 09:42:58 -0400 Subject: [PATCH] doc: use `man git` to teach users how to navigate the docs 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 --- Documentation/git.adoc | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/Documentation/git.adoc b/Documentation/git.adoc index 6f0075f9188774..6dfb829a7e06cd 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 -------