Re: [PATCH v2] Group the default git help message by topic
El 12/06/2010, a las 18:17, Scott Chacon escribió:
Show 13 quoted lines
> 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.
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.
Show 5 quoted lines
>> "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:"...
Show 7 quoted lines
>> "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).
Show 30 quoted lines
>> 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
Wincent Colaiuta <win@wincent.com>