Re: [PATCH v2] Group the default git help message by topic

Hey,

On Fri, Jun 11, 2010 at 9:26 AM, Wincent Colaiuta [off-list ref] 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