Re: PATCH: improve git switch documentation

[Martin <git@mfriebe.de>]

On 09/07/2021 02:45, Felipe Contreras wrote:
> I believe we have all the semantic tools needed to write something that
> is understandable by most people regardless of their conception of what a
> branch is.
> 

So returning to the original topic.


While writing this, I thought maybe there is a need for a
"Guideline on writing documentation" ?



On 01/07/2021 16:58, Junio C Hamano proposed a patch that had an 
interesting point.
The patch was for the docs of "git switch" and "git branch"

1)

      <start-point> versus <commit[-ish]>

I am not sure that this will help much with the original issue, which is 
my concern that a (new) user will be aware of why "switch -C" is a force 
(i.e. what the dangers are).
But it is an interesting point.

 From the synopsis of various commands (just a sample, I did not check all).
   git switch (-c|-C) <new-branch> [<start-point>]
   git branch <branchname> [<start-point>]
   git checkout [--detach] <commit>
   git checkout [[-b|-B|--orphan] <new_branch>] [<start_point>]
   git reset [--soft | --mixed | --hard ] [<commit>]

With the exception for "git reset" they all use <start-point> when it 
comes to branches.

The general question here is, should the synopsis say
a) this parameter should be a "commit".
And then the doc explains the commit will be used as startpoint
b) this parameter should be a "start point"
And then the doc explains the startpoint has to be given as commit.

In terms of checkout, this is especially interesting.
The 2nd form does create a new branch.
But both forms check-out the commit.
IMHO it is somewhat strange that you "check out a start-point to your 
worktree".

So probably <commit> (or even <commit-ish>) may indeed be the better option.
This is however an issue that goes well beyond "git switch".

This may also affect other words used in synopsises. So this is a 
general rule that needs to be decided for all of the documentation.
The issue is, that some commands take several commits.
    git rebase [--onto <newbase>] [<upstream> [<branch>]]
In that case some distinguishing is needed.

There also is the option of "<base-commit[-ish]>".
This tells the user that a commit-ish is needed. But distinguishes it 
from other <commit> that may be given as argument.
This may lead to rather long names (e.g. in rebase).
Though in checkout, I would use only <commit[-ish]> in both variants, as 
the main action is to check out that commit.


2)

      <branch> versus <branch-name>

    git switch [--no-guess] <branch>
    git switch (-c|-C) <new-branch> [<start-point>]
    git branch <branchname> [<start-point>]
    git checkout [[-b|-B|--orphan] <new_branch>] [<start_point>]
    git rebase [--onto <newbase>] [<upstream> [<branch>]]

First of all "git rebase" is simply wrong. I can give a commit for all 3 
arguments. So the last one does not have to be a branch. (or <branch-name>)

Then I think <branch-name> (or <branch-ish> /see other mail) should be 
preferred over <branch>.

As for "git switch -C"
This should IMHO change to (the 2nd arg, actually depends on the point 
"1" above)
    git switch (-c|-C) <branch-name> [<base-commit>]

I suggest to not call it "new-branch-name" because, it might be an 
existing name.


3)

    newbbranch  versus new-branch  versus  new_branch

That is something that just needs to be decided.
"new_branch" is in git checkout.


4)

    Extend of explanation for why a command is classified as "force".

This one is the one I still lobby for support.
This is also on issue across all docs. (or most)

Currently "git switch -C" is simply stated to be --force-create.

- There is no mention what is "forced". All it says is:
>  if <new-branch> already exists, it will be reset to <start-point>.
I guess this is the English verb reset. Because, if the user goes to 
"git reset" then the user would not know what kind of reset.
So the term "reset" is ambiguous, as it could be the verb, or the command.

Of course the "git branch" doc has the same
> Reset <branchname> to <startpoint>, even if <branchname> exists already. 


There is also no word, that this does not include overwriting a dirty 
work tree.

   git switch --force -c unused-name origin/branch
means "forcefully overwrite a dirty work tree"

   git switch --force-create unused-name origin/branch
fails on the dirty work tree.


Btw similar on "git checkout"
   git checkout -B unused-name origin/branch
Only difference, -B has no misleading long option.


But my point is less, the not applying danger.
My point is what danger is there, so that this was made a force command?

Look at
   git checkout --force
> --force
>     When switching branches, proceed even if the index or the working tree differs from HEAD. This is used to throw away local changes.

   git switch --force
> --force
>     An alias for --discard-changes.
and then eventually
> This is used to throw away local changes.

So --force clearly says: You will loose local changes (if you have any).

The same clarity is missing for "force create branch".

Yes, sure any commits that where in the branch, may be hold by other 
branches or the ref-log.
But neither is guaranteed. A branch does not need to have a reflog.

Even if we say a user must know about certain concepts (such as a 
branchname is a reference, and non referenced objects may be lost), even 
then the user is left to connect the dots themself.

I think it should be included in the docs (git switch/checkout/branch 
and reset)

The current wording
    Reset <branchname> to <startpoint>, even if
    <branchname> exists already.

should be amended
Avoid "reset"
    Create a new branch at <startpoint> with the name
    <branchname>, even if <branchname> is already used.

Add clarity
    Create a new branch at <startpoint> with the name
    <branchname>.
    If <branchname> already existed, then the old branch
    will be removed.

If the user perceives "the old branch" as container for a "chain of 
commits", then it is still up to the user to know, that any of those 
commits can be part of other branches. And that "removing the branch", 
may or may not include removing the commits.

However, a user not yet knowing what exactly "removing a branch" means, 
does at least have the word "remove" to make him wary that they should 
look up more details.