Re: PATCH: improve git switch documentation

From: Sergey Organov <sorganov@gmail.com>
Date: Jul 11, 2021, 12:23 UTC
Message-ID: <871r85f39n.fsf@osv.gnss.ru>
In-Reply-To: <6ffd7f1c-97be-a57c-b738-31deae26e8fc@mfriebe.de>

Martin <git@mfriebe.de> writes:

Show 16 quoted lines

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

Show 9 quoted lines

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

Show 5 quoted lines

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

Show 14 quoted lines

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

Show 10 quoted lines

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

Show 9 quoted lines

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

Show 8 quoted lines

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

Show 7 quoted lines

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