{"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-10-16T21:12:38Z","messageCount":20,"participants":["Julia Evans via GitGitGadget","Ben Knoble","Junio C Hamano","Julia Evans","D. Ben Knoble","Kristoffer Haugsbakk"],"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,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\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 <julia@jvns.ca>\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,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"\n> Le 28 sept. 2026 à 16:33, Julia Evans via GitGitGadget <gitgitgadget@gmail.com> a écrit :\n> \n> ﻿From: Julia Evans <julia@jvns.ca>\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,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ben Knoble <ben.knoble@gmail.com> 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,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"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,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans\" <julia@jvns.ca> 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,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"On Tue, Sep 29, 2026, at 3:51 PM, Junio C Hamano wrote:\n> \"Julia Evans\" <julia@jvns.ca> 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,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans\" <julia@jvns.ca> 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"},{"id":"554329","messageId":"pull.2242.v2.git.1791317163584.gitgitgadget@gmail.com","threadId":"66412","inReplyTo":"pull.2242.git.1790627574093.gitgitgadget@gmail.com","subject":"[PATCH v2] doc: use `man git` to teach users how to navigate the docs","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-06T20:06:03Z","receivedAt":"2026-10-06T20:06:03Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\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 <julia@jvns.ca>\n---\n    [doc] Use man git to teach users how to navigate the docs\n    \n    Changes in v2:\n    \n     * mention the git help push form too\n     * mention you can get HTML docs with git help --web push at the end to\n       advertise git help's great features, and remove\n       https://git.github.io/htmldocs/git.html since\n       https://git-scm.com/docs has a nicer view and 3 different options is\n       a lot.\n     * some minor wording changes\n     * fix commit message style (doc: not [doc])\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-2242%2Fjvns%2Fupdate-git-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2242/jvns/update-git-v2\nPull-Request: https://github.com/gitgitgadget/git/pull/2242\n\nRange-diff vs v1:\n\n 1:  5da3881760 ! 1:  18f373a8f3 [doc] Use `man git` to teach users how to navigate the docs\n     @@ Metadata\n      Author: Julia Evans <julia@jvns.ca>\n      \n       ## Commit message ##\n     -    [doc] Use `man git` to teach users how to navigate the docs\n     +    doc: use `man git` to teach users how to navigate the docs\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     @@ Documentation/git.adoc: Git is a fast, scalable, distributed revision control sy\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     ++There are two ways to get help with any Git subcommand (replace \"push\"\n     ++with the command you want help with):\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     ++- `git push --help` or `git help push` for the full documentation\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     +-or https://git-scm.com/docs.\n      +There are also guides explaining Git's concepts and more:\n     -+\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     ++You can view an HTML version of the documentation with `git help --web`\n     ++(for example `git help --web push`) or at https://git-scm.com/docs.\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     + OPTIONS\n     + -------\n\n\n Documentation/git.adoc | 24 ++++++++++++------------\n 1 file changed, 12 insertions(+), 12 deletions(-)\n\ndiff --git a/Documentation/git.adoc b/Documentation/git.adoc\nindex 6f0075f918..6dfb829a7e 100644\n--- a/Documentation/git.adoc\n+++ b/Documentation/git.adoc\n@@ -22,21 +22,21 @@ 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+There are two ways to get help with any Git subcommand (replace \"push\"\n+with the command you want help with):\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+- `git push -h` for a short help\n+- `git push --help` or `git help push` for the full documentation\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-or https://git-scm.com/docs.\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+You can view an HTML version of the documentation with `git help --web`\n+(for example `git help --web push`) or at https://git-scm.com/docs.\n \n OPTIONS\n -------\n\nbase-commit: 0f8e75abebff0877cae681a3d5ff31ac47f54220\n-- \ngitgitgadget\n\n"},{"id":"554332","messageId":"CALnO6CCwCLEBzJiRaJp3h9b=6uF5x341NhXd+B7UfatsQmr2TA@mail.gmail.com","threadId":"66412","inReplyTo":"pull.2242.v2.git.1791317163584.gitgitgadget@gmail.com","subject":"Re: [PATCH v2] doc: use `man git` to teach users how to navigate the docs","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2026-10-06T20:23:42Z","receivedAt":"2026-10-06T20:23:42Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Tue, Oct 6, 2026 at 4:06 PM Julia Evans via GitGitGadget\n<gitgitgadget@gmail.com> wrote:\n>     Changes in v2:\n>\n>      * mention the git help push form too\n>      * mention you can get HTML docs with git help --web push at the end to\n>        advertise git help's great features, and remove\n>        https://git.github.io/htmldocs/git.html since\n>        https://git-scm.com/docs has a nicer view and 3 different options is\n>        a lot.\n>      * some minor wording changes\n>      * fix commit message style (doc: not [doc])\n\nThanks, personally I'm happy with this version.\n\n"},{"id":"554353","messageId":"ea29fe74-7f76-440c-9597-fdbc173be90f@app.fastmail.com","threadId":"66412","inReplyTo":"pull.2242.v2.git.1791317163584.gitgitgadget@gmail.com","subject":"Re: [PATCH v2] doc: use `man git` to teach users how to navigate the docs","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-10-07T06:06:20Z","receivedAt":"2026-10-07T06:06:20Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Tue, Oct 6, 2026, at 22:06, Julia Evans via GitGitGadget wrote:\n> From: Julia Evans <julia@jvns.ca>\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\nYeah I can imagine.\n\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\nI recall only relatively recently learning that `-h` is not just a\nshorter way to type `--help`.\n\n> Remove the references to gittutorial and giteveryday since they're\n> unlikely to help new users learn Git. Currently they feel very\n> aspirational (it would be nice to have a tutorial and a guide to\n> everyday Git commands!), but we should give users a realistic view of\n> what the documentation actually provides.\n\nRight, aspirations are not good enough when it comes to the bread and\nbutter everyday howtos.\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> Also mention `git help --guides` and `git help --user-interfaces`,\n> since those parts of the documentation are useful and hard to discover.\n>\n> Do not mention `git help --developer-interfaces` since it's not relevant\n> to users.\n\nOkay, so now we don’t have to list out every guide that might be of\ninterest. That’s cool.\n\nI see that this would conflict with my topic\nkh/doc-gitbreaking-changes7.[1] Just would since my topic hasn’t\nbeen integrated yet (RFC). I use the old style of mentioning the\nnew gitbreaking-changes(7) (“see <here> for ...”. I will remove\nthat change in order to stay consistent with this topic.\n\n🔗 1: https://lore.kernel.org/git/CV_gitbrchanges7_please.d1c@m5gid.xyz/\n\n>\n> Signed-off-by: Julia Evans <julia@jvns.ca>\n> ---\n>     [doc] Use man git to teach users how to navigate the docs\n>\n>     Changes in v2:\n>\n>      * mention the git help push form too\n>      * mention you can get HTML docs with git help --web push at the end to\n>        advertise git help's great features, and remove\n>        https://git.github.io/htmldocs/git.html since\n>        https://git-scm.com/docs has a nicer view and 3 different options is\n>        a lot.\n\nNitpick: Okay, but with the current commit message I don’t really\nunderstand why the git.github.io link is gone. I have to guess that it\nis an effective duplicate of git-scm or something since git-scm does\nremain after this change.\n\n>      * some minor wording changes\n>      * fix commit message style (doc: not [doc])\n>\n>[snip]\n\n"},{"id":"554365","messageId":"99bc9624-47a5-469d-bcae-8daa9b01581a@app.fastmail.com","threadId":"66412","inReplyTo":"ea29fe74-7f76-440c-9597-fdbc173be90f@app.fastmail.com","subject":"Re: [PATCH v2] doc: use `man git` to teach users how to navigate the docs","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-10-07T12:13:22Z","receivedAt":"2026-10-07T12:13:22Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"> I recall only relatively recently learning that `-h` is not just a\n> shorter way to type `--help`.\n\nI just learned that recently too!\n\n> Okay, so now we don’t have to list out every guide that might be of\n> interest. That’s cool.\n>\n> I see that this would conflict with my topic\n> kh/doc-gitbreaking-changes7.[1] Just would since my topic hasn’t\n> been integrated yet (RFC). I use the old style of mentioning the\n> new gitbreaking-changes(7) (“see <here> for ...”. I will remove\n> that change in order to stay consistent with this topic.\n\n> 🔗 1: https://lore.kernel.org/git/CV_gitbrchanges7_please.d1c@m5gid.xyz/\n\nThat makes sense to me, thanks! I saw that topic and funnily I've\nbeen working on moving most of the content of `gitworkflows`\nin the other direction (from the user facing manual pages to\nthe internal-only docs).\n\n>>\n>>      * mention the git help push form too\n>>      * mention you can get HTML docs with git help --web push at the end to\n>>        advertise git help's great features, and remove\n>>        https://git.github.io/htmldocs/git.html since\n>>        https://git-scm.com/docs has a nicer view and 3 different options is\n>>        a lot.\n>\n> Nitpick: Okay, but with the current commit message I don’t really\n> understand why the git.github.io link is gone. I have to guess that it\n> is an effective duplicate of git-scm or something since git-scm does\n> remain after this change.\n\nYep! It has the same content as https://git-scm.com as far as I know,\nbut without a lot of the nice features (a table of contents, an overview\nof all the documentation, search, etc).\n\n"},{"id":"554373","messageId":"xmqqv77dbp1e.fsf@gitster.g","threadId":"66412","inReplyTo":"99bc9624-47a5-469d-bcae-8daa9b01581a@app.fastmail.com","subject":"Re: [PATCH v2] doc: use `man git` to teach users how to navigate the docs","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-07T13:47:41Z","receivedAt":"2026-10-07T13:47:41Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans\" <julia@jvns.ca> writes:\n\n>> Nitpick: Okay, but with the current commit message I don’t really\n>> understand why the git.github.io link is gone. I have to guess that it\n>> is an effective duplicate of git-scm or something since git-scm does\n>> remain after this change.\n>\n> Yep! It has the same content as https://git-scm.com as far as I know,\n\nCorrect.  That is direct rendition of what we ship.  git-scm.com has\nsome fruff around it (grouping and other meaningful usability\nimprovements besides coloring and fonts), but I do not know how\nup-to-date the contents or the grouping is and how they are kept\nsynchronized to the originals at git.github.io/htmldocs/git.html.\n\n"},{"id":"554379","messageId":"2ef42736-8879-4399-bbe9-3ba09522373d@app.fastmail.com","threadId":"66412","inReplyTo":"xmqqv77dbp1e.fsf@gitster.g","subject":"Re: [PATCH v2] doc: use `man git` to teach users how to navigate the docs","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-10-07T13:57:15Z","receivedAt":"2026-10-07T13:57:15Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"On Wed, Oct 7, 2026, at 9:47 AM, Junio C Hamano wrote:\n> \"Julia Evans\" <julia@jvns.ca> writes:\n>\n>>> Nitpick: Okay, but with the current commit message I don’t really\n>>> understand why the git.github.io link is gone. I have to guess that it\n>>> is an effective duplicate of git-scm or something since git-scm does\n>>> remain after this change.\n>>\n>> Yep! It has the same content as https://git-scm.com as far as I know,\n>\n> Correct.  That is direct rendition of what we ship.  git-scm.com has\n> some fruff around it (grouping and other meaningful usability\n> improvements besides coloring and fonts), but I do not know how\n> up-to-date the contents or the grouping is and how they are kept\n> synchronized to the originals at git.github.io/htmldocs/git.html.\n\nYeah, the grouping at https://git-scm.com/docs is a bit out of date.\nI'm not sure how to fix it in a satisfactory way.\n\n"},{"id":"554396","messageId":"xmqqv77d8ld9.fsf@gitster.g","threadId":"66412","inReplyTo":"2ef42736-8879-4399-bbe9-3ba09522373d@app.fastmail.com","subject":"Re: [PATCH v2] doc: use `man git` to teach users how to navigate the docs","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-07T17:35:14Z","receivedAt":"2026-10-07T17:35:14Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans\" <julia@jvns.ca> writes:\n\n> On Wed, Oct 7, 2026, at 9:47 AM, Junio C Hamano wrote:\n>> \"Julia Evans\" <julia@jvns.ca> writes:\n>>\n>>>> Nitpick: Okay, but with the current commit message I don’t really\n>>>> understand why the git.github.io link is gone. I have to guess that it\n>>>> is an effective duplicate of git-scm or something since git-scm does\n>>>> remain after this change.\n>>>\n>>> Yep! It has the same content as https://git-scm.com as far as I know,\n>>\n>> Correct.  That is direct rendition of what we ship.  git-scm.com has\n>> some fruff around it (grouping and other meaningful usability\n>> improvements besides coloring and fonts), but I do not know how\n>> up-to-date the contents or the grouping is and how they are kept\n>> synchronized to the originals at git.github.io/htmldocs/git.html.\n>\n> Yeah, the grouping at https://git-scm.com/docs is a bit out of date.\n> I'm not sure how to fix it in a satisfactory way.\n\nAnother thing is I do not know how fresh the contents are.  I know\nthe one you are removing the reference to keeps up with the tip of\n'main/master' so it may describe yet-to-be-released new features and\nbehaviours.  I am assuming that the one at git-scm.com is updated to\nthe latest released version, which may be more useful for general\naudience.\n\n"},{"id":"554412","messageId":"xmqqfqyh728j.fsf@gitster.g","threadId":"66412","inReplyTo":"pull.2242.v2.git.1791317163584.gitgitgadget@gmail.com","subject":"Re: [PATCH v2] doc: use `man git` to teach users how to navigate the docs","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-07T19:13:48Z","receivedAt":"2026-10-07T19:13:48Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> From: Julia Evans <julia@jvns.ca>\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> Remove the references to gittutorial and giteveryday since they're\n> unlikely to help new users learn Git. Currently they feel very\n> aspirational (it would be nice to have a tutorial and a guide to\n> everyday Git commands!), but we should give users a realistic view of\n> what the documentation actually provides.\n\nThe text mentions removing 'tutorial' and 'everyday', but does\nnot explain why we no longer reference 'user-manual', 'datamodel',\nand 'cli'.  The third iteration should justify this.  At least,\nI recall that adding a reference to 'cli' early in the document was\na deliberate decision, and we should explain why it is no longer\nrelevant.  It would not be surprising if it has become obsolete\nover the last decade, but we still need to spell out why it is no\nlonger appropriate to reference here.\n\nI wholeheartedly agree with dropping 'everyday', which was written\nbefore Git 1.0 back when we did not have much introductory material.\nIt was not aspirational, and while its choice of twenty commands\nsuited the workflows of the time, it outlived its usefulness long\nago.\n\nThanks.\n\n"},{"id":"554415","messageId":"3a665230-b221-410b-9a58-96c01210aea0@app.fastmail.com","threadId":"66412","inReplyTo":"xmqqfqyh728j.fsf@gitster.g","subject":"Re: [PATCH v2] doc: use `man git` to teach users how to navigate the docs","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-10-07T19:29:51Z","receivedAt":"2026-10-07T19:29:51Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\n\nOn Wed, Oct 7, 2026, at 3:13 PM, Junio C Hamano wrote:\n> \"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n>\n>> From: Julia Evans <julia@jvns.ca>\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>> Remove the references to gittutorial and giteveryday since they're\n>> unlikely to help new users learn Git. Currently they feel very\n>> aspirational (it would be nice to have a tutorial and a guide to\n>> everyday Git commands!), but we should give users a realistic view of\n>> what the documentation actually provides.\n>\n> The text mentions removing 'tutorial' and 'everyday', but does\n> not explain why we no longer reference 'user-manual', 'datamodel',\n> and 'cli'.  The third iteration should justify this.  At least,\n> I recall that adding a reference to 'cli' early in the document was\n> a deliberate decision, and we should explain why it is no longer\n> relevant.  It would not be surprising if it has become obsolete\n> over the last decade, but we still need to spell out why it is no\n> longer appropriate to reference here.\n\nThanks, can do. Here's my thought process:\n\n- Removed 'cli' because (from my perspective as a user) it seems like\n  something that's written for Git developers and not users, like\n  with \"Commands that support the enhanced option parser\",\n  how is a user supposed to know which commands support\n  the enhanced parser? I think it makes sense as a guide to\n  scripting Git but not for interactive use. Some of the bits on `diff`\n  feel like they might belong in the `git diff` man page, not sure.\n- Removed \"user-manual\" because it's outdated. The chapter on\n  \"Sharing development with others\" explains how to use\n  `git format-patch` which is not how most people collaborate with\n  git.\n- Once all the others were removed it seemed a bit out of place\n  to mention `gitdatamodel`.\n\n"},{"id":"554419","messageId":"xmqq4iex6zox.fsf@gitster.g","threadId":"66412","inReplyTo":"3a665230-b221-410b-9a58-96c01210aea0@app.fastmail.com","subject":"Re: [PATCH v2] doc: use `man git` to teach users how to navigate the docs","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-07T20:08:46Z","receivedAt":"2026-10-07T20:08:46Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans\" <julia@jvns.ca> writes:\n\n> - Removed 'cli' because (from my perspective as a user) it seems like\n>   something that's written for Git developers and not users, like\n>   with \"Commands that support the enhanced option parser\",\n>   how is a user supposed to know which commands support\n>   the enhanced parser? I think it makes sense as a guide to\n>   scripting Git but not for interactive use. Some of the bits on `diff`\n>   feel like they might belong in the `git diff` man page, not sure.\n\nPerhaps updating cli so that it does not give a false smell of\ngetting written for a wrong audiences is a more productive\ndirection, though?  I do not think there is any other document that\ntells users the simple \"options first and then revs and then paths\"\nrule, for example.\n\n> - Removed \"user-manual\" because it's outdated. The chapter on\n>   \"Sharing development with others\" explains how to use\n>   `git format-patch` which is not how most people collaborate with\n>   git.\n\nYes, the was written in a very early days, and by a person who\nworked in the Linux kernel circle.  I do not know about \"not how\nmost people\" part, but I would agree that \"many users do not use\"\nwould be a fair description of the modern world order.\n\n> - Once all the others were removed it seemed a bit out of place\n>   to mention `gitdatamodel`.\n\nNot limited to the issue of where `gitdatamodel` should fit, I think\nwe probably should explain the goal of these change at a bit higher\nlevel.  The original intention to refer to these things very early\nin the documentation was to direct those readers who are not ready\nto go into the list of git subcommands to those \"introductory\" text\nand concepts guides, and encourage them to come back once they are\nequipped with basic concepts and workflows.  I do not know if that\ndesign actually helped or was harmful for the real-world learners,\nbut if we are shuffling the material we present early by removing\nsome and introducing others, we should explain what our overall\ndesign of the presentation order is, for example.\n\nThanks.\n\n"},{"id":"554507","messageId":"b121896e-03d9-498f-9fe3-6688c4ff4034@app.fastmail.com","threadId":"66412","inReplyTo":"xmqq4iex6zox.fsf@gitster.g","subject":"Re: [PATCH v2] doc: use `man git` to teach users how to navigate the docs","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-10-08T15:09:10Z","receivedAt":"2026-10-08T15:09:10Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"\n\nOn Wed, Oct 7, 2026, at 4:08 PM, Junio C Hamano wrote:\n> \"Julia Evans\" <julia@jvns.ca> writes:\n>\n>> - Removed 'cli' because (from my perspective as a user) it seems like\n>>   something that's written for Git developers and not users, like\n>>   with \"Commands that support the enhanced option parser\",\n>>   how is a user supposed to know which commands support\n>>   the enhanced parser? I think it makes sense as a guide to\n>>   scripting Git but not for interactive use. Some of the bits on `diff`\n>>   feel like they might belong in the `git diff` man page, not sure.\n>\n> Perhaps updating cli so that it does not give a false smell of\n> getting written for a wrong audiences is a more productive\n> direction, though?  I do not think there is any other document that\n> tells users the simple \"options first and then revs and then paths\"\n> rule, for example.\n\nIf at some time in the future we update `gitcli` I think it could make\nsense to put it back!\n\n>> - Removed \"user-manual\" because it's outdated. The chapter on\n>>   \"Sharing development with others\" explains how to use\n>>   `git format-patch` which is not how most people collaborate with\n>>   git.\n>\n> Yes, the was written in a very early days, and by a person who\n> worked in the Linux kernel circle.  I do not know about \"not how\n> most people\" part, but I would agree that \"many users do not use\"\n> would be a fair description of the modern world order.\n>\n>> - Once all the others were removed it seemed a bit out of place\n>>   to mention `gitdatamodel`.\n>\n> Not limited to the issue of where `gitdatamodel` should fit, I think\n> we probably should explain the goal of these change at a bit higher\n> level.  The original intention to refer to these things very early\n> in the documentation was to direct those readers who are not ready\n> to go into the list of git subcommands to those \"introductory\" text\n> and concepts guides, and encourage them to come back once they are\n> equipped with basic concepts and workflows.  I do not know if that\n> design actually helped or was harmful for the real-world learners,\n> but if we are shuffling the material we present early by removing\n> some and introducing others, we should explain what our overall\n> design of the presentation order is, for example.\n\nAs we rebuild some of this intro material we can bring it back in.\nFor example once we have a tutorial we're happy with I think it would\nmake sense to suggest that folks read it to learn Git.\n\nIf you're asking what I intend the overall design of the presentation order\nto be, the goal is to bring the Git docs towards more of an\n\"every page is page one\" design https://everypageispageone.com/the-book/ \nwhere on most pages we don't expect or require the reader to have read\nany of the other documentation. So for the the most part there would be no\n\"presentation order\". We'd instead provide links to more context for people\nwho are interested. This increased focus on linking is why I sent that patch\nto make the AsciiDoc links work better in the HTML docs.\n\nI think this kind of \"every page is page one\" structure would be both easier\nto maintain and better matches what users want than a book like the user\nmanual, so it's a win/win.\n\nIn some cases (like the tutorial) I think it would make sense to have an order,\nlike \"learn `git commit` before learning branching\", but I think we should keep\nthose sequences very short. Ideally we would be able to get feedback from folks\nlearning Git from the tutorial to find out they would like to learn next.\n\n"},{"id":"555270","messageId":"pull.2242.v3.git.1792178103727.gitgitgadget@gmail.com","threadId":"66412","inReplyTo":"pull.2242.git.1790627574093.gitgitgadget@gmail.com","subject":"[PATCH v3] doc: use `man git` to teach users how to navigate the docs","fromName":"Julia Evans via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-10-16T19:15:03Z","receivedAt":"2026-10-16T19:15:03Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"From: Julia Evans <julia@jvns.ca>\n\nRewrite `man git` to give a more realistic view of what the\ndocumentation actually provides.\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 direct references to all the guides, for the following\nreasons:\n\n* gittutorial and giteveryday are unlikely to help new users learn\n  Git. Currently they feel very aspirational (it would be nice to have\n  a tutorial and a guide to everyday Git commands!), but we should give\n  users a realistic view of what the documentation actually provides.\n\n  The goal is to mention the tutorial again when when we have a tutorial\n  we're happy with.\n* gitcli is not very useful for users. A lot of it is about scripting\n  and internal details about the option parser.\n* the user manual is outdated. The chapter on \"Sharing development with\n  others\" explains how to use `git format-patch` which is not how most\n  Git users collaborate with git.\n* mentioning the data model feels out of place once everything else is\n  removed\n\nMention `git help` instead of `giteveryday` for now, which does a better\njob of giving an overview of everyday commands.\n\nMention `git help --guides` and `git help --user-interfaces`,\nsince there are some important guides in there (like `submodules`) that\nare hard to discover.\n\nDo not mention `git help --developer-interfaces` since it's not relevant\nto users.\n\nRemove https://git.github.io/htmldocs/git.html since it points to the\n`master` version of the documentation. https://git-scm.com/ has the\nversion from the latest release which is more likely to be useful.\n\nSigned-off-by: Julia Evans <julia@jvns.ca>\n---\n    [doc] Use man git to teach users how to navigate the docs\n    \n    Changes in v2:\n    \n     * mention the git help push form too\n     * mention you can get HTML docs with git help --web push at the end to\n       advertise git help's great features, and remove\n       https://git.github.io/htmldocs/git.html since\n       https://git-scm.com/docs has a nicer view and 3 different options is\n       a lot.\n     * some minor wording changes\n     * fix commit message style (doc: not [doc])\n    \n    Changes in v3: (just updates to the commit message)\n    \n     * Add a sentence summarizing the goals \"give a more realistic view of\n       what the documentation actually provides.\"\n     * Explain why we're removing https://git.github.io/htmldocs/git.html,\n       gitcli, and the user manual, and the data model\n     * Mention the plan to include the tutorial again here once we have one\n       we're happy with\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-2242%2Fjvns%2Fupdate-git-v3\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2242/jvns/update-git-v3\nPull-Request: https://github.com/gitgitgadget/git/pull/2242\n\nRange-diff vs v2:\n\n 1:  18f373a8f3 ! 1:  6cb4390e53 doc: use `man git` to teach users how to navigate the docs\n     @@ Metadata\n       ## Commit message ##\n          doc: use `man git` to teach users how to navigate the docs\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     +    Rewrite `man git` to give a more realistic view of what the\n     +    documentation actually provides.\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     -    Remove the references to gittutorial and giteveryday since they're\n     -    unlikely to help new users learn Git. Currently they feel very\n     -    aspirational (it would be nice to have a tutorial and a guide to\n     -    everyday Git commands!), but we should give users a realistic view of\n     -    what the documentation actually provides.\n     +    Remove the direct references to all the guides, for the following\n     +    reasons:\n     +\n     +    * gittutorial and giteveryday are unlikely to help new users learn\n     +      Git. Currently they feel very aspirational (it would be nice to have\n     +      a tutorial and a guide to everyday Git commands!), but we should give\n     +      users a realistic view of what the documentation actually provides.\n     +\n     +      The goal is to mention the tutorial again when when we have a tutorial\n     +      we're happy with.\n     +    * gitcli is not very useful for users. A lot of it is about scripting\n     +      and internal details about the option parser.\n     +    * the user manual is outdated. The chapter on \"Sharing development with\n     +      others\" explains how to use `git format-patch` which is not how most\n     +      Git users collaborate with git.\n     +    * mentioning the data model feels out of place once everything else is\n     +      removed\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     -    Also mention `git help --guides` and `git help --user-interfaces`,\n     -    since those parts of the documentation are useful and hard to discover.\n     +    Mention `git help --guides` and `git help --user-interfaces`,\n     +    since there are some important guides in there (like `submodules`) that\n     +    are hard to discover.\n      \n          Do not mention `git help --developer-interfaces` since it's not relevant\n          to users.\n      \n     +    Remove https://git.github.io/htmldocs/git.html since it points to the\n     +    `master` version of the documentation. https://git-scm.com/ has the\n     +    version from the latest release which is more likely to be useful.\n     +\n          Signed-off-by: Julia Evans <julia@jvns.ca>\n      \n       ## Documentation/git.adoc ##\n\n\n Documentation/git.adoc | 24 ++++++++++++------------\n 1 file changed, 12 insertions(+), 12 deletions(-)\n\ndiff --git a/Documentation/git.adoc b/Documentation/git.adoc\nindex 6f0075f918..6dfb829a7e 100644\n--- a/Documentation/git.adoc\n+++ b/Documentation/git.adoc\n@@ -22,21 +22,21 @@ 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+There are two ways to get help with any Git subcommand (replace \"push\"\n+with the command you want help with):\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+- `git push -h` for a short help\n+- `git push --help` or `git help push` for the full documentation\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-or https://git-scm.com/docs.\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+You can view an HTML version of the documentation with `git help --web`\n+(for example `git help --web push`) or at https://git-scm.com/docs.\n \n OPTIONS\n -------\n\nbase-commit: 0f8e75abebff0877cae681a3d5ff31ac47f54220\n-- \ngitgitgadget\n\n"},{"id":"555278","messageId":"xmqqcxt9e4e1.fsf@gitster.g","threadId":"66412","inReplyTo":"pull.2242.v3.git.1792178103727.gitgitgadget@gmail.com","subject":"Re: [PATCH v3] doc: use `man git` to teach users how to navigate the docs","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-10-16T21:12:38Z","receivedAt":"2026-10-16T21:12:38Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Julia Evans via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n>     Changes in v3: (just updates to the commit message)\n>     \n>      * Add a sentence summarizing the goals \"give a more realistic view of\n>        what the documentation actually provides.\"\n>      * Explain why we're removing https://git.github.io/htmldocs/git.html,\n>        gitcli, and the user manual, and the data model\n>      * Mention the plan to include the tutorial again here once we have one\n>        we're happy with\n\nThanks, queued.\n\n"}]}