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

El 12/06/2010, a las 18:17, Scott Chacon escribió:

Hey,

On Fri, Jun 11, 2010 at 9:26 AM, Wincent Colaiuta [off-list ref] wrote:

quoted

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.

I think that's an overly restrictive criterion. By that standard, "git status" shouldn't be there either because you don't *have* to know that to use Git either.

quoted

"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.

In any case, now that you mention it I see that I forgot to include "git tag" anywhere in the listing. I don't think it belongs clearly in any of the categories mentioned so far, despite the fact that it is still a fairly basic command. Perhaps there's a need for a final section called "Other commands:"...

quoted

"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.

Well, it's a pretty useful tool IMO as you can point "git show" at just about anything and get something informative back. I use it all the time with no params to get a quick look at the latest change in a repo, and point it at tags and such to give me a quick indication of when/what they were applied to.

For me "git reset" is a much more advanced command and one of the _last_ things I would show a beginning user, seeing as it actually requires them to have a proper grasp of branches and heads in Git (and that may take a little while for them to sink in).

quoted

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

That's not true. You can start learning to use Git in an empty directory with "git init", and in fact you could quite happily use Git for weeks without using "git clone". Some people use Git to track their home directories or "/etc" or whatever, and never work collaboratively with other repositories at all. So there's nothing "fundamental" about "git clone" IMO.

but I had it in the 'remotes' section at first too, so I
wouldn't be terribly opposed to moving it back down there.

Well it is kind of nice to have those five commands grouped together seeing as, unlike some of the other commands under discussion here, they are all indisputably about "Interacting with other repositories".

I really don't want 'checkout' in 'basic' - there is no good reason I can see
to not have it in 'branches'.

Well, it seems pretty basic to me. Have you ever seen a Git tutorial that didn't teach "git checkout" in the first 5 minutes? And once the user gets started using Git it's a command they'll use literally all the time. Sticking it in "branches" seems wrong to me seeing as it is a multi-purpose command that does a lot more than just work with branches.

Wincent