{"thread":{"id":"66412","subject":"[PATCH] [doc] Use `man git` to teach users how to navigate the docs","startedAt":"2026-09-28T20:32:56Z","lastAt":"2026-09-29T21:20:42Z","messageCount":7,"participants":["Julia Evans via GitGitGadget","Ben Knoble","Junio C Hamano","Julia Evans"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"553521","messageId":"pull.2242.git.1790627574093.gitgitgadget@gmail.com","threadId":"66412","inReplyTo":null,"subject":"[PATCH] [doc] Use `man git` to teach users how to navigate the docs","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-09-28T20:32:54Z","receivedAt":"2026-09-28T20:32:56Z","isPatch":true,"body":"From: Julia Evans \n\nMany existing users of Git don't know how Git's documentation is\nstructured, and a lot of folks have expressed frustration that `man git`\ndoesn't make it easy to find out how to get help with using Git.\n\nExplain how Git's help system works in `man git`\n(`git push -h` gives a short help, `git push --help` is the full docs),\nsince it's a slightly unusual approach.\n\nRemove the references to gittutorial and giteveryday since they're\nunlikely to help new users learn Git. Currently they feel very\naspirational (it would be nice to have a tutorial and a guide to\neveryday Git commands!), but we should give users a realistic view of\nwhat the documentation actually provides.\n\nMention `git help` instead of `giteveryday` for now, which does a better\njob of giving an overview of everyday commands.\n\nAlso mention `git help --guides` and `git help --user-interfaces`,\nsince those parts of the documentation are useful and hard to discover.\n\nDo not mention `git help --developer-interfaces` since it's not relevant\nto users.\n\nSigned-off-by: Julia Evans \n---\n [doc] Use man git to teach users how to navigate the docs\n \n Here's a list of things I'm still considering in the hopes that it'll\n help with the discussion:\n \n I'm not totally satisfied with the description of git help\n --user-interfaces here. It might be clearer to give examples of topics\n those guides cover, like \"hooks, .gitignore, and more\".\n \n I thought about mentioning git help push and/or man git-push, but (from\n a Mastodon survey I did) git push --help is the one users are most\n familiar with, it's most similar to how other Unix tools work, and it\n makes the description really clear and concise (-h for short help,\n --help for long help).\n \n We just added gitdatamodel here but I took it out because I couldn't\n find a place to put it in the new explanation that felt natural. I do\n think that discoverability of that guide is still an issue and it's\n something that's on my mind. One option in the future to make the guides\n more discoverable would be to feature them more often in Git's advice,\n for example see 'git help mergeconflicts' for a guide to handling merge\n conflicts. Users definitely do read the advice.\n \n Related to the discussion here\n https://lore.kernel.org/git/7004c3b1-2100-4a90-9815-2a679ceb25b2@app.fastmail.com/T/#mf600063180d6239916e3fa6e9d33da86969547ec\n \n ccing Kristoffer who edited this most recently.\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-2242%2Fjvns%2Fupdate-git-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2242/jvns/update-git-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/2242\n\n Documentation/git.adoc | 22 ++++++++++++----------\n 1 file changed, 12 insertions(+), 10 deletions(-)\n\ndiff --git a/Documentation/git.adoc b/Documentation/git.adoc\nindex 6f0075f918..3e886d3e1d 100644\n--- a/Documentation/git.adoc\n+++ b/Documentation/git.adoc\n@@ -22,16 +22,18 @@ Git is a fast, scalable, distributed revision control system with an\n unusually rich command set that provides both high-level operations\n and full access to internals.\n \n-See linkgit:gittutorial[7] to get started, then see\n-linkgit:giteveryday[7] for a useful minimum set of\n-commands. The link:user-manual.html[Git User's Manual] has a more\n-in-depth introduction. See linkgit:gitdatamodel[7] if you want to\n-learn about the data model and important terminology.\n-\n-After you mastered the basic concepts, you can come back to this\n-page to learn what commands Git offers. You can learn more about\n-individual Git commands with \"git help command\". linkgit:gitcli[7]\n-manual page gives you an overview of the command-line command syntax.\n+There are two ways to get help on any Git subcommand (replace \"push\"\n+with the command you want help with):\n+\n+- `git push -h` for a short help\n+- `git push --help` for the full documentation\n+\n+There are also guides explaining Git's concepts and more:\n+\n+- `git help` shows the most frequently used Git subcommands\n+- `git help --guides` lists Git's concept guides\n+- `git help --user-interfaces` lists guides for various\n+ special files you can use to change Git's behaviour\n \n A formatted and hyperlinked copy of the latest Git documentation\n can be viewed at https://git.github.io/htmldocs/git.html\n\nbase-commit: 0f8e75abebff0877cae681a3d5ff31ac47f54220\n-- \ngitgitgadget\n"},{"id":"553528","messageId":"CCB1855E-759F-4741-BE49-23FC6DD402A6@gmail.com","threadId":"66412","inReplyTo":"pull.2242.git.1790627574093.gitgitgadget@gmail.com","subject":"Re: [PATCH] [doc] Use `man git` to teach users how to navigate the docs","fromName":"Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2026-09-28T21:02:24Z","receivedAt":"2026-09-28T21:02:36Z","isPatch":true,"body":"\n> Le 28 sept. 2026 à 16:33, Julia Evans via GitGitGadget a écrit :\n> \n> From: Julia Evans \n> \n> Many existing users of Git don't know how Git's documentation is\n> structured, and a lot of folks have expressed frustration that `man git`\n> doesn't make it easy to find out how to get help with using Git.\n> \n> Explain how Git's help system works in `man git`\n> (`git push -h` gives a short help, `git push --help` is the full docs),\n> since it's a slightly unusual approach.\n\n[snip]\n\n> Mention `git help` instead of `giteveryday` for now, which does a better\n> job of giving an overview of everyday commands.\n\n[snip]\n\n> I thought about mentioning git help push and/or man git-push, but (from\n> a Mastodon survey I did) git push --help is the one users are most\n> familiar with, it's most similar to how other Unix tools work, and it\n> makes the description really clear and concise (-h for short help,\n> --help for long help).\n\nI appreciate the concision. I think “git help cmd” is quite a bit more\nuseful than “git cmd --help” because the former supports\naliases, HTML formats, and various other documents.\nI don’t know how to fit that in with what you already proposed,\nthough; I doubt that mentioning bare “git help” will push anyone towards\nits manual to discover “git help cmd”, although the bottom of the help\noutput mentions it as a possibility. \n\n[Unrelated]\nOne thing I think Git is really missing is easy access to the stuff\nin “git --html-path”. I have a custom script for that, but AFAICT even\n“git help” in web mode can’t open all of it. "},{"id":"553536","messageId":"xmqqo6dgkead.fsf@gitster.g","threadId":"66412","inReplyTo":"CCB1855E-759F-4741-BE49-23FC6DD402A6@gmail.com","subject":"Re: [PATCH] [doc] Use `man git` to teach users how to navigate the docs","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-09-29T02:00:10Z","receivedAt":"2026-09-29T02:00:13Z","isPatch":true,"body":"Ben Knoble writes:\n\n>> Mention `git help` instead of `giteveryday` for now, which does a better\n>> job of giving an overview of everyday commands.\n>\n> [snip]\n>\n>> I thought about mentioning git help push and/or man git-push, but (from\n>> a Mastodon survey I did) git push --help is the one users are most\n>> familiar with, it's most similar to how other Unix tools work, and it\n>> makes the description really clear and concise (-h for short help,\n>> --help for long help).\n> I appreciate the concision.\n\nThe survey result that says the users are more familiar with \"git\ncmd --help\" merely tells us that they are not taking full advantage\nof what they are offered ;-).\n\n> I think “git help cmd” is quite a bit more\n> useful than “git cmd --help” because the former supports\n> aliases, HTML formats, and various other documents.\n\nI agree that \"git help cmd/concept/guide\" is more useful for all\nthese reasons, with \"git help help\".\n"},{"id":"553589","messageId":"064ec9c5-d539-4d21-96a7-6ad0ead5a061@app.fastmail.com","threadId":"66412","inReplyTo":"xmqqo6dgkead.fsf@gitster.g","subject":"Re: [PATCH] [doc] Use `man git` to teach users how to navigate the docs","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-09-29T11:29:24Z","receivedAt":"2026-09-29T11:29:45Z","isPatch":true,"body":"> The survey result that says the users are more familiar with \"git\n> cmd --help\" merely tells us that they are not taking full advantage\n> of what they are offered ;-).\n\n>> I think “git help cmd” is quite a bit more\n>> useful than “git cmd --help” because the former supports\n>> aliases, HTML formats, and various other documents.\n\nViewing the HTML docs with `git help` does seem very useful, especially for\nfolks who aren't as comfortable in the terminal. I had no idea you could do\nthat.\n\nPerhaps we could mention `git help` like this:\n\n> `git push --help` or `git help push` for the full documentation\n\nand then advertise the superior features of `git help` like this\n(in the last sentence of the DESCRIPTION).\n\n> You can view an HTML version of the Git documentation at\n> https://git-scm.com/docs, or on your computer with `git help`,\n> for example `git help push --web`.\n"},{"id":"553635","messageId":"xmqqfqyrg7j7.fsf@gitster.g","threadId":"66412","inReplyTo":"064ec9c5-d539-4d21-96a7-6ad0ead5a061@app.fastmail.com","subject":"Re: [PATCH] [doc] Use `man git` to teach users how to navigate the docs","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-09-29T19:51:56Z","receivedAt":"2026-09-29T19:51:59Z","isPatch":true,"body":"\"Julia Evans\" writes:\n\n> Perhaps we could mention `git help` like this:\n>\n>> `git push --help` or `git help push` for the full documentation\n>\n> and then advertise the superior features of `git help` like this\n> (in the last sentence of the DESCRIPTION).\n\nAmusingly\n\n$ git help tutorial\n\nbegins with \"man git-log\" and \"git help log\". The first one is so\nold fashioned ;-) Perhaps a more modern version should be given at\nthe very first part of the description section of\n\n$ git help git\n\n>> You can view an HTML version of the Git documentation at\n>> https://git-scm.com/docs, or on your computer with `git help`,\n>> for example `git help push --web`.\n\nPlease write it as \"git help --web push\".\n\nThe command line parser may be lenient at times, but we do not\nguarantee it. Please stick to published \"git help cli\" style in\nyour insturction materials.\n"},{"id":"553643","messageId":"9a628695-3c82-4cbb-96ba-8bd9c1c7570f@app.fastmail.com","threadId":"66412","inReplyTo":"xmqqfqyrg7j7.fsf@gitster.g","subject":"Re: [PATCH] [doc] Use `man git` to teach users how to navigate the docs","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-09-29T21:00:18Z","receivedAt":"2026-09-29T21:00:40Z","isPatch":true,"body":"On Tue, Sep 29, 2026, at 3:51 PM, Junio C Hamano wrote:\n> \"Julia Evans\" writes:\n>\n>> Perhaps we could mention `git help` like this:\n>>\n>>> `git push --help` or `git help push` for the full documentation\n>>\n>> and then advertise the superior features of `git help` like this\n>> (in the last sentence of the DESCRIPTION).\n>\n> Amusingly\n>\n> $ git help tutorial\n>\n> begins with \"man git-log\" and \"git help log\". The first one is so\n> old fashioned ;-) \n\nI still only use `man git-log` actually :)\n\n> Perhaps a more modern version should be given at\n> the very first part of the description section of\n>\n> $ git help git\n> \n\nWill submit a v2 with the wording I suggested above\n(since I think that's \"a more modern version\" of what\n`git help tutorial` says)\n\n>>> You can view an HTML version of the Git documentation at\n>>> https://git-scm.com/docs, or on your computer with `git help`,\n>>> for example `git help push --web`.\n>\n> Please write it as \"git help --web push\".\n\nWill do.\n\n> The command line parser may be lenient at times, but we do not\n> guarantee it. Please stick to published \"git help cli\" style in\n> your insturction materials.\n\nI tried to read `git help cli`, got extremely confused, and gave up so I'm\nnot sure what that style is but I'm always happy to be corrected if there's\na different preferred style :)\n\nI do always test Git commands to make sure they work.\n"},{"id":"553647","messageId":"xmqqqzibeouv.fsf@gitster.g","threadId":"66412","inReplyTo":"9a628695-3c82-4cbb-96ba-8bd9c1c7570f@app.fastmail.com","subject":"Re: [PATCH] [doc] Use `man git` to teach users how to navigate the docs","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-09-29T21:20:40Z","receivedAt":"2026-09-29T21:20:42Z","isPatch":true,"body":"\"Julia Evans\" writes:\n\n> I tried to read `git help cli`, got extremely confused, and gave up so I'm\n> not sure what that style is but I'm always happy to be corrected if there's\n> a different preferred style :)\n\n\"Options come first and then args.\" appears very early.\n\n\n"}]}