Re: PATCH: improve git switch documentation

Martin <git@mfriebe.de> writes:

I do not think it is a mistake at all. In a history where the branch B points at commit Z, we do say the branch contains commits Z and Y and we do say the branch does not contain commits X or W, for example.

                 W---X
                /
        ---o---V---Y---Z
                       ^ we're here (branch B)

This is even true if the user is not yet familiar with the "snapshots" view of the world (which is based on "the objects"), but has the "changes" view of the world. The branch has the change that took Y to Z and the change that took V to Y, but it does not have the change that took W to X or the change that took V to W.

If I understand you correctly, the confusion your hypothetical newbie would have is caused by the word "start-point" in

	git branch -f <branch-name> <start-point>

That is, if we repoint the branch that is currently at Z to point at X with "git branch -f B X", it is possible to imagine that we build more history on top of "X" simply because "X" is called "start-point", i.e. we start at X and do something more.

And _your_ particular hypothetical user would imagine that that something more is to replay Y and Z on top.

But I find two problems with the proposed solution to solve that confusion.

 * Replaying Y and Z on top of X is not the only possible way to
   build "more" history on top of "start-point" that is X.  It is,
   for example, entirely plausible to look at the remote-tracking
   branch of B and rebuild the history missing from there on top of
   X, just like your version of confusion rebuilt the history
   missing from the tip of old B on top of X.  Saying "Z and Y will
   not be replayed on top of X after resetting the tip of the branch
   to X" may help _your_ version of confusion, but not other
   confusion.

 * In general, when an explanation in the documentation says that
   a command does A, it shouldn't have to say "the command does A
   but does not do B or C on top of that".

I think the source of the confusion is the <start point>. It does not change what the explanation wants to say at all if we changed it to <end point>. It is where the branch's tip ends up to be after "git branch -f" (or "git switch -C") finishes, so it might even be technically more correct.

The only reason why we use <start point> is purely historical. We used that phrase from the very beginning. The explanation did not consider the use of "gir branch -f" is the *end* of the world. It intended the user to use "gir branch [-f]" to start or restart a branch as the first step of many other things the user will do to build a history on the branch, and that is the reason why the word "start" is used.

Perhaps along the lines of the attached patch would be an improvement without adding "we do not do B, we do not do C, we do not do anything else we do not say we do in this documentation".

Note that the following is *not* meant to be a full illustration; there are many leftover <start-point> in these pages after this patch gets applied that need to be adjusted, if we were to go this route.

 Documentation/git-branch.txt |  4 ++--
 Documentation/git-switch.txt | 14 +++++++-------
 2 files changed, 9 insertions(+), 9 deletions(-)