| Message ID | 1518387eaa95098707878459bc74bd5ef2179386.1606087406.git.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | Add helpful advice about init.defaultBranch | expand |
"Johannes Schindelin via GitGitGadget" <gitgitgadget@gmail.com> writes: > 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> > --- It would have been nicer to have a reference to the original patch <xmqqd00a36wc.fsf@gitster.c.googlers.com> here after the three-dash lines, which would have made it easier for me to say that the updated phrasing is much better. I do not think I deserve credit for this step in the series. Please drop "initial-patch-by" when you do a v2. > 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 59ecda6c17..19f9f16e6b 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). "branch without any commits" is certainly easier to understand than "unborn branch", which was in my weatherballoon patch. Stepping back a bit more, I wonder if we want to make reference to implementation details even less, e.g. ... an empty Git repository---a `.git` directory to store objects, branches and tags, hooks, and template files. which would be in the same spirit as not mentioning 'HEAD file'. > @@ -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). s/The/the/ after semicolon that ends a half-sentence. Or alternatively, s/in the future;/in the future./ > > --shared[=(false|true|umask|group|all|world|everybody|0xxx)]::
Hi Junio, On Sun, 22 Nov 2020, Junio C Hamano wrote: > "Johannes Schindelin via GitGitGadget" <gitgitgadget@gmail.com> > writes: > > > 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> > > --- > > It would have been nicer to have a reference to the original patch > <xmqqd00a36wc.fsf@gitster.c.googlers.com> here after the three-dash > lines, which would have made it easier for me to say that the > updated phrasing is much better. This is unfortunately not possible with GitGitGadget, which I use because it takes away so much of my burden when contributing patches. > I do not think I deserve credit for this step in the series. Please > drop "initial-patch-by" when you do a v2. This is not about "deserving". More than half of the patch is still identical to what you wrote, I only pasted it. This is yours, not mine. > > diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt > > index 59ecda6c17..19f9f16e6b 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). > > "branch without any commits" is certainly easier to understand than > "unborn branch", which was in my weatherballoon patch. > > Stepping back a bit more, I wonder if we want to make reference to > implementation details even less, e.g. > > ... an empty Git repository---a `.git` directory to store > objects, branches and tags, hooks, and template files. > > which would be in the same spirit as not mentioning 'HEAD file'. Hmm. I'm of two minds there. On the one hand, it is nice to have a conciser description. On the other hand, it is nice to have a little bit depth in the description. For the time being, I'll leave it as-is. > > @@ -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). > > s/The/the/ after semicolon that ends a half-sentence. Or > alternatively, s/in the future;/in the future./ Okay. > > --shared[=(false|true|umask|group|all|world|everybody|0xxx)]:: Thanks for the thorough review, Dscho
diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt index 59ecda6c17..19f9f16e6b 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)]::