git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: Martin <git@mfriebe.de>
To: Junio C Hamano <gitster@pobox.com>
Cc: git@vger.kernel.org
Subject: Re: PATCH: improve git switch documentation
Date: Thu, 1 Jul 2021 12:06:17 +0200	[thread overview]
Message-ID: <b80bf908-0c31-2b3a-6d6c-1a3fba5b2334@mfriebe.de> (raw)
In-Reply-To: <xmqqy2arrmba.fsf@gitster.g>

On 01/07/2021 00:59, Junio C Hamano wrote:
> 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

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


  reply	other threads:[~2021-07-01 10:06 UTC|newest]

Thread overview: 103+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-06-29 15:28 PATCH: improve git switch documentation Martin
2021-06-29 16:35 ` Junio C Hamano
2021-06-29 19:04   ` Martin
2021-06-29 22:39     ` Junio C Hamano
2021-06-30  8:50       ` Martin
2021-06-30 22:59         ` Junio C Hamano
2021-07-01 10:06           ` Martin [this message]
2021-07-01 11:27             ` Sergey Organov
2021-07-07 18:34               ` Felipe Contreras
2021-07-07 20:46                 ` Sergey Organov
2021-07-07 21:25                   ` What actually is a branch? Felipe Contreras
2021-07-07 22:07                     ` Sergey Organov
2021-07-07 22:35                       ` Martin
2021-07-08  3:39                         ` Felipe Contreras
2021-07-08 10:15                           ` Martin
2021-07-08 17:33                             ` Felipe Contreras
2021-07-08 19:21                               ` Martin
2021-07-08 20:37                                 ` Felipe Contreras
2021-07-08 23:11                                   ` Martin
2021-07-09  0:45                                     ` Felipe Contreras
2021-07-09 13:24                                       ` Martin
2021-07-09 15:08                                         ` Felipe Contreras
2021-07-09 15:23                                           ` switch requires --detach [[Re: What actually is a branch]] Martin
2021-07-09 16:21                                             ` Felipe Contreras
2021-07-09 16:38                                               ` Randall S. Becker
2021-07-09 17:10                                                 ` Felipe Contreras
2021-07-09 16:54                                               ` Martin
2021-07-10 10:08                                             ` Sergey Organov
2021-07-10 19:18                                               ` Felipe Contreras
2021-07-09 14:29                                       ` PATCH: improve git switch documentation Martin
2021-07-09 16:10                                         ` Felipe Contreras
2021-07-09 16:51                                           ` Martin
2021-07-09 17:41                                             ` Felipe Contreras
2021-07-09 18:23                                               ` Martin
2021-07-10 19:45                                                 ` Felipe Contreras
2021-07-10 20:07                                                   ` Martin
2021-07-10 20:49                                                     ` Felipe Contreras
2021-07-10 22:13                                                       ` Martin
2021-07-10 23:35                                                         ` Felipe Contreras
2021-07-11  9:10                                                           ` Martin
2021-07-11  9:30                                                             ` Sergey Organov
2021-07-12 16:28                                                             ` Felipe Contreras
2021-07-12 16:33                                                               ` Martin
2021-07-12 16:58                                                                 ` Felipe Contreras
2021-07-12 17:52                                                                   ` Martin
2021-07-12 19:08                                                                     ` Felipe Contreras
     [not found]                                                                       ` <3a84e4c9-4e48-1cbe-4fe6-150ff56c8508@mfriebe.de>
     [not found]                                                                         ` <60ecbe577a086_a6b702082@natae.notmuch>
2021-07-13 10:42                                                                           ` Martin
2021-07-13 16:02                                                                             ` Felipe Contreras
2021-07-16 18:12                                                                               ` Martin
2021-07-16 18:31                                                                               ` Martin
2021-07-16 18:56                                                                                 ` Felipe Contreras
2021-07-17  7:02                                                                                   ` Martin
     [not found]                                                                                   ` <1997ca3b-117a-e19a-0dee-7342a2f1a0e7@mfriebe.de>
     [not found]                                                                                     ` <60f1f4c3dd8b1_14cb208c1@natae.notmuch>
     [not found]                                                                                       ` <fedbfe1f-9e6d-f46f-ca41-e176a30e938c@mfriebe.de>
     [not found]                                                                                         ` <60f22aaa6a4f1_1f602081b@natae.notmuch>
2021-07-17 10:07                                                                                           ` Martin
     [not found]                                                                                             ` <60f33f8a7c39b_507220823@natae.notmuch>
2021-07-17 21:23                                                                                               ` Martin
2021-07-19 17:51                                                                                                 ` Felipe Contreras
2021-07-11  7:57                                                         ` Sergey Organov
2021-07-11  9:27                                                           ` Martin
2021-07-11  9:37                                                             ` Sergey Organov
2021-07-11 10:24                                                               ` Martin
2021-07-12 16:34                                                             ` Felipe Contreras
2021-07-10 22:13                                                       ` Naming the --forec option [[Re: PATCH: improve git switch documentation]] Martin
2021-07-10 23:18                                                         ` Felipe Contreras
2021-07-11  0:39                                                           ` Martin
2021-07-12 16:15                                                             ` Felipe Contreras
2021-07-10 10:24                                             ` PATCH: improve git switch documentation Sergey Organov
2021-07-10 10:37                                               ` Bagas Sanjaya
2021-07-10 11:05                                               ` Martin
2021-07-10 16:32                                                 ` Sergey Organov
2021-07-10 20:12                                                   ` Felipe Contreras
2021-07-11  9:04                                                     ` Sergey Organov
2021-07-11 10:05                                                       ` Martin
2021-07-11 12:23                                                         ` Sergey Organov
2021-07-11 13:39                                                           ` Martin
2021-07-11 14:49                                                             ` Sergey Organov
2021-07-11 16:51                                                             ` Sergey Organov
2021-07-12 10:31                                                               ` Kerry, Richard
2021-07-12 11:11                                                                 ` Sergey Organov
2021-07-12 16:55                                                                   ` Felipe Contreras
2021-07-12 16:24                                                       ` Felipe Contreras
2021-07-12 16:39                                                         ` Martin
2021-07-12 17:09                                                           ` Felipe Contreras
2021-07-12 22:58                                                         ` Sergey Organov
2021-07-12 23:36                                                           ` Felipe Contreras
2021-07-13 11:20                                                           ` Martin
2021-07-10 20:00                                                 ` Felipe Contreras
2021-07-10 19:51                                               ` Felipe Contreras
2021-07-11  9:52                                                 ` Sergey Organov
2021-07-12 16:44                                                   ` Felipe Contreras
2021-07-13 10:57                                                     ` Sergey Organov
2021-07-13 16:10                                                       ` Felipe Contreras
2021-07-14 19:14                                                         ` Sergey Organov
2021-07-14 19:51                                                           ` Felipe Contreras
2021-07-14 20:42                                                             ` Sergey Organov
2021-07-08  3:12                       ` What actually is a branch? Felipe Contreras
2021-07-08 11:16                         ` Sergey Organov
2021-07-08 18:05                           ` Felipe Contreras
2021-07-01 14:58             ` PATCH: improve git switch documentation Junio C Hamano
2021-07-01 17:29               ` Martin
2021-07-01 17:46                 ` Sergey Organov
2021-07-07 18:54                 ` Felipe Contreras
2021-07-07 18:47               ` Felipe Contreras
2021-07-07 18:14             ` Felipe Contreras
2021-07-01  0:06         ` Matt Rogers

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=b80bf908-0c31-2b3a-6d6c-1a3fba5b2334@mfriebe.de \
    --to=git@mfriebe.de \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).