Re: PATCH: improve git switch documentation

Martin [off-list ref] writes:

On 11/07/2021 14:23, Sergey Organov wrote:

quoted

Martin [off-list ref] writes:

[...]

quoted

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.

quoted

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.

quoted

quoted

quoted

  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