Re: PATCH: improve git switch documentation

From: Sergey Organov <sorganov@gmail.com>
Date: Jul 12, 2021, 11:11 UTC
Message-ID: <87r1g3n5x3.fsf@osv.gnss.ru>
In-Reply-To: <AS8PR02MB730258D0643373CB476A18D39C159@AS8PR02MB7302.eurprd02.prod.outlook.com>

"Kerry, Richard" <richard.kerry@atos.net> writes:

Show 7 quoted lines

>> >    git branch switch
>> >    git tag switch   // detach
>> >    git commit switch   // detach
>> 
>> Why? You don't switch tags or commits. You switch only branches, 
>
> Yes you do.

No, you don't. You probably didn't read my sentence carefully. Please try to read what is written there, and see below for more explanations.

> You can switch to branches, tags or commits.

1. Switch branch /to a tag/ is not the same as switching /tag/. You can
reset tag to point to another commit, yes, but that was outside of the
scope of the discussion. Switching *commit* doesn't make sense at all.
Overall, you don't switch tags or commits when you switch branches, --
that's the meaning of my original sentence.

2. Event when you switch /to/ tags or commits, you actually still switch
to a branch, as you can still create new commits that will grow that
branch. This "detached HEAD" thingy that has been adopted to support
switching to commits is just a misnomer that obscures understanding, and
should be eventually replaced, probably by means of introducing the
notion of "unnamed" or "automatic" branch.

Show 11 quoted lines

>
> If I remember correctly, "branch" is used in Subversion and CVS only
> for the creation of a branch. Likewise "tag" for creating a tag.
> And I think they both use "update" to load the required
> branch/tag/commit into the current working area.
>
> If git were to do that then I think we might get around some of this
> confusion.
>
> In that case:
> git branch = create a branch

Sorry, it's too late. I don't think we can actually do it.

> git tag = create a tag

Ditto. Too late.

Show 5 quoted lines

>
> And then a new "update", so:
> git update <branchname> = make the current working area contain a copy
> of the given branch, and similarly "git update <tagname>" or "git
> update <commit-id>"

It's already called "git restore", no?

>
> In all these cases the keyword after "git" is definitely a verb, even
> where the actual word used could be either, and you need to look at
> all the definitions in the dictionary to check.

In the current "git branch" command "branch" is a noun, and then a verb defining exact operation follows as an option, or is assumed. You may well think about it as being "namespace":

  "git" -- enter "git" namespace
  "branch" -- enter "git:branch" namespace

and everything that follows is about Git branches with more or less random syntax for particular functions to be performed.

Thanks,

-- 
Sergey Organov