All of lore.kernel.org
 help / color / mirror / Atom feed
* [PATCH] lots of documentation fixes/rewordings in git-init(1)
@ 2014-08-02 18:06 Linus Arver
  2014-08-02 18:06 ` [PATCH 1/7] Documentation: git-init: typographical fixes Linus Arver
                   ` (7 more replies)
  0 siblings, 8 replies; 30+ messages in thread
From: Linus Arver @ 2014-08-02 18:06 UTC (permalink / raw)
  To: git
  Cc: Steven Drake, Nguyễn Thái Ngọc Duy,
	Johan Herland, Nanako Shiraishi

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

^ permalink raw reply	[flat|nested] 30+ messages in thread

* [PATCH 1/7] Documentation: git-init: typographical fixes
  2014-08-02 18:06 [PATCH] lots of documentation fixes/rewordings in git-init(1) Linus Arver
@ 2014-08-02 18:06 ` Linus Arver
  2014-08-05 22:06   ` Junio C Hamano
  2014-08-02 18:06 ` [PATCH 2/7] Documentation: git-init: list items facelift Linus Arver
                   ` (6 subsequent siblings)
  7 siblings, 1 reply; 30+ messages in thread
From: Linus Arver @ 2014-08-02 18:06 UTC (permalink / raw)
  To: git
  Cc: Steven Drake, Nguyễn Thái Ngọc Duy,
	Johan Herland, Nanako Shiraishi, 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

^ permalink raw reply related	[flat|nested] 30+ messages in thread

* [PATCH 2/7] Documentation: git-init: list items facelift
  2014-08-02 18:06 [PATCH] lots of documentation fixes/rewordings in git-init(1) Linus Arver
  2014-08-02 18:06 ` [PATCH 1/7] Documentation: git-init: typographical fixes Linus Arver
@ 2014-08-02 18:06 ` Linus Arver
  2014-08-02 18:06 ` [PATCH 3/7] Documentation: git-init: template directory: reword Linus Arver
                   ` (5 subsequent siblings)
  7 siblings, 0 replies; 30+ messages in thread
From: Linus Arver @ 2014-08-02 18:06 UTC (permalink / raw)
  To: git
  Cc: Steven Drake, Nguyễn Thái Ngọc Duy,
	Johan Herland, Nanako Shiraishi, 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

^ permalink raw reply related	[flat|nested] 30+ messages in thread

* [PATCH 3/7] Documentation: git-init: template directory: reword
  2014-08-02 18:06 [PATCH] lots of documentation fixes/rewordings in git-init(1) Linus Arver
  2014-08-02 18:06 ` [PATCH 1/7] Documentation: git-init: typographical fixes Linus Arver
  2014-08-02 18:06 ` [PATCH 2/7] Documentation: git-init: list items facelift Linus Arver
@ 2014-08-02 18:06 ` Linus Arver
  2014-08-05 22:10   ` Junio C Hamano
  2014-08-02 18:06 ` [PATCH 4/7] Documentation: git-init: --separate-git-dir: clarify Linus Arver
                   ` (4 subsequent siblings)
  7 siblings, 1 reply; 30+ messages in thread
From: Linus Arver @ 2014-08-02 18:06 UTC (permalink / raw)
  To: git
  Cc: Steven Drake, Nguyễn Thái Ngọc Duy,
	Johan Herland, Nanako Shiraishi, 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

^ permalink raw reply related	[flat|nested] 30+ messages in thread

* [PATCH 4/7] Documentation: git-init: --separate-git-dir: clarify
  2014-08-02 18:06 [PATCH] lots of documentation fixes/rewordings in git-init(1) Linus Arver
                   ` (2 preceding siblings ...)
  2014-08-02 18:06 ` [PATCH 3/7] Documentation: git-init: template directory: reword Linus Arver
@ 2014-08-02 18:06 ` Linus Arver
  2014-08-05 22:12   ` Junio C Hamano
  2014-08-02 18:06 ` [PATCH 5/7] Documentation: git-init: reword parenthetical statements Linus Arver
                   ` (3 subsequent siblings)
  7 siblings, 1 reply; 30+ messages in thread
From: Linus Arver @ 2014-08-02 18:06 UTC (permalink / raw)
  To: git
  Cc: Steven Drake, Nguyễn Thái Ngọc Duy,
	Johan Herland, Nanako Shiraishi, 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

^ permalink raw reply related	[flat|nested] 30+ messages in thread

* [PATCH 5/7] Documentation: git-init: reword parenthetical statements
  2014-08-02 18:06 [PATCH] lots of documentation fixes/rewordings in git-init(1) Linus Arver
                   ` (3 preceding siblings ...)
  2014-08-02 18:06 ` [PATCH 4/7] Documentation: git-init: --separate-git-dir: clarify Linus Arver
@ 2014-08-02 18:06 ` Linus Arver
  2014-08-02 18:06 ` [PATCH 6/7] Documentation: git-init: template directory: reword and cross-reference Linus Arver
                   ` (2 subsequent siblings)
  7 siblings, 0 replies; 30+ messages in thread
From: Linus Arver @ 2014-08-02 18:06 UTC (permalink / raw)
  To: git
  Cc: Steven Drake, Nguyễn Thái Ngọc Duy,
	Johan Herland, Nanako Shiraishi, 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

^ permalink raw reply related	[flat|nested] 30+ messages in thread

* [PATCH 6/7] Documentation: git-init: template directory: reword and cross-reference
  2014-08-02 18:06 [PATCH] lots of documentation fixes/rewordings in git-init(1) Linus Arver
                   ` (4 preceding siblings ...)
  2014-08-02 18:06 ` [PATCH 5/7] Documentation: git-init: reword parenthetical statements Linus Arver
@ 2014-08-02 18:06 ` Linus Arver
  2014-08-02 18:06 ` [PATCH 7/7] Documentation: git-init: flesh out example Linus Arver
  2014-08-08 17:29 ` [PATCH v2] lots of documentation fixes/rewordings in git-init(1) Linus Arver
  7 siblings, 0 replies; 30+ messages in thread
From: Linus Arver @ 2014-08-02 18:06 UTC (permalink / raw)
  To: git
  Cc: Steven Drake, Nguyễn Thái Ngọc Duy,
	Johan Herland, Nanako Shiraishi, 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

^ permalink raw reply related	[flat|nested] 30+ messages in thread

* [PATCH 7/7] Documentation: git-init: flesh out example
  2014-08-02 18:06 [PATCH] lots of documentation fixes/rewordings in git-init(1) Linus Arver
                   ` (5 preceding siblings ...)
  2014-08-02 18:06 ` [PATCH 6/7] Documentation: git-init: template directory: reword and cross-reference Linus Arver
@ 2014-08-02 18:06 ` Linus Arver
  2014-08-05 22:14   ` Junio C Hamano
  2014-08-08 17:29 ` [PATCH v2] lots of documentation fixes/rewordings in git-init(1) Linus Arver
  7 siblings, 1 reply; 30+ messages in thread
From: Linus Arver @ 2014-08-02 18:06 UTC (permalink / raw)
  To: git
  Cc: Steven Drake, Nguyễn Thái Ngọc Duy,
	Johan Herland, Nanako Shiraishi, 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

^ permalink raw reply related	[flat|nested] 30+ messages in thread

* Re: [PATCH 1/7] Documentation: git-init: typographical fixes
  2014-08-02 18:06 ` [PATCH 1/7] Documentation: git-init: typographical fixes Linus Arver
@ 2014-08-05 22:06   ` Junio C Hamano
  2014-08-06  4:58     ` Linus Arver
  0 siblings, 1 reply; 30+ messages in thread
From: Junio C Hamano @ 2014-08-05 22:06 UTC (permalink / raw)
  To: Linus Arver
  Cc: git, Steven Drake, Nguyễn Thái Ngọc Duy,
	Johan Herland, Nanako Shiraishi

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.

^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [PATCH 3/7] Documentation: git-init: template directory: reword
  2014-08-02 18:06 ` [PATCH 3/7] Documentation: git-init: template directory: reword Linus Arver
@ 2014-08-05 22:10   ` Junio C Hamano
  2014-08-06  5:15     ` Linus Arver
  0 siblings, 1 reply; 30+ messages in thread
From: Junio C Hamano @ 2014-08-05 22:10 UTC (permalink / raw)
  To: Linus Arver; +Cc: git

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.

^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [PATCH 4/7] Documentation: git-init: --separate-git-dir: clarify
  2014-08-02 18:06 ` [PATCH 4/7] Documentation: git-init: --separate-git-dir: clarify Linus Arver
@ 2014-08-05 22:12   ` Junio C Hamano
  2014-08-06  5:21     ` Linus Arver
  0 siblings, 1 reply; 30+ messages in thread
From: Junio C Hamano @ 2014-08-05 22:12 UTC (permalink / raw)
  To: Linus Arver; +Cc: git

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)]::

^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [PATCH 7/7] Documentation: git-init: flesh out example
  2014-08-02 18:06 ` [PATCH 7/7] Documentation: git-init: flesh out example Linus Arver
@ 2014-08-05 22:14   ` Junio C Hamano
  2014-08-06  5:34     ` Linus Arver
  0 siblings, 1 reply; 30+ messages in thread
From: Junio C Hamano @ 2014-08-05 22:14 UTC (permalink / raw)
  To: Linus Arver; +Cc: git

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

^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [PATCH 1/7] Documentation: git-init: typographical fixes
  2014-08-05 22:06   ` Junio C Hamano
@ 2014-08-06  4:58     ` Linus Arver
  0 siblings, 0 replies; 30+ messages in thread
From: Linus Arver @ 2014-08-06  4:58 UTC (permalink / raw)
  To: Junio C Hamano
  Cc: git, Steven Drake, Nguyễn Thái Ngọc Duy,
	Johan Herland, Nanako Shiraishi

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.

^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [PATCH 3/7] Documentation: git-init: template directory: reword
  2014-08-05 22:10   ` Junio C Hamano
@ 2014-08-06  5:15     ` Linus Arver
  2014-08-06 17:21       ` Junio C Hamano
  0 siblings, 1 reply; 30+ messages in thread
From: Linus Arver @ 2014-08-06  5:15 UTC (permalink / raw)
  To: Junio C Hamano; +Cc: git

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.

^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [PATCH 4/7] Documentation: git-init: --separate-git-dir: clarify
  2014-08-05 22:12   ` Junio C Hamano
@ 2014-08-06  5:21     ` Linus Arver
  2014-08-06 17:35       ` Junio C Hamano
  0 siblings, 1 reply; 30+ messages in thread
From: Linus Arver @ 2014-08-06  5:21 UTC (permalink / raw)
  To: Junio C Hamano; +Cc: git

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)]::

^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [PATCH 7/7] Documentation: git-init: flesh out example
  2014-08-05 22:14   ` Junio C Hamano
@ 2014-08-06  5:34     ` Linus Arver
  2014-08-06 17:41       ` Junio C Hamano
  0 siblings, 1 reply; 30+ messages in thread
From: Linus Arver @ 2014-08-06  5:34 UTC (permalink / raw)
  To: Junio C Hamano; +Cc: git

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

^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [PATCH 3/7] Documentation: git-init: template directory: reword
  2014-08-06  5:15     ` Linus Arver
@ 2014-08-06 17:21       ` Junio C Hamano
  2014-08-08 16:36         ` Linus Arver
  0 siblings, 1 reply; 30+ messages in thread
From: Junio C Hamano @ 2014-08-06 17:21 UTC (permalink / raw)
  To: Linus Arver; +Cc: git

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.

^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [PATCH 4/7] Documentation: git-init: --separate-git-dir: clarify
  2014-08-06  5:21     ` Linus Arver
@ 2014-08-06 17:35       ` Junio C Hamano
  2014-08-08 16:42         ` Linus Arver
  0 siblings, 1 reply; 30+ messages in thread
From: Junio C Hamano @ 2014-08-06 17:35 UTC (permalink / raw)
  To: Linus Arver; +Cc: git

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)]::

^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [PATCH 7/7] Documentation: git-init: flesh out example
  2014-08-06  5:34     ` Linus Arver
@ 2014-08-06 17:41       ` Junio C Hamano
  2014-08-08 16:49         ` Linus Arver
  0 siblings, 1 reply; 30+ messages in thread
From: Junio C Hamano @ 2014-08-06 17:41 UTC (permalink / raw)
  To: Linus Arver; +Cc: git

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.

^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [PATCH 3/7] Documentation: git-init: template directory: reword
  2014-08-06 17:21       ` Junio C Hamano
@ 2014-08-08 16:36         ` Linus Arver
  0 siblings, 0 replies; 30+ messages in thread
From: Linus Arver @ 2014-08-08 16:36 UTC (permalink / raw)
  To: Junio C Hamano; +Cc: git

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.

^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [PATCH 4/7] Documentation: git-init: --separate-git-dir: clarify
  2014-08-06 17:35       ` Junio C Hamano
@ 2014-08-08 16:42         ` Linus Arver
  0 siblings, 0 replies; 30+ messages in thread
From: Linus Arver @ 2014-08-08 16:42 UTC (permalink / raw)
  To: Junio C Hamano; +Cc: git

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.

^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [PATCH 7/7] Documentation: git-init: flesh out example
  2014-08-06 17:41       ` Junio C Hamano
@ 2014-08-08 16:49         ` Linus Arver
  0 siblings, 0 replies; 30+ messages in thread
From: Linus Arver @ 2014-08-08 16:49 UTC (permalink / raw)
  To: Junio C Hamano; +Cc: git

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.

^ permalink raw reply	[flat|nested] 30+ messages in thread

* [PATCH v2] lots of documentation fixes/rewordings in git-init(1)
  2014-08-02 18:06 [PATCH] lots of documentation fixes/rewordings in git-init(1) Linus Arver
                   ` (6 preceding siblings ...)
  2014-08-02 18:06 ` [PATCH 7/7] Documentation: git-init: flesh out example Linus Arver
@ 2014-08-08 17:29 ` Linus Arver
  2014-08-08 17:29   ` [PATCH v2 1/7] Documentation: git-init: typographical fixes Linus Arver
                     ` (6 more replies)
  7 siblings, 7 replies; 30+ messages in thread
From: Linus Arver @ 2014-08-08 17:29 UTC (permalink / raw)
  To: git; +Cc: Steven Drake, Nguyễn Thái Ngọc Duy, Johan Herland

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.

^ permalink raw reply	[flat|nested] 30+ messages in thread

* [PATCH v2 1/7] Documentation: git-init: typographical fixes
  2014-08-08 17:29 ` [PATCH v2] lots of documentation fixes/rewordings in git-init(1) Linus Arver
@ 2014-08-08 17:29   ` Linus Arver
  2014-08-08 17:29   ` [PATCH v2 2/7] Documentation: git-init: list items facelift Linus Arver
                     ` (5 subsequent siblings)
  6 siblings, 0 replies; 30+ messages in thread
From: Linus Arver @ 2014-08-08 17:29 UTC (permalink / raw)
  To: git
  Cc: Steven Drake, Nguyễn Thái Ngọc Duy,
	Johan Herland, 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

^ permalink raw reply related	[flat|nested] 30+ messages in thread

* [PATCH v2 2/7] Documentation: git-init: list items facelift
  2014-08-08 17:29 ` [PATCH v2] lots of documentation fixes/rewordings in git-init(1) Linus Arver
  2014-08-08 17:29   ` [PATCH v2 1/7] Documentation: git-init: typographical fixes Linus Arver
@ 2014-08-08 17:29   ` Linus Arver
  2014-08-08 17:29   ` [PATCH v2 3/7] Documentation: git-init: template directory: reword Linus Arver
                     ` (4 subsequent siblings)
  6 siblings, 0 replies; 30+ messages in thread
From: Linus Arver @ 2014-08-08 17:29 UTC (permalink / raw)
  To: git
  Cc: Steven Drake, Nguyễn Thái Ngọc Duy,
	Johan Herland, 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

^ permalink raw reply related	[flat|nested] 30+ messages in thread

* [PATCH v2 3/7] Documentation: git-init: template directory: reword
  2014-08-08 17:29 ` [PATCH v2] lots of documentation fixes/rewordings in git-init(1) Linus Arver
  2014-08-08 17:29   ` [PATCH v2 1/7] Documentation: git-init: typographical fixes Linus Arver
  2014-08-08 17:29   ` [PATCH v2 2/7] Documentation: git-init: list items facelift Linus Arver
@ 2014-08-08 17:29   ` Linus Arver
  2014-08-08 17:29   ` [PATCH v2 4/7] Documentation: git-init: --separate-git-dir: clarify Linus Arver
                     ` (3 subsequent siblings)
  6 siblings, 0 replies; 30+ messages in thread
From: Linus Arver @ 2014-08-08 17:29 UTC (permalink / raw)
  To: git
  Cc: Steven Drake, Nguyễn Thái Ngọc Duy,
	Johan Herland, 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

^ permalink raw reply related	[flat|nested] 30+ messages in thread

* [PATCH v2 4/7] Documentation: git-init: --separate-git-dir: clarify
  2014-08-08 17:29 ` [PATCH v2] lots of documentation fixes/rewordings in git-init(1) Linus Arver
                     ` (2 preceding siblings ...)
  2014-08-08 17:29   ` [PATCH v2 3/7] Documentation: git-init: template directory: reword Linus Arver
@ 2014-08-08 17:29   ` Linus Arver
  2014-08-08 17:29   ` [PATCH v2 5/7] Documentation: git-init: reword parenthetical statements Linus Arver
                     ` (2 subsequent siblings)
  6 siblings, 0 replies; 30+ messages in thread
From: Linus Arver @ 2014-08-08 17:29 UTC (permalink / raw)
  To: git
  Cc: Steven Drake, Nguyễn Thái Ngọc Duy,
	Johan Herland, 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

^ permalink raw reply related	[flat|nested] 30+ messages in thread

* [PATCH v2 5/7] Documentation: git-init: reword parenthetical statements
  2014-08-08 17:29 ` [PATCH v2] lots of documentation fixes/rewordings in git-init(1) Linus Arver
                     ` (3 preceding siblings ...)
  2014-08-08 17:29   ` [PATCH v2 4/7] Documentation: git-init: --separate-git-dir: clarify Linus Arver
@ 2014-08-08 17:29   ` Linus Arver
  2014-08-08 17:29   ` [PATCH v2 6/7] Documentation: git-init: template directory: reword and cross-reference Linus Arver
  2014-08-08 17:29   ` [PATCH v2 7/7] Documentation: git-init: flesh out example Linus Arver
  6 siblings, 0 replies; 30+ messages in thread
From: Linus Arver @ 2014-08-08 17:29 UTC (permalink / raw)
  To: git
  Cc: Steven Drake, Nguyễn Thái Ngọc Duy,
	Johan Herland, 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

^ permalink raw reply related	[flat|nested] 30+ messages in thread

* [PATCH v2 6/7] Documentation: git-init: template directory: reword and cross-reference
  2014-08-08 17:29 ` [PATCH v2] lots of documentation fixes/rewordings in git-init(1) Linus Arver
                     ` (4 preceding siblings ...)
  2014-08-08 17:29   ` [PATCH v2 5/7] Documentation: git-init: reword parenthetical statements Linus Arver
@ 2014-08-08 17:29   ` Linus Arver
  2014-08-08 17:29   ` [PATCH v2 7/7] Documentation: git-init: flesh out example Linus Arver
  6 siblings, 0 replies; 30+ messages in thread
From: Linus Arver @ 2014-08-08 17:29 UTC (permalink / raw)
  To: git
  Cc: Steven Drake, Nguyễn Thái Ngọc Duy,
	Johan Herland, 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

^ permalink raw reply related	[flat|nested] 30+ messages in thread

* [PATCH v2 7/7] Documentation: git-init: flesh out example
  2014-08-08 17:29 ` [PATCH v2] lots of documentation fixes/rewordings in git-init(1) Linus Arver
                     ` (5 preceding siblings ...)
  2014-08-08 17:29   ` [PATCH v2 6/7] Documentation: git-init: template directory: reword and cross-reference Linus Arver
@ 2014-08-08 17:29   ` Linus Arver
  6 siblings, 0 replies; 30+ messages in thread
From: Linus Arver @ 2014-08-08 17:29 UTC (permalink / raw)
  To: git
  Cc: Steven Drake, Nguyễn Thái Ngọc Duy,
	Johan Herland, 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

^ permalink raw reply related	[flat|nested] 30+ messages in thread

end of thread, other threads:[~2014-08-08 17:30 UTC | newest]

Thread overview: 30+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2014-08-02 18:06 [PATCH] lots of documentation fixes/rewordings in git-init(1) Linus Arver
2014-08-02 18:06 ` [PATCH 1/7] Documentation: git-init: typographical fixes Linus Arver
2014-08-05 22:06   ` Junio C Hamano
2014-08-06  4:58     ` Linus Arver
2014-08-02 18:06 ` [PATCH 2/7] Documentation: git-init: list items facelift Linus Arver
2014-08-02 18:06 ` [PATCH 3/7] Documentation: git-init: template directory: reword Linus Arver
2014-08-05 22:10   ` Junio C Hamano
2014-08-06  5:15     ` Linus Arver
2014-08-06 17:21       ` Junio C Hamano
2014-08-08 16:36         ` Linus Arver
2014-08-02 18:06 ` [PATCH 4/7] Documentation: git-init: --separate-git-dir: clarify Linus Arver
2014-08-05 22:12   ` Junio C Hamano
2014-08-06  5:21     ` Linus Arver
2014-08-06 17:35       ` Junio C Hamano
2014-08-08 16:42         ` Linus Arver
2014-08-02 18:06 ` [PATCH 5/7] Documentation: git-init: reword parenthetical statements Linus Arver
2014-08-02 18:06 ` [PATCH 6/7] Documentation: git-init: template directory: reword and cross-reference Linus Arver
2014-08-02 18:06 ` [PATCH 7/7] Documentation: git-init: flesh out example Linus Arver
2014-08-05 22:14   ` Junio C Hamano
2014-08-06  5:34     ` Linus Arver
2014-08-06 17:41       ` Junio C Hamano
2014-08-08 16:49         ` Linus Arver
2014-08-08 17:29 ` [PATCH v2] lots of documentation fixes/rewordings in git-init(1) Linus Arver
2014-08-08 17:29   ` [PATCH v2 1/7] Documentation: git-init: typographical fixes Linus Arver
2014-08-08 17:29   ` [PATCH v2 2/7] Documentation: git-init: list items facelift Linus Arver
2014-08-08 17:29   ` [PATCH v2 3/7] Documentation: git-init: template directory: reword Linus Arver
2014-08-08 17:29   ` [PATCH v2 4/7] Documentation: git-init: --separate-git-dir: clarify Linus Arver
2014-08-08 17:29   ` [PATCH v2 5/7] Documentation: git-init: reword parenthetical statements Linus Arver
2014-08-08 17:29   ` [PATCH v2 6/7] Documentation: git-init: template directory: reword and cross-reference Linus Arver
2014-08-08 17:29   ` [PATCH v2 7/7] Documentation: git-init: flesh out example Linus Arver

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.