# [PATCH] Modified the default git help message to be grouped by topic 12 messages from 2008-12-01 to 2008-12-03. Participants: Scott Chacon, Jeff King, Junio C Hamano, James Pickens, Boyd Stephen Smith Jr., Johannes Schindelin, Jakub Narebski. Thread: https://gitlist.dev/t/16542 ## Scott Chacon, 2008-12-01 17:30 Subject: [PATCH] Modified the default git help message to be grouped by topic Message-ID: <20081201173037.GA41967@agadorsparticus> URL: https://gitlist.dev/e/20081201173037.GA41967%40agadorsparticus ``` It's difficult to process 21 commands (which is what is output by default for git when no command is given). I've re-grouped them into 4 groups of 5 or 6 commands each, which I think is clearer and easier for new users to process. As discussed at the GitTogether. Signed-off-by: Scott Chacon --- This makes the 'git' (with no arguments) command look like this: http://gist.github.com/20553 This won't automatically update with the common-commands.txt file, but I think it is easier to parse for the command you may be looking for. builtin-help.c | 42 +++++++++++++++++++++++++++++------------- 1 files changed, 29 insertions(+), 13 deletions(-) diff --git a/builtin-help.c b/builtin-help.c index f076efa..562d5d1 100644 --- a/builtin-help.c +++ b/builtin-help.c @@ -277,19 +277,35 @@ static struct cmdnames main_cmds, other_cmds; void list_common_cmds_help(void) { - int i, longest = 0; - - for (i = 0; i < ARRAY_SIZE(common_cmds); i++) { - if (longest < strlen(common_cmds[i].name)) - longest = strlen(common_cmds[i].name); - } - - puts("The most commonly used git commands are:"); - for (i = 0; i < ARRAY_SIZE(common_cmds); i++) { - printf(" %s ", common_cmds[i].name); - mput_char(' ', longest - strlen(common_cmds[i].name)); - puts(common_cmds[i].help); - } + puts("The most commonly used git commands are:\n\ +\n\ +Basic Commands\n\ + init Create an empty git repository or reinitialize an existing one\n\ + add Add file contents to the staging area\n\ + status Show the working tree and staging area status\n\ + commit Record changes in the staging area to the repository\n\ + rm Remove files from the working tree and from the index\n\ + mv Move or rename a file, a directory, or a symlink\n\ +\n\ +History Commands\n\ + log Show commit log history\n\ + diff Show changes between commits, commit and working tree, etc\n\ + grep Print lines in git tracked files matching a pattern\n\ + reset Reset current HEAD to the specified state\n\ + show Show various types of objects\n\ +\n\ +Branch Commands\n\ + checkout Checkout a branch or paths to the working tree\n\ + branch List, create, or delete branches\n\ + merge Join two or more development histories together\n\ + rebase Apply changes introduced in one branch onto another\n\ + tag Create, list, delete or verify a tag object signed with GPG\n\ +\n\ +Remote Commands\n\ + clone Clone a repository into a new directory\n\ + fetch Download objects and refs from another repository\n\ + pull Fetch from and merge with another repository or a local branch\n\ + push Update remote refs along with associated objects"); } static int is_git_command(const char *s) -- 1.6.0.8.gc9c8 ``` ## Jeff King, 2008-12-01 18:32 Subject: Re: [PATCH] Modified the default git help message to be grouped by topic Message-ID: <20081201183258.GB24443@coredump.intra.peff.net> URL: https://gitlist.dev/e/20081201183258.GB24443%40coredump.intra.peff.net In-Reply-To: <20081201173037.GA41967@agadorsparticus> ``` On Mon, Dec 01, 2008 at 09:30:37AM -0800, Scott Chacon wrote: > It's difficult to process 21 commands (which is what is output > by default for git when no command is given). I've re-grouped > them into 4 groups of 5 or 6 commands each, which I think is > clearer and easier for new users to process. I like it (and I think the categorizations look reasonable, which is something that I recall caused some discussion at the GitTogether). The only downside I see is that we're now >24 lines. > This won't automatically update with the common-commands.txt file, > but I think it is easier to parse for the command you may be looking > for. Personally, I don't see a big problem. This is not a list that should change very frequently, and there is extra information here that would be annoying to encode in the list. But since the "common" flag in command-list.txt and the common-cmds.h file would no longer be used, they should probably be removed. -Peff ``` ## Junio C Hamano, 2008-12-02 01:45 Subject: Re: [PATCH] Modified the default git help message to be grouped by topic Message-ID: <7v7i6jqriv.fsf@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7v7i6jqriv.fsf%40gitster.siamese.dyndns.org In-Reply-To: <20081201183258.GB24443@coredump.intra.peff.net> ``` Jeff King writes: > On Mon, Dec 01, 2008 at 09:30:37AM -0800, Scott Chacon wrote: > >> It's difficult to process 21 commands (which is what is output >> by default for git when no command is given). I've re-grouped >> them into 4 groups of 5 or 6 commands each, which I think is >> clearer and easier for new users to process. > > I like it (and I think the categorizations look reasonable, which is > something that I recall caused some discussion at the GitTogether). > > The only downside I see is that we're now >24 lines. If this list is meant to show "the most commonly used" basics, then you can trim the list somewhat. For example, "rm" and "mv" can be safely discarded, "status" can be replaced with "diff", and "diff" can be removed from "History Commands". ``` ## Scott Chacon, 2008-12-02 06:10 Subject: Re: [PATCH] Modified the default git help message to be grouped by topic Message-ID: URL: https://gitlist.dev/e/d411cc4a0812012210h4cb59974sbda71abd2c64f93b%40mail.gmail.com In-Reply-To: <7v7i6jqriv.fsf@gitster.siamese.dyndns.org> ``` Hi, On Mon, Dec 1, 2008 at 5:45 PM, Junio C Hamano wrote: > Jeff King writes: > >> On Mon, Dec 01, 2008 at 09:30:37AM -0800, Scott Chacon wrote: >> >>> It's difficult to process 21 commands (which is what is output >>> by default for git when no command is given). I've re-grouped >>> them into 4 groups of 5 or 6 commands each, which I think is >>> clearer and easier for new users to process. >> >> I like it (and I think the categorizations look reasonable, which is >> something that I recall caused some discussion at the GitTogether). >> >> The only downside I see is that we're now >24 lines. > > If this list is meant to show "the most commonly used" basics, then you > can trim the list somewhat. For example, "rm" and "mv" can be safely > discarded, "status" can be replaced with "diff", and "diff" can be removed > from "History Commands". > I sent a new patch that removes 'rm' and 'mv' and removes the common-cmd.h build process. I did keep the 'status' command, since in my personal experience people tend to like having that command. Scott ``` ## James Pickens, 2008-12-02 20:11 Subject: Re: [PATCH] Modified the default git help message to be grouped by topic Message-ID: <885649360812021211u3d547982i8e1c3070972363e8@mail.gmail.com> URL: https://gitlist.dev/e/885649360812021211u3d547982i8e1c3070972363e8%40mail.gmail.com In-Reply-To: ``` On Mon, Dec 1, 2008 at 11:10 PM, Scott Chacon wrote: > Hi, > > On Mon, Dec 1, 2008 at 5:45 PM, Junio C Hamano wrote: >> If this list is meant to show "the most commonly used" basics, then you >> can trim the list somewhat. For example, "rm" and "mv" can be safely >> discarded, "status" can be replaced with "diff", and "diff" can be removed >> from "History Commands". >> > > I sent a new patch that removes 'rm' and 'mv' and removes the > common-cmd.h build process. I did keep the 'status' command, since in > my personal experience people tend to like having that command. Even though 'rm' might not be used very often, I think it's an important enough command that it should not be removed from the 'basics' list. AFAIK, the only other way to delete a file is 'rm file' followed by 'git add -u' or 'git commit -a'. Imagine a git newbie trying to figure that out. I'm tempted to say the same thing about 'mv' as well. And FWIW, I use 'status' a lot more than I use 'diff', so I would vote to keep 'status' in the list too. James ``` ## Boyd Stephen Smith Jr., 2008-12-02 21:33 Subject: Re: [PATCH] Modified the default git help message to be grouped by topic Message-ID: <200812021533.42114.bss03@volumehost.net> URL: https://gitlist.dev/e/200812021533.42114.bss03%40volumehost.net In-Reply-To: <885649360812021211u3d547982i8e1c3070972363e8@mail.gmail.com> ``` On Tuesday 02 December 2008, "James Pickens" wrote about 'Re: [PATCH] Modified the default git help message to be grouped by topic': >On Mon, Dec 1, 2008 at 11:10 PM, Scott Chacon wrote: >> I sent a new patch that removes 'rm' and 'mv' and removes the >> common-cmd.h build process. I did keep the 'status' command, since in >> my personal experience people tend to like having that command. > >Even though 'rm' might not be used very often, I think it's an important >enough command that it should not be removed from the 'basics' list. >AFAIK, the only other way to delete a file is 'rm file' followed by 'git >add -u' or 'git commit -a'. Imagine a git newbie trying to figure that >out. > >I'm tempted to say the same thing about 'mv' as well. And FWIW, I use >'status' a lot more than I use 'diff', so I would vote to keep 'status' > in the list too. x2 to all of both paragraphs, except that I'm not just "tempted"; I do say that mv should be kept. -- Boyd Stephen Smith Jr. ,= ,-_-. =. bss03@volumehost.net ((_/)o o(\_)) ICQ: 514984 YM/AIM: DaTwinkDaddy `-'(. .)`-' http://iguanasuicide.org/ \_/ ``` ## Johannes Schindelin, 2008-12-02 22:55 Subject: Re: [PATCH] Modified the default git help message to be grouped by topic Message-ID: URL: https://gitlist.dev/e/alpine.DEB.1.00.0812022353410.27091%40racer In-Reply-To: <885649360812021211u3d547982i8e1c3070972363e8@mail.gmail.com> ``` Hi, On Tue, 2 Dec 2008, James Pickens wrote: > On Mon, Dec 1, 2008 at 11:10 PM, Scott Chacon wrote: > > > On Mon, Dec 1, 2008 at 5:45 PM, Junio C Hamano wrote: > >> If this list is meant to show "the most commonly used" basics, then > >> you can trim the list somewhat. For example, "rm" and "mv" can be > >> safely discarded, "status" can be replaced with "diff", and "diff" > >> can be removed from "History Commands". > > > > I sent a new patch that removes 'rm' and 'mv' and removes the > > common-cmd.h build process. I did keep the 'status' command, since in > > my personal experience people tend to like having that command. > > Even though 'rm' might not be used very often, I think it's an important > enough command that it should not be removed from the 'basics' list. > AFAIK, the only other way to delete a file is 'rm file' followed by 'git > add -u' or 'git commit -a'. Imagine a git newbie trying to figure that > out. > > I'm tempted to say the same thing about 'mv' as well. And FWIW, I use > 'status' a lot more than I use 'diff', so I would vote to keep 'status' > in the list too. If the whole thing gets longer than 24 lines, we have to leave some things out. Personally, I consider rm and mv unimportant enough that they could be shown in an extended list, but be left out of the summary page. Ciao, Dscho ``` ## Jeff King, 2008-12-02 23:30 Subject: Re: [PATCH] Modified the default git help message to be grouped by topic Message-ID: <20081202233004.GA22379@coredump.intra.peff.net> URL: https://gitlist.dev/e/20081202233004.GA22379%40coredump.intra.peff.net In-Reply-To: ``` On Tue, Dec 02, 2008 at 11:55:03PM +0100, Johannes Schindelin wrote: > If the whole thing gets longer than 24 lines, we have to leave some things > out. Personally, I consider rm and mv unimportant enough that they could > be shown in an extended list, but be left out of the summary page. For the record, the current output is 26 lines, plus you probably want to account for 1 line of the user's next shell prompt. So we are 3 lines over already. Scott's proposal is about grouping the commands more sensibly. Many of the complaints are about the length of the output. Maybe we should scrap having a list of commands altogether and just point at section-specific documentation, each of which could discuss basic commands related to it. I think there has been mention of task-oriented documentation pointers before, and I think this is a place where we would want it. -Peff ``` ## Scott Chacon, 2008-12-02 23:39 Subject: Re: [PATCH] Modified the default git help message to be grouped by topic Message-ID: URL: https://gitlist.dev/e/d411cc4a0812021539g34d3a94bn7e873f8cf04adc56%40mail.gmail.com In-Reply-To: <20081202233004.GA22379@coredump.intra.peff.net> ``` Hi, On Tue, Dec 2, 2008 at 3:30 PM, Jeff King wrote: > On Tue, Dec 02, 2008 at 11:55:03PM +0100, Johannes Schindelin wrote: > >> If the whole thing gets longer than 24 lines, we have to leave some things >> out. Personally, I consider rm and mv unimportant enough that they could >> be shown in an extended list, but be left out of the summary page. > > For the record, the current output is 26 lines, plus you probably want > to account for 1 line of the user's next shell prompt. So we are 3 lines > over already. > > Scott's proposal is about grouping the commands more sensibly. Many of > the complaints are about the length of the output. Maybe we should scrap > having a list of commands altogether and just point at section-specific > documentation, each of which could discuss basic commands related to it. I've always felt it was helpful to newcomers to have that page there with the couple dozen commands you might use - mostly in case you've forgotten what the exact command name was. Hg does something like 'hg help' which gives you more commands, but I feel like just having the quick cheat-sheet is generally really helpful. If someone just wants to remember what the command 'checkout' was, I wouldn't want them to have to go to two places - one to look up what the task document was and then another to view that. My $0.02 > I think there has been mention of task-oriented documentation pointers > before, and I think this is a place where we would want it. > > -Peff > Scott ``` ## Junio C Hamano, 2008-12-03 00:10 Subject: Re: [PATCH] Modified the default git help message to be grouped by topic Message-ID: <7vfxl6m84g.fsf@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7vfxl6m84g.fsf%40gitster.siamese.dyndns.org In-Reply-To: <20081202233004.GA22379@coredump.intra.peff.net> ``` Jeff King writes: > On Tue, Dec 02, 2008 at 11:55:03PM +0100, Johannes Schindelin wrote: > >> If the whole thing gets longer than 24 lines, we have to leave some things >> out. Personally, I consider rm and mv unimportant enough that they could >> be shown in an extended list, but be left out of the summary page. > > For the record, the current output is 26 lines, plus you probably want > to account for 1 line of the user's next shell prompt. So we are 3 lines > over already. > > Scott's proposal is about grouping the commands more sensibly. Many of > the complaints are about the length of the output. Maybe we should scrap > having a list of commands altogether and just point at section-specific > documentation, each of which could discuss basic commands related to it. > > I think there has been mention of task-oriented documentation pointers > before, and I think this is a place where we would want it. It might not be a bad idea to make this "top page help" into an interactive hierarchical help topic browser. You would start a page that might look like this: Bootstrapping -- preparing an area to work in init, clone Basic -- review, undo and record your changes diff, status, checkout , add, reset, commit History -- inspect what you have now, and what happened before log, blame, grep, show Branching and Merging -- build and use alternate histories branch, checkout -b, merge, rebase Working with Others remote, fetch, pull, push with each of the command and the heading being a "link" (use ncurses for that). If you choose the leaf-level command (say, 'diff'), you will get the git-diff(1) manual page. If you pick one of the headings, say, "Basic", you may get a more extended description of commands in the category, that may include other basic commands not in the front page, perhaps, like this: (review) diff HEAD: view what you did since the last commit diff: view what you did since you last added diff --cached: view what you already added status: list what are added and changes yet to be added (undo) checkout path...: checkout a copy from the staging area checkout HEAD path...: checkout a copy from the last commit reset: undo earlier "git add" to the staging area reset path...: do so only for the named paths (record) mv path1 path2: move the state of path1 to path2 rm path2: remove path2 rm --cached path2: do so without losing the copy in the working tree add: add the contents to the staging area add -p: do so interactively, hunk by hunk commit: record the changes you added to the staging area commit path...: record all the changes to the paths, ignoring changes you added to the staging area for other paths. and again each element can be a "link". ``` ## Jeff King, 2008-12-03 00:37 Subject: Re: [PATCH] Modified the default git help message to be grouped by topic Message-ID: <20081203003731.GA23780@coredump.intra.peff.net> URL: https://gitlist.dev/e/20081203003731.GA23780%40coredump.intra.peff.net In-Reply-To: <7vfxl6m84g.fsf@gitster.siamese.dyndns.org> ``` On Tue, Dec 02, 2008 at 04:10:07PM -0800, Junio C Hamano wrote: > It might not be a bad idea to make this "top page help" into an > interactive hierarchical help topic browser. You would start a page that > might look like this: > > Bootstrapping -- preparing an area to work in > init, clone > Basic -- review, undo and record your changes > diff, status, checkout , add, reset, commit > History -- inspect what you have now, and what happened before > log, blame, grep, show > Branching and Merging -- build and use alternate histories > branch, checkout -b, merge, rebase > Working with Others > remote, fetch, pull, push Yes, that is the sort of thing I was thinking of. And I think your layout addresses Scott's concern, which is to keep names of commands available for quick reference. So really we are ditching the descriptions. > with each of the command and the heading being a "link" (use ncurses for > that). If you choose the leaf-level command (say, 'diff'), you will get I'm not sure we need anything so fancy. I was thinking of something like: Bootstrapping -- preparing an area to work in (bootstrapping) init, clone ... Working with Others (others) remote, fetch, pull, push Use "git help " for more help on one of these subjects, or "git help " for help with a specific command. And maybe the "(bootstrapping)" could be typographically more obvious as the subject keyword, but I think you get the point (and for "Bootstrapping", it's obvious what the keyword would be, but for "Working with Others" it's not). And obviously something with ncurses would save you typing, but I have no desire to recreate "info" or "lynx" here (and I also think that "git" or "git foo" displaying help should remain non-interactive to cause the least surprise). -Peff ``` ## Jakub Narebski, 2008-12-03 00:47 Subject: Re: [PATCH] Modified the default git help message to be grouped by topic Message-ID: URL: https://gitlist.dev/e/gh4kub%24rh3%241%40ger.gmane.org In-Reply-To: <7vfxl6m84g.fsf@gitster.siamese.dyndns.org> ``` Junio C Hamano wrote: > Jeff King writes: > >> On Tue, Dec 02, 2008 at 11:55:03PM +0100, Johannes Schindelin wrote: >> >>> If the whole thing gets longer than 24 lines, we have to leave some things >>> out.  Personally, I consider rm and mv unimportant enough that they could >>> be shown in an extended list, but be left out of the summary page. >> >> For the record, the current output is 26 lines, plus you probably want >> to account for 1 line of the user's next shell prompt. So we are 3 lines >> over already. >> >> Scott's proposal is about grouping the commands more sensibly. Many of >> the complaints are about the length of the output. Maybe we should scrap >> having a list of commands altogether and just point at section-specific >> documentation, each of which could discuss basic commands related to it. >> >> I think there has been mention of task-oriented documentation pointers >> before, and I think this is a place where we would want it. > > It might not be a bad idea to make this "top page help" into an > interactive hierarchical help topic browser. Isn't that info? -- Jakub Narebski Warsaw, Poland ShadeHawk on #git ```