[PATCH] lots of documentation fixes/rewordings in git-init(1)

[PATCH] lots of documentation fixes/rewordings in git-init(1)

[Linus Arver]

Hello,

I noticed a typo in git-init(1), which led me to some related changes. All
changes are in Documentation/git-init.txt. I have cc'ed the people involved
(thanks git-blame), just to make sure that my changes maintain technical
accuracy.

I've tested out the compiled man/html/etc. files and everything seems to look
correct.

This is my first patch submission to the git project, thanks!

-L

[PATCH 1/7] Documentation: git-init: typographical fixes

[Linus Arver]

Signed-off-by: Linus Arver <linusarver@gmail.com>
---
 Documentation/git-init.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index afd721e..5ed5859 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -43,7 +43,7 @@ OPTIONS
 -q::
 --quiet::
 
-Only print error and warning messages, all other output will be suppressed.
+Only print error and warning messages; all other output will be suppressed.
 
 --bare::
 
@@ -97,7 +97,7 @@ is given:
    create a repo that is readable and writable to the current user and group,
    but inaccessible to others.
 
-By default, the configuration flag receive.denyNonFastForwards is enabled
+By default, the configuration flag 'receive.denyNonFastForwards' is enabled
 in shared repositories, so that you cannot force a non fast-forwarding push
 into it.
 
@@ -113,7 +113,7 @@ TEMPLATE DIRECTORY
 The template directory contains files and directories that will be copied to
 the `$GIT_DIR` after it is created.
 
-The template directory used will (in order):
+The template directory used will be (in order):
 
  - The argument given with the `--template` option.
 
-- 
2.0.3

Re: [PATCH 1/7] Documentation: git-init: typographical fixes

[Junio C Hamano]

Linus Arver <linusarver@gmail.com> writes:

> Signed-off-by: Linus Arver <linusarver@gmail.com>
> ---
>  Documentation/git-init.txt | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
> index afd721e..5ed5859 100644
> --- a/Documentation/git-init.txt
> +++ b/Documentation/git-init.txt
> @@ -43,7 +43,7 @@ OPTIONS
>  -q::
>  --quiet::
>  
> -Only print error and warning messages, all other output will be suppressed.
> +Only print error and warning messages; all other output will be suppressed.

OK.

>  --bare::
>  
> @@ -97,7 +97,7 @@ is given:
>     create a repo that is readable and writable to the current user and group,
>     but inaccessible to others.
>  
> -By default, the configuration flag receive.denyNonFastForwards is enabled
> +By default, the configuration flag 'receive.denyNonFastForwards' is enabled
>  in shared repositories, so that you cannot force a non fast-forwarding push
>  into it.

If you are going to quote something that the user should literally
use, it is probably better to use `backticks` so that the quoted
contents will be typeset in monospaced typewriter-font.

> @@ -113,7 +113,7 @@ TEMPLATE DIRECTORY
>  The template directory contains files and directories that will be copied to
>  the `$GIT_DIR` after it is created.
>  
> -The template directory used will (in order):
> +The template directory used will be (in order):
>  
>   - The argument given with the `--template` option.

OK.

Thanks.

Re: [PATCH 1/7] Documentation: git-init: typographical fixes

[Linus Arver]

On Tue, Aug 05, 2014 at 03:06:00PM -0700, Junio C Hamano wrote:
> Linus Arver <linusarver@gmail.com> writes:
> 
> > Signed-off-by: Linus Arver <linusarver@gmail.com>
> > ---
> >  Documentation/git-init.txt | 6 +++---
> >  1 file changed, 3 insertions(+), 3 deletions(-)
> >
> > diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
> > index afd721e..5ed5859 100644
> > --- a/Documentation/git-init.txt
> > +++ b/Documentation/git-init.txt
> > @@ -43,7 +43,7 @@ OPTIONS
> >  -q::
> >  --quiet::
> >  
> > -Only print error and warning messages, all other output will be suppressed.
> > +Only print error and warning messages; all other output will be suppressed.
> 
> OK.
> 
> >  --bare::
> >  
> > @@ -97,7 +97,7 @@ is given:
> >     create a repo that is readable and writable to the current user and group,
> >     but inaccessible to others.
> >  
> > -By default, the configuration flag receive.denyNonFastForwards is enabled
> > +By default, the configuration flag 'receive.denyNonFastForwards' is enabled
> >  in shared repositories, so that you cannot force a non fast-forwarding push
> >  into it.
> 
> If you are going to quote something that the user should literally
> use, it is probably better to use `backticks` so that the quoted
> contents will be typeset in monospaced typewriter-font.

OK, that is simple to change.

> > @@ -113,7 +113,7 @@ TEMPLATE DIRECTORY
> >  The template directory contains files and directories that will be copied to
> >  the `$GIT_DIR` after it is created.
> >  
> > -The template directory used will (in order):
> > +The template directory used will be (in order):
> >  
> >   - The argument given with the `--template` option.
> 
> OK.
> 
> Thanks.

[PATCH 2/7] Documentation: git-init: list items facelift

[Linus Arver]

No textual change.

Signed-off-by: Linus Arver <linusarver@gmail.com>
---
 Documentation/git-init.txt | 49 ++++++++++++++++++++++++++--------------------
 1 file changed, 28 insertions(+), 21 deletions(-)

diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index 5ed5859..45501d0 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -72,30 +72,37 @@ repository.  When specified, the config variable "core.sharedRepository" is
 set so that files and directories under `$GIT_DIR` are created with the
 requested permissions.  When not specified, Git will use permissions reported
 by umask(2).
-
++
 The option can have the following values, defaulting to 'group' if no value
 is given:
++
+--
+'umask' (or 'false')::
+
+Use permissions reported by umask(2). The default, when `--shared` is not
+specified.
+
+'group' (or 'true')::
 
- - 'umask' (or 'false'): Use permissions reported by umask(2). The default,
-   when `--shared` is not specified.
-
- - 'group' (or 'true'): Make the repository group-writable, (and g+sx, since
-   the git group may be not the primary group of all users).
-   This is used to loosen the permissions of an otherwise safe umask(2) value.
-   Note that the umask still applies to the other permission bits (e.g. if
-   umask is '0022', using 'group' will not remove read privileges from other
-   (non-group) users). See '0xxx' for how to exactly specify the repository
-   permissions.
-
- - 'all' (or 'world' or 'everybody'): Same as 'group', but make the repository
-   readable by all users.
-
- - '0xxx': '0xxx' is an octal number and each file will have mode '0xxx'.
-   '0xxx' will override users' umask(2) value (and not only loosen permissions
-   as 'group' and 'all' does). '0640' will create a repository which is
-   group-readable, but not group-writable or accessible to others. '0660' will
-   create a repo that is readable and writable to the current user and group,
-   but inaccessible to others.
+Make the repository group-writable, (and g+sx, since the git group may be not
+the primary group of all users). This is used to loosen the permissions of an
+otherwise safe umask(2) value. Note that the umask still applies to the other
+permission bits (e.g. if umask is '0022', using 'group' will not remove read
+privileges from other (non-group) users). See '0xxx' for how to exactly specify
+the repository permissions.
+
+'all' (or 'world' or 'everybody')::
+
+Same as 'group', but make the repository readable by all users.
+
+'0xxx'::
+
+'0xxx' is an octal number and each file will have mode '0xxx'. '0xxx' will
+override users' umask(2) value (and not only loosen permissions as 'group' and
+'all' does). '0640' will create a repository which is group-readable, but not
+group-writable or accessible to others. '0660' will create a repo that is
+readable and writable to the current user and group, but inaccessible to others.
+--
 
 By default, the configuration flag 'receive.denyNonFastForwards' is enabled
 in shared repositories, so that you cannot force a non fast-forwarding push
-- 
2.0.3

[PATCH 3/7] Documentation: git-init: template directory: reword

[Linus Arver]

Signed-off-by: Linus Arver <linusarver@gmail.com>
---
 Documentation/git-init.txt | 14 +++++---------
 1 file changed, 5 insertions(+), 9 deletions(-)

diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index 45501d0..f21b85b 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -113,22 +113,18 @@ line, the command is run inside the directory (possibly after creating it).
 
 --
 
-
 TEMPLATE DIRECTORY
 ------------------
 
 The template directory contains files and directories that will be copied to
 the `$GIT_DIR` after it is created.
 
-The template directory used will be (in order):
-
- - The argument given with the `--template` option.
-
- - The contents of the `$GIT_TEMPLATE_DIR` environment variable.
-
- - The `init.templatedir` configuration variable.
+The template directory will be one of the following (in order):
 
- - The default template directory: `/usr/share/git-core/templates`.
+- the argument given with the `--template` option;
+- the contents of the `$GIT_TEMPLATE_DIR` environment variable;
+- the `init.templatedir` configuration variable; or
+- the default template directory: `/usr/share/git-core/templates`.
 
 The default template directory includes some directory structure, some
 suggested "exclude patterns", and copies of sample "hook" files.
-- 
2.0.3

Re: [PATCH 3/7] Documentation: git-init: template directory: reword

[Junio C Hamano]

Linus Arver <linusarver@gmail.com> writes:

> Signed-off-by: Linus Arver <linusarver@gmail.com>
> ---

This seems to reword and also reformat at the same time, but was the
latter change (i.e. to unindent the bulletted items and to remove
blank lines between items) necessary?

>  Documentation/git-init.txt | 14 +++++---------
>  1 file changed, 5 insertions(+), 9 deletions(-)
>
> diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
> index 45501d0..f21b85b 100644
> --- a/Documentation/git-init.txt
> +++ b/Documentation/git-init.txt
> @@ -113,22 +113,18 @@ line, the command is run inside the directory (possibly after creating it).
>  
>  --
>  
> -
>  TEMPLATE DIRECTORY
>  ------------------
>  
>  The template directory contains files and directories that will be copied to
>  the `$GIT_DIR` after it is created.
>  
> -The template directory used will be (in order):
> -
> - - The argument given with the `--template` option.
> -
> - - The contents of the `$GIT_TEMPLATE_DIR` environment variable.
> -
> - - The `init.templatedir` configuration variable.
> +The template directory will be one of the following (in order):
>  
> - - The default template directory: `/usr/share/git-core/templates`.
> +- the argument given with the `--template` option;
> +- the contents of the `$GIT_TEMPLATE_DIR` environment variable;
> +- the `init.templatedir` configuration variable; or
> +- the default template directory: `/usr/share/git-core/templates`.
>  
>  The default template directory includes some directory structure, some
>  suggested "exclude patterns", and copies of sample "hook" files.

Re: [PATCH 3/7] Documentation: git-init: template directory: reword

[Linus Arver]

On Tue, Aug 05, 2014 at 03:10:30PM -0700, Junio C Hamano wrote:
> Linus Arver <linusarver@gmail.com> writes:
> 
> > Signed-off-by: Linus Arver <linusarver@gmail.com>
> > ---
> 
> This seems to reword and also reformat at the same time, but was the
> latter change (i.e. to unindent the bulletted items and to remove
> blank lines between items) necessary?

No, the unindenting/removal of blank lines is a non-grammar change and
is not necessary, as it doesn't have any effect on the actual output
(html/txt/manpage).

I can either keep the same coding style with the rewording, or chop this
into two commits, one for the rewording and another for reformatting.
Which one do you suggest?

> >  Documentation/git-init.txt | 14 +++++---------
> >  1 file changed, 5 insertions(+), 9 deletions(-)
> >
> > diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
> > index 45501d0..f21b85b 100644
> > --- a/Documentation/git-init.txt
> > +++ b/Documentation/git-init.txt
> > @@ -113,22 +113,18 @@ line, the command is run inside the directory (possibly after creating it).
> >  
> >  --
> >  
> > -
> >  TEMPLATE DIRECTORY
> >  ------------------
> >  
> >  The template directory contains files and directories that will be copied to
> >  the `$GIT_DIR` after it is created.
> >  
> > -The template directory used will be (in order):
> > -
> > - - The argument given with the `--template` option.
> > -
> > - - The contents of the `$GIT_TEMPLATE_DIR` environment variable.
> > -
> > - - The `init.templatedir` configuration variable.
> > +The template directory will be one of the following (in order):
> >  
> > - - The default template directory: `/usr/share/git-core/templates`.
> > +- the argument given with the `--template` option;
> > +- the contents of the `$GIT_TEMPLATE_DIR` environment variable;
> > +- the `init.templatedir` configuration variable; or
> > +- the default template directory: `/usr/share/git-core/templates`.
> >  
> >  The default template directory includes some directory structure, some
> >  suggested "exclude patterns", and copies of sample "hook" files.

Re: [PATCH 3/7] Documentation: git-init: template directory: reword

[Junio C Hamano]

Linus Arver <linusarver@gmail.com> writes:

> No, the unindenting/removal of blank lines is a non-grammar change and
> is not necessary, as it doesn't have any effect on the actual output
> (html/txt/manpage).
>
> I can either keep the same coding style with the rewording, or chop this
> into two commits, one for the rewording and another for reformatting.
> Which one do you suggest?

If I were doing this change, I wouldn't touch the formatting,
because I did not find that the reformatted version would be any
easier to read or maintain compared to the original.

But I suspect that you must have thought the reformatting was a good
thing to do for a reason, and I suspected I might have been missing
something obvious to you, and that was why I asked.  If there is a
good reason to reformat, then lets hear it in the commit log message
of one of the two patches.  Otherwise we can drop the reformatting
part.

So my suggestion would be a patch #1 to reword, and optionally
another patch #2 to reformat on top, if (and only if) there is a
good reason to reformat.

Re: [PATCH 3/7] Documentation: git-init: template directory: reword

[Linus Arver]

On Wed, Aug 06, 2014 at 10:21:33AM -0700, Junio C Hamano wrote:
> Linus Arver <linusarver@gmail.com> writes:
> 
> > No, the unindenting/removal of blank lines is a non-grammar change and
> > is not necessary, as it doesn't have any effect on the actual output
> > (html/txt/manpage).
> >
> > I can either keep the same coding style with the rewording, or chop this
> > into two commits, one for the rewording and another for reformatting.
> > Which one do you suggest?
> 
> If I were doing this change, I wouldn't touch the formatting,
> because I did not find that the reformatted version would be any
> easier to read or maintain compared to the original.
> 
> But I suspect that you must have thought the reformatting was a good
> thing to do for a reason, and I suspected I might have been missing
> something obvious to you, and that was why I asked.  If there is a
> good reason to reformat, then lets hear it in the commit log message
> of one of the two patches.  Otherwise we can drop the reformatting
> part.

And well, considering that the rewording makes the separate items into a
single sentence, I thought it would help readability to delete all the
whitespace.

In retrospect, I don't think this is a good enough reason to reformat.
It was more of a personal writing style judgment call. I am dropping the
reformatting part.

[PATCH 4/7] Documentation: git-init: --separate-git-dir: clarify

[Linus Arver]

Signed-off-by: Linus Arver <linusarver@gmail.com>
---
 Documentation/git-init.txt | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index f21b85b..bf0a7ae 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -57,12 +57,12 @@ DIRECTORY" section below.)
 
 --separate-git-dir=<git dir>::
 
-Instead of initializing the repository where it is supposed to be,
-place a filesytem-agnostic Git symbolic link there, pointing to the
-specified path, and initialize a Git repository at the path. The
-result is Git repository can be separated from working tree. If this
-is reinitialization, the repository will be moved to the specified
-path.
+Separate the Git repository from your working tree.  Instead of initializing the
+repository as a directory to either `$GIT_DIR` or `./.git/`, create a text file
+there containing the path to the actual repository.  This file acts as
+filesystem-agnostic Git symbolic link to the repository.
++
+If this is reinitialization, the repository will be moved to the specified path.
 
 --shared[=(false|true|umask|group|all|world|everybody|0xxx)]::
 
-- 
2.0.3

Re: [PATCH 4/7] Documentation: git-init: --separate-git-dir: clarify

[Junio C Hamano]

Linus Arver <linusarver@gmail.com> writes:

> Signed-off-by: Linus Arver <linusarver@gmail.com>
> ---

You would need to work on your justification skills ;-) in the log
message.  What does this change "clarify" and in what way?

>  Documentation/git-init.txt | 12 ++++++------
>  1 file changed, 6 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
> index f21b85b..bf0a7ae 100644
> --- a/Documentation/git-init.txt
> +++ b/Documentation/git-init.txt
> @@ -57,12 +57,12 @@ DIRECTORY" section below.)
>  
>  --separate-git-dir=<git dir>::
>  
> -Instead of initializing the repository where it is supposed to be,
> -place a filesytem-agnostic Git symbolic link there, pointing to the
> -specified path, and initialize a Git repository at the path. The
> -result is Git repository can be separated from working tree. If this
> -is reinitialization, the repository will be moved to the specified
> -path.
> +Separate the Git repository from your working tree.  Instead of initializing the
> +repository as a directory to either `$GIT_DIR` or `./.git/`, create a text file
> +there containing the path to the actual repository.  This file acts as
> +filesystem-agnostic Git symbolic link to the repository.
> ++
> +If this is reinitialization, the repository will be moved to the specified path.
>  
>  --shared[=(false|true|umask|group|all|world|everybody|0xxx)]::

Re: [PATCH 4/7] Documentation: git-init: --separate-git-dir: clarify

[Linus Arver]

On Tue, Aug 05, 2014 at 03:12:21PM -0700, Junio C Hamano wrote:
> Linus Arver <linusarver@gmail.com> writes:
> 
> > Signed-off-by: Linus Arver <linusarver@gmail.com>
> > ---
> 
> You would need to work on your justification skills ;-) in the log
> message.  What does this change "clarify" and in what way?

Oops, sorry. I guess I should have written some more information in the
commit message, something like this:

    Use shorter sentences to describe what actually happens. We describe
    what the term "Git symbolic link" actually means.

    Also, we separate out the description of the behavioral change upon
    reinitialization into its own paragraph.

> >  Documentation/git-init.txt | 12 ++++++------
> >  1 file changed, 6 insertions(+), 6 deletions(-)
> >
> > diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
> > index f21b85b..bf0a7ae 100644
> > --- a/Documentation/git-init.txt
> > +++ b/Documentation/git-init.txt
> > @@ -57,12 +57,12 @@ DIRECTORY" section below.)
> >  
> >  --separate-git-dir=<git dir>::
> >  
> > -Instead of initializing the repository where it is supposed to be,
> > -place a filesytem-agnostic Git symbolic link there, pointing to the
> > -specified path, and initialize a Git repository at the path. The
> > -result is Git repository can be separated from working tree. If this
> > -is reinitialization, the repository will be moved to the specified
> > -path.
> > +Separate the Git repository from your working tree.  Instead of initializing the
> > +repository as a directory to either `$GIT_DIR` or `./.git/`, create a text file
> > +there containing the path to the actual repository.  This file acts as
> > +filesystem-agnostic Git symbolic link to the repository.
> > ++
> > +If this is reinitialization, the repository will be moved to the specified path.
> >  
> >  --shared[=(false|true|umask|group|all|world|everybody|0xxx)]::

Re: [PATCH 4/7] Documentation: git-init: --separate-git-dir: clarify

[Junio C Hamano]

Linus Arver <linusarver@gmail.com> writes:

> On Tue, Aug 05, 2014 at 03:12:21PM -0700, Junio C Hamano wrote:
>> Linus Arver <linusarver@gmail.com> writes:
>> 
>> > Signed-off-by: Linus Arver <linusarver@gmail.com>
>> > ---
>> 
>> You would need to work on your justification skills ;-) in the log
>> message.  What does this change "clarify" and in what way?
>
> Oops, sorry. I guess I should have written some more information in the
> commit message, something like this:
>
>     Use shorter sentences to describe what actually happens. We describe
>     what the term "Git symbolic link" actually means.
>
>     Also, we separate out the description of the behavioral change upon
>     reinitialization into its own paragraph.

Sounds very sensible.

>> >  Documentation/git-init.txt | 12 ++++++------
>> >  1 file changed, 6 insertions(+), 6 deletions(-)
>> >
>> > diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
>> > index f21b85b..bf0a7ae 100644
>> > --- a/Documentation/git-init.txt
>> > +++ b/Documentation/git-init.txt
>> > @@ -57,12 +57,12 @@ DIRECTORY" section below.)
>> >  
>> >  --separate-git-dir=<git dir>::
>> >  
>> > -Instead of initializing the repository where it is supposed to be,
>> > -place a filesytem-agnostic Git symbolic link there, pointing to the
>> > -specified path, and initialize a Git repository at the path. The
>> > -result is Git repository can be separated from working tree. If this
>> > -is reinitialization, the repository will be moved to the specified
>> > -path.
>> > +Separate the Git repository from your working tree.  Instead of initializing the
>> > +repository as a directory to either `$GIT_DIR` or `./.git/`, create a text file
>> > +there containing the path to the actual repository.  This file acts as
>> > +filesystem-agnostic Git symbolic link to the repository.

While I agree that it is a very good idea to state "what it does,
what it is for" with the very first sentence of the paragraph,
"separate the git repository from your working tree" does not say
much more than the name of the option "--separate-git-dir" already
tells the reader.  And I do not offhand think of a better version
(and obviously I didn't think of any when the current text was
reviewed and committed).  The second sentence in your version is
definitely an improvement over the first and the second sentences of
the original ("where it is supposed to be" does not give any new
information to those who don't know, and does not help those who
already know).

Perhaps we can simply remove the first sentence from your version?

>> > +If this is reinitialization, the repository will be moved to the specified path.
>> >  
>> >  --shared[=(false|true|umask|group|all|world|everybody|0xxx)]::

Re: [PATCH 4/7] Documentation: git-init: --separate-git-dir: clarify

[Linus Arver]

On Wed, Aug 06, 2014 at 10:35:31AM -0700, Junio C Hamano wrote:
> While I agree that it is a very good idea to state "what it does,
> what it is for" with the very first sentence of the paragraph,
> "separate the git repository from your working tree" does not say
> much more than the name of the option "--separate-git-dir" already
> tells the reader.

Ah, I see.

> And I do not offhand think of a better version
> (and obviously I didn't think of any when the current text was
> reviewed and committed).  The second sentence in your version is
> definitely an improvement over the first and the second sentences of
> the original ("where it is supposed to be" does not give any new
> information to those who don't know, and does not help those who
> already know).

OK.

> Perhaps we can simply remove the first sentence from your version?

Yes, I agree. I enjoy cutting excess verbiage.

[PATCH 5/7] Documentation: git-init: reword parenthetical statements

[Linus Arver]

Signed-off-by: Linus Arver <linusarver@gmail.com>
---
 Documentation/git-init.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index bf0a7ae..96d6e67 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -108,8 +108,8 @@ By default, the configuration flag 'receive.denyNonFastForwards' is enabled
 in shared repositories, so that you cannot force a non fast-forwarding push
 into it.
 
-If you name a (possibly non-existent) directory at the end of the command
-line, the command is run inside the directory (possibly after creating it).
+If you provide a 'directory', the command is run inside it. If this directory
+does not exist, it will be created.
 
 --
 
-- 
2.0.3

[PATCH 6/7] Documentation: git-init: template directory: reword and cross-reference

[Linus Arver]

Signed-off-by: Linus Arver <linusarver@gmail.com>
---
 Documentation/git-init.txt | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index 96d6e67..b94d165 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -126,9 +126,8 @@ The template directory will be one of the following (in order):
 - the `init.templatedir` configuration variable; or
 - the default template directory: `/usr/share/git-core/templates`.
 
-The default template directory includes some directory structure, some
-suggested "exclude patterns", and copies of sample "hook" files.
-The suggested patterns and hook files are all modifiable and extensible.
+The default template directory includes some directory structure, suggested
+"exclude patterns" (see linkgit:gitignore[5]), and sample hook files (see linkgit:githooks[5]).
 
 EXAMPLES
 --------
-- 
2.0.3

[PATCH 7/7] Documentation: git-init: flesh out example

[Linus Arver]

Signed-off-by: Linus Arver <linusarver@gmail.com>
---
 Documentation/git-init.txt | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index b94d165..16e9f9c 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -138,10 +138,12 @@ Start a new Git repository for an existing code base::
 $ cd /path/to/my/codebase
 $ git init      <1>
 $ git add .     <2>
+$ git commit    <3>
 ----------------
 +
-<1> prepare /path/to/my/codebase/.git directory
-<2> add all existing file to the index
+<1> Create a /path/to/my/codebase/.git directory.
+<2> Add all existing files to the index.
+<3> Create the first root-commit.
 
 GIT
 ---
-- 
2.0.3

Re: [PATCH 7/7] Documentation: git-init: flesh out example

[Junio C Hamano]

Linus Arver <linusarver@gmail.com> writes:

> Signed-off-by: Linus Arver <linusarver@gmail.com>
> ---
>  Documentation/git-init.txt | 6 ++++--
>  1 file changed, 4 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
> index b94d165..16e9f9c 100644
> --- a/Documentation/git-init.txt
> +++ b/Documentation/git-init.txt
> @@ -138,10 +138,12 @@ Start a new Git repository for an existing code base::
>  $ cd /path/to/my/codebase
>  $ git init      <1>
>  $ git add .     <2>
> +$ git commit    <3>

I agree it is a good discipline to make the initial "pristine"
import immediately after "git add ." without doing anything else.
Perhaps the description below wants to make it more explicit?

>  ----------------
>  +
> -<1> prepare /path/to/my/codebase/.git directory
> -<2> add all existing file to the index
> +<1> Create a /path/to/my/codebase/.git directory.
> +<2> Add all existing files to the index.
> +<3> Create the first root-commit.
>  
>  GIT
>  ---

Re: [PATCH 7/7] Documentation: git-init: flesh out example

[Linus Arver]

On Tue, Aug 05, 2014 at 03:14:48PM -0700, Junio C Hamano wrote:
> Linus Arver <linusarver@gmail.com> writes:
> 
> > Signed-off-by: Linus Arver <linusarver@gmail.com>
> > ---
> >  Documentation/git-init.txt | 6 ++++--
> >  1 file changed, 4 insertions(+), 2 deletions(-)
> >
> > diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
> > index b94d165..16e9f9c 100644
> > --- a/Documentation/git-init.txt
> > +++ b/Documentation/git-init.txt
> > @@ -138,10 +138,12 @@ Start a new Git repository for an existing code base::
> >  $ cd /path/to/my/codebase
> >  $ git init      <1>
> >  $ git add .     <2>
> > +$ git commit    <3>
> 
> I agree it is a good discipline to make the initial "pristine"
> import immediately after "git add ." without doing anything else.
> Perhaps the description below wants to make it more explicit?
> 

I could add a comment like the following:

    For new repositories, creating a commit immediately after "git add
    ." is good practice as it will cleanly separate any preexisting work
    (done under some other VCS, for example) from any new work done with
    git.

Does this make sense? I am not sure how explicit you want it to be, or
whether I captured what you wanted to be explained.

Actually, I would like to know if anything is special about the
"root-commit" (I only know it is written as such, with a hyphen, because
that is what you get from git's output message). I am not sure if this
"root-commit" idea is explained in detail in git's other documentation.
> >  ----------------
> >  +
> > -<1> prepare /path/to/my/codebase/.git directory
> > -<2> add all existing file to the index
> > +<1> Create a /path/to/my/codebase/.git directory.
> > +<2> Add all existing files to the index.
> > +<3> Create the first root-commit.
> >  
> >  GIT
> >  ---

Re: [PATCH 7/7] Documentation: git-init: flesh out example

[Junio C Hamano]

Linus Arver <linusarver@gmail.com> writes:

> On Tue, Aug 05, 2014 at 03:14:48PM -0700, Junio C Hamano wrote:
>> Linus Arver <linusarver@gmail.com> writes:
>> 
>> > Signed-off-by: Linus Arver <linusarver@gmail.com>
>> > ---
>> >  Documentation/git-init.txt | 6 ++++--
>> >  1 file changed, 4 insertions(+), 2 deletions(-)
>> >
>> > diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
>> > index b94d165..16e9f9c 100644
>> > --- a/Documentation/git-init.txt
>> > +++ b/Documentation/git-init.txt
>> > @@ -138,10 +138,12 @@ Start a new Git repository for an existing code base::
>> >  $ cd /path/to/my/codebase
>> >  $ git init      <1>
>> >  $ git add .     <2>
>> > +$ git commit    <3>
>> 
>> I agree it is a good discipline to make the initial "pristine"
>> import immediately after "git add ." without doing anything else.
>> Perhaps the description below wants to make it more explicit?
>> 
>
> I could add a comment like the following:
>
>     For new repositories, creating a commit immediately after "git add
>     ." is good practice as it will cleanly separate any preexisting work
>     (done under some other VCS, for example) from any new work done with
>     git.
>
> Does this make sense? I am not sure how explicit you want it to be, or
> whether I captured what you wanted to be explained.

I was thinking more along the lines of

    <3> Record the pristine state as the first commit in the history.

which should suffice without becoming excessively verbose.

> Actually, I would like to know if anything is special about the
> "root-commit"...

As far as Git is concerned, they are just ordinary commits without
any parents.  A commit in Git can have zero or more parents, so from
that "structural" point of view, they are not that special.

They are considered special by users because they represent the
beginning of the project history.

Re: [PATCH 7/7] Documentation: git-init: flesh out example

[Linus Arver]

On Wed, Aug 06, 2014 at 10:41:10AM -0700, Junio C Hamano wrote:
> Linus Arver <linusarver@gmail.com> writes:
> 
> > On Tue, Aug 05, 2014 at 03:14:48PM -0700, Junio C Hamano wrote:
> >> Linus Arver <linusarver@gmail.com> writes:
> >> 
> >> > Signed-off-by: Linus Arver <linusarver@gmail.com>
> >> > ---
> >> >  Documentation/git-init.txt | 6 ++++--
> >> >  1 file changed, 4 insertions(+), 2 deletions(-)
> >> >
> >> > diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
> >> > index b94d165..16e9f9c 100644
> >> > --- a/Documentation/git-init.txt
> >> > +++ b/Documentation/git-init.txt
> >> > @@ -138,10 +138,12 @@ Start a new Git repository for an existing code base::
> >> >  $ cd /path/to/my/codebase
> >> >  $ git init      <1>
> >> >  $ git add .     <2>
> >> > +$ git commit    <3>
> >> 
> >> I agree it is a good discipline to make the initial "pristine"
> >> import immediately after "git add ." without doing anything else.
> >> Perhaps the description below wants to make it more explicit?
> >> 
> >
> > I could add a comment like the following:
> >
> >     For new repositories, creating a commit immediately after "git add
> >     ." is good practice as it will cleanly separate any preexisting work
> >     (done under some other VCS, for example) from any new work done with
> >     git.
> >
> > Does this make sense? I am not sure how explicit you want it to be, or
> > whether I captured what you wanted to be explained.
> 
> I was thinking more along the lines of
> 
>     <3> Record the pristine state as the first commit in the history.
> 
> which should suffice without becoming excessively verbose.

Ah yes, I like the brevity.

> > Actually, I would like to know if anything is special about the
> > "root-commit"...
> 
> As far as Git is concerned, they are just ordinary commits without
> any parents.  A commit in Git can have zero or more parents, so from
> that "structural" point of view, they are not that special.
> 
> They are considered special by users because they represent the
> beginning of the project history.

Thank you for the insight. I won't bother adding a blurb about
"root-commit" and what it means because they are not that special, as
you said so yourself.

[PATCH v2] lots of documentation fixes/rewordings in git-init(1)

[Linus Arver]

Hello,

Aside from the changes stemming from the discussion, I have also separated out
some typographical changes from patches 3 and 7, and squashed them into patch
1. So, those commits are cleaner now.

[PATCH v2 1/7] Documentation: git-init: typographical fixes

[Linus Arver]

Use backticks when we quote something that the user should literally
use.

Signed-off-by: Linus Arver <linusarver@gmail.com>
---
 Documentation/git-init.txt | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index afd721e..f1f920e 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -43,7 +43,7 @@ OPTIONS
 -q::
 --quiet::
 
-Only print error and warning messages, all other output will be suppressed.
+Only print error and warning messages; all other output will be suppressed.
 
 --bare::
 
@@ -97,7 +97,7 @@ is given:
    create a repo that is readable and writable to the current user and group,
    but inaccessible to others.
 
-By default, the configuration flag receive.denyNonFastForwards is enabled
+By default, the configuration flag `receive.denyNonFastForwards` is enabled
 in shared repositories, so that you cannot force a non fast-forwarding push
 into it.
 
@@ -106,14 +106,13 @@ line, the command is run inside the directory (possibly after creating it).
 
 --
 
-
 TEMPLATE DIRECTORY
 ------------------
 
 The template directory contains files and directories that will be copied to
 the `$GIT_DIR` after it is created.
 
-The template directory used will (in order):
+The template directory used will be (in order):
 
  - The argument given with the `--template` option.
 
@@ -138,8 +137,8 @@ $ git init      <1>
 $ git add .     <2>
 ----------------
 +
-<1> prepare /path/to/my/codebase/.git directory
-<2> add all existing file to the index
+<1> Create a /path/to/my/codebase/.git directory.
+<2> Add all existing files to the index.
 
 GIT
 ---
-- 
2.0.4

[PATCH v2 2/7] Documentation: git-init: list items facelift

[Linus Arver]

No textual change.

Signed-off-by: Linus Arver <linusarver@gmail.com>
---
 Documentation/git-init.txt | 49 ++++++++++++++++++++++++++--------------------
 1 file changed, 28 insertions(+), 21 deletions(-)

diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index f1f920e..c02ccd0 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -72,30 +72,37 @@ repository.  When specified, the config variable "core.sharedRepository" is
 set so that files and directories under `$GIT_DIR` are created with the
 requested permissions.  When not specified, Git will use permissions reported
 by umask(2).
-
++
 The option can have the following values, defaulting to 'group' if no value
 is given:
++
+--
+'umask' (or 'false')::
+
+Use permissions reported by umask(2). The default, when `--shared` is not
+specified.
+
+'group' (or 'true')::
 
- - 'umask' (or 'false'): Use permissions reported by umask(2). The default,
-   when `--shared` is not specified.
-
- - 'group' (or 'true'): Make the repository group-writable, (and g+sx, since
-   the git group may be not the primary group of all users).
-   This is used to loosen the permissions of an otherwise safe umask(2) value.
-   Note that the umask still applies to the other permission bits (e.g. if
-   umask is '0022', using 'group' will not remove read privileges from other
-   (non-group) users). See '0xxx' for how to exactly specify the repository
-   permissions.
-
- - 'all' (or 'world' or 'everybody'): Same as 'group', but make the repository
-   readable by all users.
-
- - '0xxx': '0xxx' is an octal number and each file will have mode '0xxx'.
-   '0xxx' will override users' umask(2) value (and not only loosen permissions
-   as 'group' and 'all' does). '0640' will create a repository which is
-   group-readable, but not group-writable or accessible to others. '0660' will
-   create a repo that is readable and writable to the current user and group,
-   but inaccessible to others.
+Make the repository group-writable, (and g+sx, since the git group may be not
+the primary group of all users). This is used to loosen the permissions of an
+otherwise safe umask(2) value. Note that the umask still applies to the other
+permission bits (e.g. if umask is '0022', using 'group' will not remove read
+privileges from other (non-group) users). See '0xxx' for how to exactly specify
+the repository permissions.
+
+'all' (or 'world' or 'everybody')::
+
+Same as 'group', but make the repository readable by all users.
+
+'0xxx'::
+
+'0xxx' is an octal number and each file will have mode '0xxx'. '0xxx' will
+override users' umask(2) value (and not only loosen permissions as 'group' and
+'all' does). '0640' will create a repository which is group-readable, but not
+group-writable or accessible to others. '0660' will create a repo that is
+readable and writable to the current user and group, but inaccessible to others.
+--
 
 By default, the configuration flag `receive.denyNonFastForwards` is enabled
 in shared repositories, so that you cannot force a non fast-forwarding push
-- 
2.0.4

[PATCH v2 3/7] Documentation: git-init: template directory: reword

[Linus Arver]

Signed-off-by: Linus Arver <linusarver@gmail.com>
---
 Documentation/git-init.txt | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index c02ccd0..6ffe721 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -119,15 +119,15 @@ TEMPLATE DIRECTORY
 The template directory contains files and directories that will be copied to
 the `$GIT_DIR` after it is created.
 
-The template directory used will be (in order):
+The template directory will be one of the following (in order):
 
- - The argument given with the `--template` option.
+ - the argument given with the `--template` option;
 
- - The contents of the `$GIT_TEMPLATE_DIR` environment variable.
+ - the contents of the `$GIT_TEMPLATE_DIR` environment variable;
 
- - The `init.templatedir` configuration variable.
+ - the `init.templatedir` configuration variable; or
 
- - The default template directory: `/usr/share/git-core/templates`.
+ - the default template directory: `/usr/share/git-core/templates`.
 
 The default template directory includes some directory structure, some
 suggested "exclude patterns", and copies of sample "hook" files.
-- 
2.0.4

[PATCH v2 4/7] Documentation: git-init: --separate-git-dir: clarify

[Linus Arver]

Use shorter sentences to describe what actually happens. We describe
what the term "Git symbolic link" actually means.

Also, we separate out the description of the behavioral change upon
reinitialization into its own paragraph.

Signed-off-by: Linus Arver <linusarver@gmail.com>
---
 Documentation/git-init.txt | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index 6ffe721..3f4e46a 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -57,12 +57,12 @@ DIRECTORY" section below.)
 
 --separate-git-dir=<git dir>::
 
-Instead of initializing the repository where it is supposed to be,
-place a filesytem-agnostic Git symbolic link there, pointing to the
-specified path, and initialize a Git repository at the path. The
-result is Git repository can be separated from working tree. If this
-is reinitialization, the repository will be moved to the specified
-path.
+Instead of initializing the repository as a directory to either `$GIT_DIR` or
+`./.git/`, create a text file there containing the path to the actual
+repository.  This file acts as filesystem-agnostic Git symbolic link to the
+repository.
++
+If this is reinitialization, the repository will be moved to the specified path.
 
 --shared[=(false|true|umask|group|all|world|everybody|0xxx)]::
 
-- 
2.0.4

[PATCH v2 5/7] Documentation: git-init: reword parenthetical statements

[Linus Arver]

Signed-off-by: Linus Arver <linusarver@gmail.com>
---
 Documentation/git-init.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index 3f4e46a..21e5ad9 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -108,8 +108,8 @@ By default, the configuration flag `receive.denyNonFastForwards` is enabled
 in shared repositories, so that you cannot force a non fast-forwarding push
 into it.
 
-If you name a (possibly non-existent) directory at the end of the command
-line, the command is run inside the directory (possibly after creating it).
+If you provide a 'directory', the command is run inside it. If this directory
+does not exist, it will be created.
 
 --
 
-- 
2.0.4

[PATCH v2 6/7] Documentation: git-init: template directory: reword and cross-reference

[Linus Arver]

Signed-off-by: Linus Arver <linusarver@gmail.com>
---
 Documentation/git-init.txt | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index 21e5ad9..9f2c7d8 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -129,9 +129,8 @@ The template directory will be one of the following (in order):
 
  - the default template directory: `/usr/share/git-core/templates`.
 
-The default template directory includes some directory structure, some
-suggested "exclude patterns", and copies of sample "hook" files.
-The suggested patterns and hook files are all modifiable and extensible.
+The default template directory includes some directory structure, suggested
+"exclude patterns" (see linkgit:gitignore[5]), and sample hook files (see linkgit:githooks[5]).
 
 EXAMPLES
 --------
-- 
2.0.4

[PATCH v2 7/7] Documentation: git-init: flesh out example

[Linus Arver]

Add a third step `git commit` after adding files for the first time.

Signed-off-by: Linus Arver <linusarver@gmail.com>
---
 Documentation/git-init.txt | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index 9f2c7d8..369f889 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -141,10 +141,12 @@ Start a new Git repository for an existing code base::
 $ cd /path/to/my/codebase
 $ git init      <1>
 $ git add .     <2>
+$ git commit    <3>
 ----------------
 +
 <1> Create a /path/to/my/codebase/.git directory.
 <2> Add all existing files to the index.
+<3> Record the pristine state as the first commit in the history.
 
 GIT
 ---
-- 
2.0.4