Re: PATCH: improve git switch documentation

[Sergey Organov <sorganov@gmail.com>]

Martin <git@mfriebe.de> writes:

> 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.

It's definitely a noun if only consider its description, as output by
"git help":

  "branch            List, create, or delete branches"

So "git branch" is "whatever about branches", not "perform the branch
operation", whatever the latter might be.

>
> 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.

Yep, that's it. However, there is no need to immediately do something
about it except considering this as a sound design to be targeted at.

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

This we can't do sanely in a backward-compatible manner, I'm afraid, so
it's likely not an option.

OTOH, adding, say:

      git rm <branch-name>

or, say, adding a whole new "git new" (pun intended) could be considered
to be steps in the right direction if we choose "git <action> ..."
model.

>
>
>>>> 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....

Maybe. My primary point is inconsistency, not my personal preference for
one way or another. I'm afraid one could find suitable example to
support any model.

>
>> 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?

I don't see it, at least not in the usual human conversations. When one
means an action to be performed, they name the action and then the object:

  "Play football", "Go home", "Set your thoughts straight", "Wash your hands"

No?

Anyway, it's more the consistency that matters, not particular
convention. Git problem is that is has no convention at all. "Just do
what feels right today" seems to be the motto.

Finally, the problem for this particular discussion is that if we decide
that it's rather:

  git <object> <command>

that is the way to go, that I'm pretty fine with as well, we should
simply *obsolete "git switch" right away*, rather than spending time
improving its now almost useless documentation.

>>  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.

  git help worktree

should be able to provide a short manual on worktrees. Please notice
it's again not

  git worktree help


>
> So a manpage for "git new" is not desirable.

Sure it is desirable. That's the primary purpose of manual pages -- to
describe actual commands.

> It would have to be split into the manpages for the objects. But that
> is not good either, or is it?

No-no! Manual pages for describing actual commands are to be there.

It's user/programmer manuals and tutorials that should rather be built
around concepts. It's fine with me if they are available in the format
of manual pages, even though it's not very suitable for that.

>
>> 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....

Python was aiming to have one obvious way of doing every single thing...
Did it succeed in that, I wonder? Maybe this aim is only good in theory?

>
>
> Btw, missing from the discussion:
>
>    git log
>
> "log" can be a verb, but not in the above.

Yep, and "git log" is yet another can of worms I'm not willing to open.

Thanks,
-- 
Sergey Organov