| Message ID | 483e490349165223a80a0bdf7716c5189560c977.1607637517.git.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Add helpful advice about init.defaultBranch | expand |
On Thu, Dec 10, 2020 at 3:58 PM Johannes Schindelin via GitGitGadget <gitgitgadget@gmail.com> wrote: > > From: Johannes Schindelin <johannes.schindelin@gmx.de> > > Our documentation does not mention any future plan to change 'master' to > other value. It is a good idea to document this, though. > > Initial-patch-by: Junio C Hamano <gitster@pobox.com> > Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> > --- > Documentation/git-init.txt | 11 +++++++---- > 1 file changed, 7 insertions(+), 4 deletions(-) > > diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt > index 59ecda6c17d..2b399cb73d7 100644 > --- a/Documentation/git-init.txt > +++ b/Documentation/git-init.txt > @@ -20,8 +20,9 @@ DESCRIPTION > > This command creates an empty Git repository - basically a `.git` > directory with subdirectories for `objects`, `refs/heads`, > -`refs/tags`, and template files. An initial `HEAD` file that > -references the HEAD of the master branch is also created. The current sentence: "An initial `HEAD` file that references the HEAD of the master branch is also created." is still true. There's no need to change that (yet). > +`refs/tags`, and template files. An initial branch without any > +commits will be created (see the `--initial-branch` option below > +for its name). Perhaps: (see the `--initial-branch` option below to choose another name). > If the `$GIT_DIR` environment variable is set then it specifies a path > to use instead of `./.git` for the base of the repository. > @@ -73,8 +74,10 @@ If this is reinitialization, the repository will be moved to the specified path. > -b <branch-name>:: > --initial-branch=<branch-name>:: > > -Use the specified name for the initial branch in the newly created repository. > -If not specified, fall back to the default name: `master`. > +Use the specified name for the initial branch in the newly created Again; the default name has not changed. > +repository. If not specified, fall back to the default name (currently > +`master`, but that will be changed in the future; the name can be customized > +via the `init.defaultBranch` configuration variable). Wait a second. The advice warning said "this is subject to change", and the documentation says "that will be changed in the future". Which is it? "I might give you a fine", and "I will give you a fine" are most definitely not the same thing. Either say "this is subject to change" in both the documentation and the warning. Or say "that will be changed in the future". Don't say one thing in one and another thing in the other. Cheers.
Felipe Contreras <felipe.contreras@gmail.com> writes: >> -`refs/tags`, and template files. An initial `HEAD` file that >> -references the HEAD of the master branch is also created. >> +`refs/tags`, and template files. An initial branch without any >> +commits will be created (see the `--initial-branch` option below >> +for its name). > > The current sentence: "An initial `HEAD` file that references the HEAD > of the master branch is also created." is still true. There's no need > to change that (yet). The change updates the description for readability, lowering the technical level of description, and correcting inaccuracies. - The readers in the context of understanding what "git init" performs does not have to know nor care that HEAD is implemented as a file. In fact, there is an effort to introduce HEAD and other refs that are implemented as individual files under $GIT_DIR/. Dropping the word "file" is to correct these. - Also we no longer say "the HEAD of" a branch, even if we used to use that expression. When we really need to refer to the commit directly pointed at by a branch ref, we say "the tip of" instead there days. - It used to be left unsaid that the initial branch begins its life without any commit. Now it does. None of these is about "'master' or any other name?" issue. > Perhaps: (see the `--initial-branch` option below to choose another name). That changes the meaning of the explanation. It is compensating for not saying what the name of the initial branch is, and is not trying to teach that the name can be changed. The text in the patch is good as-is.
Felipe Contreras <felipe.contreras@gmail.com> writes: > On Thu, Dec 10, 2020 at 3:58 PM Johannes Schindelin via GitGitGadget > >> +repository. If not specified, fall back to the default name (currently >> +`master`, but that will be changed in the future; the name can be customized >> +via the `init.defaultBranch` configuration variable). > > Wait a second. The advice warning said "this is subject to change", > and the documentation says "that will be changed in the future". Which > is it? > > "I might give you a fine", and "I will give you a fine" are most > definitely not the same thing. I think we say "this is subject to change" in other places, and I agree that this part should match to avoid confusing readers, especially the non-native ones like me. If not specified, fall back to the default name (currently `master`, but this is subject to change in the future; ... would be more consistent.
On Thu, Dec 10, 2020 at 11:47 PM Junio C Hamano <gitster@pobox.com> wrote: > > Felipe Contreras <felipe.contreras@gmail.com> writes: > > >> -`refs/tags`, and template files. An initial `HEAD` file that > >> -references the HEAD of the master branch is also created. > >> +`refs/tags`, and template files. An initial branch without any > >> +commits will be created (see the `--initial-branch` option below > >> +for its name). > > > > The current sentence: "An initial `HEAD` file that references the HEAD > > of the master branch is also created." is still true. There's no need > > to change that (yet). > > The change updates the description for readability, lowering the > technical level of description, and correcting inaccuracies. OK. > - The readers in the context of understanding what "git init" > performs does not have to know nor care that HEAD is implemented > as a file. In fact, there is an effort to introduce HEAD and > other refs that are implemented as individual files under > $GIT_DIR/. Dropping the word "file" is to correct these. Right. > - Also we no longer say "the HEAD of" a branch, even if we used to > use that expression. When we really need to refer to the commit > directly pointed at by a branch ref, we say "the tip of" instead > there days. Sure. > - It used to be left unsaid that the initial branch begins its life > without any commit. Now it does. OK. > None of these is about "'master' or any other name?" issue. Indeed, but the commit message clearly states: Our documentation does not mention any future plan to change 'master' to other value. It is a good idea to document this, though. It doesn't say anything about improving the documentation of "git init", nor any of your three points. The main intention is clear. On top of your three points it sneaks another change; avoiding the "master" branch name. If this really had nothing to do with the "master" branch name, it could very well be sent as a separate independent patch. The following text has your three valid points, but doesn't sneak in the extra change: An initial "master" branch without any commits will be created (see the `--initial-branch` option below to choose another name). > > Perhaps: (see the `--initial-branch` option below to choose another name). > > That changes the meaning of the explanation. It is compensating for > not saying what the name of the initial branch is, and is not trying > to teach that the name can be changed. The text in the patch is good > as-is. In English parentheses are used to clarify information, and typically it's *supplementary* information. That is; the sentence must stand on its own without them. This sentence is missing crucial information and it doesn't stand on its own: An initial branch without any commits will be created. This one does stand on its own: An initial "master" branch without any commits will be created. (and doesn't omit any current information.) Cheers.
diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt index 59ecda6c17d..2b399cb73d7 100644 --- a/Documentation/git-init.txt +++ b/Documentation/git-init.txt @@ -20,8 +20,9 @@ DESCRIPTION This command creates an empty Git repository - basically a `.git` directory with subdirectories for `objects`, `refs/heads`, -`refs/tags`, and template files. An initial `HEAD` file that -references the HEAD of the master branch is also created. +`refs/tags`, and template files. An initial branch without any +commits will be created (see the `--initial-branch` option below +for its name). If the `$GIT_DIR` environment variable is set then it specifies a path to use instead of `./.git` for the base of the repository. @@ -73,8 +74,10 @@ If this is reinitialization, the repository will be moved to the specified path. -b <branch-name>:: --initial-branch=<branch-name>:: -Use the specified name for the initial branch in the newly created repository. -If not specified, fall back to the default name: `master`. +Use the specified name for the initial branch in the newly created +repository. If not specified, fall back to the default name (currently +`master`, but that will be changed in the future; the name can be customized +via the `init.defaultBranch` configuration variable). --shared[=(false|true|umask|group|all|world|everybody|0xxx)]::