Re: PATCH: improve git switch documentation

[Sergey Organov <sorganov@gmail.com>]

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

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

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

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