Re: PATCH: improve git switch documentation

[Junio C Hamano <gitster@pobox.com>]

Martin <git@mfriebe.de> writes:

> Anyway, can we agree, that there are people who (mistakenly)
> use/understand "branch" as including the objects?
> Enough people to call it a "common mistake".
> If so, then we should not ignore this.

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.

> With this use of "branch" in mind, (re-)creating an existing
> branch on a new startpoint, does to the inexperienced user read
> like a rebase. It recreates all the commits.

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

diff --git c/Documentation/git-branch.txt w/Documentation/git-branch.txt
index 94dc9a54f2..5e6a32da04 100644
--- c/Documentation/git-branch.txt
+++ w/Documentation/git-branch.txt
@@ -16,7 +16,7 @@ SYNOPSIS
 	[--points-at <object>] [--format=<format>]
 	[(-r | --remotes) | (-a | --all)]
 	[--list] [<pattern>...]
-'git branch' [--track | --no-track] [-f] <branchname> [<start-point>]
+'git branch' [--track | --no-track] [-f] <branchname> [<commit>]
 'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>]
 'git branch' --unset-upstream [<branchname>]
 'git branch' (-m | -M) [<oldbranch>] <newbranch>
@@ -115,7 +115,7 @@ OPTIONS
 
 -f::
 --force::
-	Reset <branchname> to <startpoint>, even if <branchname> exists
+	Reset <branchname> to <commit>, even if <branchname> exists
 	already. Without `-f`, 'git branch' refuses to change an existing branch.
 	In combination with `-d` (or `--delete`), allow deleting the
 	branch irrespective of its merged status. In combination with
diff --git c/Documentation/git-switch.txt w/Documentation/git-switch.txt
index 5c438cd505..c8ea86d385 100644
--- c/Documentation/git-switch.txt
+++ w/Documentation/git-switch.txt
@@ -9,8 +9,8 @@ SYNOPSIS
 --------
 [verse]
 'git switch' [<options>] [--no-guess] <branch>
-'git switch' [<options>] --detach [<start-point>]
-'git switch' [<options>] (-c|-C) <new-branch> [<start-point>]
+'git switch' [<options>] --detach [<commit>]
+'git switch' [<options>] (-c|-C) <new-branch> [<commit>]
 'git switch' [<options>] --orphan <new-branch>
 
 DESCRIPTION
@@ -39,9 +39,9 @@ OPTIONS
 <new-branch>::
 	Name for the new branch.
 
-<start-point>::
-	The starting point for the new branch. Specifying a
-	`<start-point>` allows you to create a branch based on some
+<commit>::
+	The commit pointed at by the new branch. Specifying a
+	`<commit>` allows you to create a branch based on some
 	other point in history than where HEAD currently points. (Or,
 	in the case of `--detach`, allows you to inspect and detach
 	from some other point.)
@@ -59,7 +59,7 @@ out at most one of `A` and `B`, in which case it defaults to `HEAD`.
 -c <new-branch>::
 --create <new-branch>::
 	Create a new branch named `<new-branch>` starting at
-	`<start-point>` before switching to the branch. This is a
+	`<commit>` before switching to the branch. This is a
 	convenient shortcut for:
 +
 ------------
@@ -70,7 +70,7 @@ $ git switch <new-branch>
 -C <new-branch>::
 --force-create <new-branch>::
 	Similar to `--create` except that if `<new-branch>` already
-	exists, it will be reset to `<start-point>`. This is a
+	exists, it will be reset to `<commit>`. This is a
 	convenient shortcut for:
 +
 ------------