Re: PATCH: improve git switch documentation

On 11/07/2021 11:04, Sergey Organov wrote:

Felipe Contreras [off-list ref] writes:

quoted

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.

quoted

quoted

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.