Re: PATCH: improve git switch documentation

[Martin <git@mfriebe.de>]

On 13/07/2021 00:58, Sergey Organov wrote:
> Felipe Contreras <felipe.contreras@gmail.com> writes:
>> I disagree. I prefer the former.
> 
>       git create branch "nice-feature"
> 
> Almost plain human language. Isn't it nice? I mean I fail to see why
> you prefer the former, but I don't care that much either.
> 

But human language is not always the best to express something to a 
computer (sometimes not even to a human). Human language for starters is 
often very ambiguous. (Not in this particular example, but in general).

So even if it looks like human language, its not (not a "duck" either;) ).
It still needs each token (each word is a token) to be documented.

The "create" vs "new" is a good example.
- "creating" still happens when you add commits into the branch (human 
language "branch"). Because that's what the branch wants to be, a series 
of commits. You keep creating it, until its done, then you merge it.
- "new" of course is not a verb...

    git prepare branch
would probably be more accurate.
But I am sure it has flaws too.


> No, I don't think it's an option, as unfortunately for your preferences,
> 
>          git branch new
> 
> looks impossible to introduce in a backward compatible manner, nor there
> is significant need to, as
> 
>          git branch
> 
> already does the job, even if by introducing syntax irregularity.

It is not that it already does the job ("git stash push" and "git stash" 
both do the job)

But in
    git branch new
"new" would be the name of a branch. :(

But at some point, it was indicated that this is about finding 
guidelines for future additions.
So not all old commands need to be "fixed".

Not that they are broken. They are fine. We do not need to break them by 
adding a rule like that.

And
    git noun verb <opts>
    git verb <opts>
works as guideline for new additions.

Of course you want to add
    git verb noun
which I personally to not favour.