From: Scott Chacon <schacon@gmail.com>
Date: Sat, 12 Jun 2010 16:17:29 GMT
Subject: Re: [PATCH v2] Group the default git help message by topic
Message-ID: <AANLkTikYIePjF-ZMKh4fS_Gs6AEcImbCY1X7M4FYaEwy@mail.gmail.com>
In-Reply-To: <422F3619-25EC-4509-8EE3-78B6C765AB2A@wincent.com>

Hey,

On Fri, Jun 11, 2010 at 9:26 AM, Wincent Colaiuta <win@wincent.com> wrote:
>
> Nice. I'm sure the output will be a bit less intimidating, but I am not sure about some of the grouping choices you've made here.
>
> "git checkout" is almost certainly a "Basic" command, even though it's used for creating and switching branches.

I wanted the basic commands to be commands that you had to know to use
git.  You really don't actually *have* to know 'checkout' - you only
need to know it if you're using branches, or in a more advanced case,
want to revert file contents.  To just commit snapshots, 'checkout' is
not a necessary command.

>
> "git tag" doesn't really seem to be a "Branch" command, as it's for tagging objects (usually commits), and not branches.

This is true - I suppose it probably actually fits better under
'history', since that's what you're doing is bookmarking a point in
history.

>
> "git reset" is the odd one out in the "History" commands group. The other three commands are about _inspecting_ history, whereas "git reset" is about changing the current HEAD. I actually think "git reset" fits better with the "Branch" commands.
>

I guess - I suppose I put it there because I mainly use it to rewind
my history (reset HEAD~) but it could go under branches.  While we're
at it, I'm not sure 'show' is really necessary in this list at all.  I
rarely use it, which I guess means it's not *terribly* important for
day to day use.

> I think I'd be inclined to use more descriptive headings and group the commands like this:
>
>  Basic operation:
>    init
>    add
>    status
>    commit
>    checkout
>
>  Inspecting repository state and history:
>    log
>    diff
>    show
>
>  Working with branches:
>    branch
>    merge
>    reset
>
>  Interacting with other repositories:
>    clone
>    fetch
>    pull
>    push
>    remote
>

I kind of like the more descriptive headings, but I still think
'clone' should be in the 'basics' section, because everyone needs to
know that, but I had it in the 'remotes' section at first too, so I
wouldn't be terribly opposed to moving it back down there.  I really
don't want 'checkout' in 'basic' - there is no good reason I can see
to not have it in 'branches'.

Scott