Re: PATCH: improve git switch documentation

[Sergey Organov <sorganov@gmail.com>]

Martin <git@mfriebe.de> writes:

> On 11/07/2021 14:23, Sergey Organov wrote:
>> Martin <git@mfriebe.de> writes:

[...]

>> 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.
>
> Well human languages are not as rigid as computer languages.
>
>> 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.
>
> Actually then we would end up with
>
>    git branch switch
>    git tag switch   // detach
>    git commit switch   // detach

Why? You don't switch tags or commits. You switch only branches, so it'd
be:

    git branch switch <dest>

where <dest> is any commit'ish.

>
> Well it could be
>    git worktree switch
> (ignoring the effect on the index / and bringing "worktree" into a
> single worktree setup)

Yep, it could be, and it could be even both doing similar things.

>
> The problem is, that IMHO forcing either verb or noun, ends up with
> grouping commands in ways that create unnecessary dividers between
> related actions. (Continued, next paragraph)

The problem is that there are multiple ways of grouping, and selecting
the right one is not an easy decision. Having carefully though-of
guidelines would help.

Grouping by action first is more universal than grouping by object
first, but not always more "natural", as you've correctly noticed.

>
>> 
>>>>   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
>>>>
>
> This is what I mean with dividers.
>
> There may be some relation between "new branch", "new tag"
>
> But I can see none between "new branch" and "new remote" and "new
> worktree". None at all. Yet I can see relations between different
> things
> you can do with a worktree.

The only true relation in this model is that if you want to create
*something* new, you use "git new". Simple like hell.

>
> I also think that, switching to a commit or branch are to closely
> related, and should not be divided.

Strictly speaking, there is no need to switch to something that is not
a branch. But we'd need the notion of "unnamed branch" to achieve this
simplicity while not loosing useful functionality, and even gaining
some, see below.

> (There were even suggestions that switching to a commit, is an unnamed
> branch)

Yep. We just switch our current *branch*, so another *branch* becomes
current. If we specify a commit or a tag as the target, the unnamed
branch should be reset to point there, and only then we should switch
our current to this new unnamed branch. That's it. No need for
complications of "detached HEAD", that even sounds awfully and makes me
scared every time I see it.

In fact this "unnamed branch" could have a non-empty name, say "AUTO",
and its own entry in the reflog. That'd give even more functionality
than is currently available with this chilling "detached HEAD". We should
better bury this Nearly Headless Nick finally.

Thanks,
-- 
Sergey Organov