Re: PATCH: improve git switch documentation
- From
- Martin <git@mfriebe.de>
- Date
- Jul 1, 2021, 10:06 UTC
- Message-ID
- <b80bf908-0c31-2b3a-6d6c-1a3fba5b2334@mfriebe.de>
- In-Reply-To
- <xmqqy2arrmba.fsf@gitster.g>
On 01/07/2021 00:59, Junio C Hamano wrote:
Show 13 quoted lines
> Martin <git@mfriebe.de> writes: > >> And yes, for the documentation, it *should* be clear that, removing a >> branch, removes the >> commits on it. >> But then it must be said, that the branch is first removed. That is >> not currently the case. > Sorry, but I still do not see how it makes any difference if the > branch is first removed and then made to point at somewhere else, or > the branch gets just moved without any explicit or impolicit > removal. A branch cannot point at two different commits at the same > time, so the end result is that the commit at the old tip is no > longer pointed at by the branch after the update.
Well all very obvious, if you know git well.
Let's take a step back. How exactly is the word "branch" actually defined? Well it does not matter. What matters is, how the word is used. What does a person mean, when they speak of the branch?
And the answer is, it's not always clear.
In the above conversation, we use "branch" to speak of the "pointer to a single commit". We do not include any commits, when speaking of the "branch". (And this is how it is used in the docs, as far as I can find)
However a lot of people use "branch" to refer to the commits within. "Push a branch to a remote". That obviously means the objects (e.g. commits) in the branch. The doc says (and yes I am getting a bit picky here) >>> Updates remote refs using local refs, while sending objects necessary to complete the given refs. "complete the given ref". The ref is given by the branch, and completing means afaik "to make something part of" Maybe a mistake made, because "branch" is (according to my observation) so commonly (mis-)used to include the objects.
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.
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. The fact that as an experienced user, I shake my head in disbelief, does not change this.
But true, my attempt on adding "the old branch is removed" does not either. So not sure which wording will do best. Probably "Creates a new empty branch at <start point>"
Even though "empty" may be a sloppy usage too....
The other problem with the current doc is
Show 10 quoted lines
> On 01/07/2021 02:06, Matt Rogers wrote: >> I think the current documentations usage of "reset" in >> >> Similar to --create except that if <new-branch> already exists, it >> will be reset to <start-point>. >> >> Is pretty clear about what happens, although it does rely on users >> being familiar >> with the semantics of "resetting" a la git reset. >
Not everyone is "familiar" with reset. And if you look up reset, you are left alone if that is a --soft or --hard or --mixed.
In any case, while it is ok, to refer to other parts of the doc, it should still be possible to read just the current doc, and get a full understanding of the command.
So a short addition to the current doc, that explains "reset" should be added.
I currently am out of ideas how to word it, other than based on my previous ideas.
But as in the first part of this mail, maybe just add the "empty" to the existing doc? So the existing "it will be reset to |<start-point>|. " changes to "it will be reset to [become] an empty branch at |<start-point>|. "
Happy for any idea, how the reader can be reminded, that "branch" is the pointer only, and excludes any objects that it refers to.
I was just about to write "any objects in it (in the branch)". But as established the objects are not part, therefore not "in it"... Just how easy it is to think of branch as more than it is.