Re: [PATCH 0/3] git help: group common commands by theme

From: Junio C Hamano <gitster@pobox.com>
Date: May 6, 2015, 17:42 UTC
Message-ID: <xmqqoalxbo0w.fsf@gitster.dls.corp.google.com>
In-Reply-To: <vpqfv7ap25j.fsf@anie.imag.fr>

Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:

Show 16 quoted lines

> Sébastien Guimmara <sebastien.guimmara@gmail.com> writes:
>
>>    * examining the history and state:
>>       log        Show commit logs
>>       status     Show the working tree status
>>
>>    * growing, marking and tweaking your history:
>>       branch     List, create, or delete branches
>>       checkout   Checkout a branch or paths to the working tree
>>       commit     Record changes to the repository
>>       diff       Show changes between commits, commit and working [...]
>>       merge      Join two or more development histories together
>
> I would have put "diff" next to "status" in the "examining the history
> and state" section. It's neither growing, marking nor tweaking the
> history.

I am somewhat torn on this.

Your suggestion is about "what does this command do?" Which is a perfectly acceptable way to categorize commands once you nailed your workflow down.

There is another school of thought to organize them according to "in which phase in your development cycle do you use this command?", i.e. more workflow oriented categorization. From this point of view, "diff" and "status" are important tools you use while "growing your own history".

> But removing rm and mv seems weird. It seems to me that the obvious
> question of someone who just learnt "add" would be "and how do I do the
> opposite?".

And the answer may confuse that someone even further (it is not necessarily "rm", but is often "reset"). As a list of simple command set to help the dip-your-toes-in-water process, a new user may be better off starting with "add", "add ." and "commit -a", and learn from the last part of "git add --help" that there are "rm" and "mv" (both of which happen a lot less often than "add").