[PATCH] Modified the default git help message to be grouped by topic

[PATCH] Modified the default git help message to be grouped by topic

[Scott Chacon]

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 <schacon@gmail.com>
---

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

Re: [PATCH] Modified the default git help message to be grouped by topic

[Jeff King]

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

Re: [PATCH] Modified the default git help message to be grouped by topic

[Junio C Hamano]

Jeff King <peff@peff.net> 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".

Re: [PATCH] Modified the default git help message to be grouped by topic

[Scott Chacon]

Hi,

On Mon, Dec 1, 2008 at 5:45 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Jeff King <peff@peff.net> 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

Re: [PATCH] Modified the default git help message to be grouped by topic

[James Pickens]

On Mon, Dec 1, 2008 at 11:10 PM, Scott Chacon <schacon@gmail.com> wrote:
> Hi,
>
> On Mon, Dec 1, 2008 at 5:45 PM, Junio C Hamano <gitster@pobox.com> 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

Re: [PATCH] Modified the default git help message to be grouped by topic

[Boyd Stephen Smith Jr.]

[-- Attachment #1: Type: text/plain, Size: 1254 bytes --]

On Tuesday 02 December 2008, "James Pickens" <jepicken@gmail.com> 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 <schacon@gmail.com> 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/                      \_/     

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 197 bytes --]

Re: [PATCH] Modified the default git help message to be grouped by topic

[Johannes Schindelin]

Hi,

On Tue, 2 Dec 2008, James Pickens wrote:

> On Mon, Dec 1, 2008 at 11:10 PM, Scott Chacon <schacon@gmail.com> wrote:
>
> > On Mon, Dec 1, 2008 at 5:45 PM, Junio C Hamano <gitster@pobox.com> 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

Re: [PATCH] Modified the default git help message to be grouped by topic

[Jeff King]

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

Re: [PATCH] Modified the default git help message to be grouped by topic

[Scott Chacon]

Hi,

On Tue, Dec 2, 2008 at 3:30 PM, Jeff King <peff@peff.net> 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

Re: [PATCH] Modified the default git help message to be grouped by topic

[Junio C Hamano]

Jeff King <peff@peff.net> 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 <path>, 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".

Re: [PATCH] Modified the default git help message to be grouped by topic

[Jeff King]

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 <path>, 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 <subject>" for more help on one of these subjects, or
  "git help <command>" 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

Re: [PATCH] Modified the default git help message to be grouped by topic

[Jakub Narebski]

Junio C Hamano wrote:

> Jeff King <peff@peff.net> 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