Re: PATCH: improve git switch documentation

[Martin <git@mfriebe.de>]

On 11/07/2021 11:04, Sergey Organov wrote:
> Felipe Contreras <felipe.contreras@gmail.com> writes:
> 
>>
>> I don't see the logic in here.
>>
>>    git branch topic # here 'branch' is the verb
> 
> Not to me. I assumed the "branch" is always a noun in "git branch", and
> the actual meaning of this command is:

Well, it is easy to see it as a noun. But for "branching" creation of a 
branch, it can be seen as verb.

Yet in
    git branch --list
it definitely is a noun.

But then how would/should those work?
The action/verb is "list" or "show"

    git show branches
    git show tags
    git show ...

That completely tears apart related topics.

Or is it enough if the subcommand is a verb?
     git branch create
     git branch list
That be ok for me.


>>> is "branch" a noun or a verb?
>>
>> Both.
> 
> No, it's rather noun plus lacking subcommand, sometimes making it look
> like verb :)

As is
     git stash
for
     git stash push

And I should guess lots of people like the short form....




> I.e., I'm in favor of universal:
> 
>     git <command> ...
> 
> syntax to Git commands where <command> specifies an action. [Why things
> tend to drift to Lisp all the time, I wonder?]
> 

Because humans are more about the "things".
The way we interact is more ofter derived from the object, than the 
object being purposefully made for an interaction?


>  From that POV, for the commands you mentioned, "git bisect" is probably
> fine, whereas "git worktree", and "git remote" should better be split to
> operations on them, e.g.:
> 
>     git new remote
>     git new worktree
> 

That also makes documentation harder. People who want a worktree, want 
the documentation for it in one place.

So a manpage for "git new" is not desirable. It would have to be split 
into the manpages for the objects. But that is not good either, or is it?


> Once that is regularized, we may as well consider allowing for inverse
> order of the first 2 arguments, by making
> 
>    git new remote
>    git remote new
> 
> the synonyms.

Having even more ways to do one and the same thing....


Btw, missing from the discussion:

    git log

"log" can be a verb, but not in the above.

Because "to log" is to write something into a log.
But "git log" is to show (i.e. read) the log.