Re: fixup! [PATCH 1/6] doc: fix formatting inconsistency in githooks.txt

[Andreas Heiduk]

Am 12.04.2018 um 21:36 schrieb Martin Ågren:
> On 11 April 2018 at 23:08, Andreas Heiduk  wrote:
>> - reflow some paragraphs
>> ---
>>  Documentation/githooks.txt | 14 +++---
>>  1 file changed, 7 insertions(+), 7 deletions(-)
>
> I have reviewed the resulting githooks.txt. See the diff below for two
> more instances that I found. For the second hunk, I have difficulties
> parsing that paragraph, but I still claim those should be backticks and
> *git* read-tree...
>
> Martin

I've added the fixes for the next reroll and put you into a Reviewed-by
Trailer :-)

Andreas

Re: fixup! [PATCH 1/6] doc: fix formatting inconsistency in githooks.txt

[Martin Ågren]

On 11 April 2018 at 23:08, Andreas Heiduk  wrote:
> - reflow some paragraphs
> ---
>  Documentation/githooks.txt | 14 +++---
>  1 file changed, 7 insertions(+), 7 deletions(-)

I have reviewed the resulting githooks.txt. See the diff below for two
more instances that I found. For the second hunk, I have difficulties
parsing that paragraph, but I still claim those should be backticks and
*git* read-tree...

Martin

diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt
index ab5ce80e13..e3c283a174 100644
--- a/Documentation/githooks.txt
+++ b/Documentation/githooks.txt
@@ -80,7 +80,7 @@ This hook is invoked by linkgit:git-am[1].  It takes
no parameter,
 and is invoked after the patch is applied and a commit is made.

 This hook is meant primarily for notification, and cannot affect
-the outcome of 'git am'.
+the outcome of `git am`.

 pre-commit
 ~~
@@ -400,8 +400,8 @@ when the tip of the current branch is updated to
the new commit, and
 exit with a zero status.

 For example, the hook can simply run `git read-tree -u -m HEAD "$1"`
-in order to emulate 'git fetch' that is run in the reverse direction
-with `git push`, as the two-tree form of `read-tree -u -m` is
+in order to emulate `git fetch` that is run in the reverse direction
+with `git push`, as the two-tree form of `git read-tree -u -m` is
 essentially the same as `git checkout` that switches branches while
 keeping the local changes in the working tree that do not interfere
 with the difference between the branches.

fixup! [PATCH 1/6] doc: fix formatting inconsistency in githooks.txt

[Andreas Heiduk]

- reflow some paragraphs
---
 Documentation/githooks.txt | 14 +++---
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt
index be31376767..ab5ce80e13 100644
--- a/Documentation/githooks.txt
+++ b/Documentation/githooks.txt
@@ -194,10 +194,10 @@ for an example of how to do this.
 pre-push
 
 
-This hook is called by linkgit:git-push[1] and can be used to prevent a push 
from taking
-place.  The hook is called with two parameters which provide the name and
-location of the destination remote, if a named remote is not being used both
-values will be the same.
+This hook is called by linkgit:git-push[1] and can be used to prevent
+a push from taking place.  The hook is called with two parameters
+which provide the name and location of the destination remote, if a
+named remote is not being used both values will be the same.
 
 Information about what is to be pushed is provided on the hook's standard
 input with lines of the form:
@@ -410,9 +410,9 @@ with the difference between the branches.
 pre-auto-gc
 ~~~
 
-This hook is invoked by `git gc --auto` (see linkgit:git-gc[1]). It takes no 
parameter, and
-exiting with non-zero status from this script causes the `git gc --auto`
-to abort.
+This hook is invoked by `git gc --auto` (see linkgit:git-gc[1]). It
+takes no parameter, and exiting with non-zero status from this script
+causes the `git gc --auto` to abort.
 
 post-rewrite
 
-- 
2.16.2

fixup! [PATCH 1/6] doc: fix formatting inconsistency in githooks.txt

[Andreas Heiduk]

- add linkgit: to callers of hooks
- change 'git-foo' and similar to `git foo`
- add some more `` for fsmonitor
---
 Documentation/githooks.txt | 101 +++--
 1 file changed, 51 insertions(+), 50 deletions(-)

diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt
index 070e745b41..be31376767 100644
--- a/Documentation/githooks.txt
+++ b/Documentation/githooks.txt
@@ -31,7 +31,7 @@ Hooks can get their arguments via the environment, 
command-line
 arguments, and stdin. See the documentation for each hook below for
 details.
 
-'git init' may copy hooks to the new repository, depending on its
+`git init` may copy hooks to the new repository, depending on its
 configuration. See the "TEMPLATE DIRECTORY" section in
 linkgit:git-init[1] for details. When the rest of this document refers
 to "default hooks" it's talking about the default template shipped
@@ -45,9 +45,9 @@ HOOKS
 applypatch-msg
 ~~
 
-This hook is invoked by 'git am'.  It takes a single
+This hook is invoked by linkgit:git-am[1].  It takes a single
 parameter, the name of the file that holds the proposed commit
-log message.  Exiting with a non-zero status causes 'git am' to abort
+log message.  Exiting with a non-zero status causes `git am` to abort
 before applying the patch.
 
 The hook is allowed to edit the message file in place, and can
@@ -61,7 +61,7 @@ The default 'applypatch-msg' hook, when enabled, runs the
 pre-applypatch
 ~~
 
-This hook is invoked by 'git am'.  It takes no parameter, and is
+This hook is invoked by linkgit:git-am[1].  It takes no parameter, and is
 invoked after the patch is applied, but before a commit is made.
 
 If it exits with non-zero status, then the working tree will not be
@@ -76,7 +76,7 @@ The default 'pre-applypatch' hook, when enabled, runs the
 post-applypatch
 ~~~
 
-This hook is invoked by 'git am'.  It takes no parameter,
+This hook is invoked by linkgit:git-am[1].  It takes no parameter,
 and is invoked after the patch is applied and a commit is made.
 
 This hook is meant primarily for notification, and cannot affect
@@ -85,24 +85,24 @@ the outcome of 'git am'.
 pre-commit
 ~~
 
-This hook is invoked by 'git commit', and can be bypassed
+This hook is invoked by linkgit:git-commit[1], and can be bypassed
 with the `--no-verify` option.  It takes no parameters, and is
 invoked before obtaining the proposed commit log message and
 making a commit.  Exiting with a non-zero status from this script
-causes the 'git commit' command to abort before creating a commit.
+causes the `git commit` command to abort before creating a commit.
 
 The default 'pre-commit' hook, when enabled, catches introduction
 of lines with trailing whitespaces and aborts the commit when
 such a line is found.
 
-All the 'git commit' hooks are invoked with the environment
+All the `git commit` hooks are invoked with the environment
 variable `GIT_EDITOR=:` if the command will not bring up an editor
 to modify the commit message.
 
 prepare-commit-msg
 ~~
 
-This hook is invoked by 'git commit' right after preparing the
+This hook is invoked by linkgit:git-commit[1] right after preparing the
 default log message, and before the editor is started.
 
 It takes one to three parameters.  The first is the name of the file
@@ -114,7 +114,7 @@ commit is a merge or a `.git/MERGE_MSG` file exists); 
`squash`
 (if a `.git/SQUASH_MSG` file exists); or `commit`, followed by
 a commit SHA-1 (if a `-c`, `-C` or `--amend` option was given).
 
-If the exit status is non-zero, 'git commit' will abort.
+If the exit status is non-zero, `git commit` will abort.
 
 The purpose of the hook is to edit the message file in place, and
 it is not suppressed by the `--no-verify` option.  A non-zero exit
@@ -127,7 +127,7 @@ help message found in the commented portion of the commit 
template.
 commit-msg
 ~~
 
-This hook is invoked by 'git commit' and 'git merge', and can be
+This hook is invoked by linkgit:git-commit[1] and linkgit:git-merge[1], and 
can be
 bypassed with the `--no-verify` option.  It takes a single parameter,
 the name of the file that holds the proposed commit log message.
 Exiting with a non-zero status causes the command to abort.
@@ -143,16 +143,16 @@ The default 'commit-msg' hook, when enabled, detects 
duplicate
 post-commit
 ~~~
 
-This hook is invoked by 'git commit'. It takes no parameters, and is
+This hook is invoked by linkgit:git-commit[1]. It takes no parameters, and is
 invoked after a commit is made.
 
 This hook is meant primarily for notification, and cannot affect
-the outcome of 'git commit'.
+the outcome of `git commit`.
 
 pre-rebase
 ~~
 
-This hook is called by 'git rebase' and can be used to prevent a
+This hook is called by linkgit:git-rebase[1] and can be used to prevent a
 branch from getting rebased.  The hook may be called with one or
 two parameters.  The first parameter is the 

Re: [PATCH 1/6] doc: fix formatting inconsistency in githooks.txt

[Andreas Heiduk]

So the following two fixups should cleanup that page considerably.

Re: [PATCH 1/6] doc: fix formatting inconsistency in githooks.txt

[Junio C Hamano]

Martin Ågren  writes:

> Your reading seems correct, so I was wrong in my speculation. My guess
> is such a patch would be welcome. I checked a couple of man-pages and
> this one seems particularly heavy on 'git foo' as opposed to `git foo`.
> I think that's a reason to fix it, not to leave it behind.

Sounds sensible.  Hopefully there isn't a topic in flight that wants
to change this file, so it may be a good time to do a wholesale
cleanup of it.

Re: [PATCH 1/6] doc: fix formatting inconsistency in githooks.txt

[Martin Ågren]

On 10 April 2018 at 22:04, Andreas Heiduk  wrote:
> Am 10.04.2018 um 21:13 schrieb Martin Ågren:
>> On 10 April 2018 at 20:32, Andreas Heiduk  wrote:
>> Hmm, I wonder if that is actually intentional. `git commit --amend`
>> could be run exactly like that and would do what this paragraph expects
>> of it. The 'git-rebase' is a Git subcommand name, i.e., not some
>> copy-paste command-line ready for use. If it were something like `git
>> rebase -i HEAD~5`, I would expect the backticks.
>
> That page mostly uses single quotes and no dash ('git send-email')for
> formatting. Reading 'CodingGuidelines' my understanding is, that git
> commands should be typeset with backticks, no dash (`git send-email`).
> So 'git-rebase' (an similar) *should* be typeset as `git rebase`. But
> doing so consistently would be a full-diff for this manual page.
>
> Should I do this?

Your reading seems correct, so I was wrong in my speculation. My guess
is such a patch would be welcome. I checked a couple of man-pages and
this one seems particularly heavy on 'git foo' as opposed to `git foo`.
I think that's a reason to fix it, not to leave it behind.

Martin

Re: [PATCH 1/6] doc: fix formatting inconsistency in githooks.txt

[Andreas Heiduk]

Am 10.04.2018 um 21:13 schrieb Martin Ågren:
> On 10 April 2018 at 20:32, Andreas Heiduk  wrote:
>> The section 'post-rewrite' in 'githooks.txt' renders only one command
>> using backticks (`git commit`) but the other commands using single quotes
>> ('git-rebase'). Align this formatting to use single quotes.
>>
>> Signed-off-by: Andreas Heiduk 
>> ---
>>  Documentation/githooks.txt | 4 ++--
>>  1 file changed, 2 insertions(+), 2 deletions(-)
>>
>> diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt
>> index f877f7b7cd..070e745b41 100644
>> --- a/Documentation/githooks.txt
>> +++ b/Documentation/githooks.txt
>> @@ -417,8 +417,8 @@ to abort.
>>  post-rewrite
>>  
>>
>> -This hook is invoked by commands that rewrite commits (`git commit
>> ---amend`, 'git-rebase'; currently 'git-filter-branch' does 'not' call
>> +This hook is invoked by commands that rewrite commits ('git commit
>> +--amend', 'git-rebase'; currently 'git-filter-branch' does 'not' call
>>  it!).  Its first argument denotes the command it was invoked by:
>>  currently one of `amend` or `rebase`.  Further command-dependent
>>  arguments may be passed in the future.
> 
> Hmm, I wonder if that is actually intentional. `git commit --amend`
> could be run exactly like that and would do what this paragraph expects
> of it. The 'git-rebase' is a Git subcommand name, i.e., not some
> copy-paste command-line ready for use. If it were something like `git
> rebase -i HEAD~5`, I would expect the backticks.

That page mostly uses single quotes and no dash ('git send-email')for
formatting. Reading 'CodingGuidelines' my understanding is, that git
commands should be typeset with backticks, no dash (`git send-email`). 
So 'git-rebase' (an similar) *should* be typeset as `git rebase`. But
doing so consistently would be a full-diff for this manual page.

Should I do this?

> 
> A second discrepancy is the dash in "git commit" vs "git-rebase" and
> "git-ls-remote". That could perhaps be explained by the same reasoning.
> 
> Martin
> 

Re: [PATCH 1/6] doc: fix formatting inconsistency in githooks.txt

[Martin Ågren]

On 10 April 2018 at 20:32, Andreas Heiduk  wrote:
> The section 'post-rewrite' in 'githooks.txt' renders only one command
> using backticks (`git commit`) but the other commands using single quotes
> ('git-rebase'). Align this formatting to use single quotes.
>
> Signed-off-by: Andreas Heiduk 
> ---
>  Documentation/githooks.txt | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt
> index f877f7b7cd..070e745b41 100644
> --- a/Documentation/githooks.txt
> +++ b/Documentation/githooks.txt
> @@ -417,8 +417,8 @@ to abort.
>  post-rewrite
>  
>
> -This hook is invoked by commands that rewrite commits (`git commit
> ---amend`, 'git-rebase'; currently 'git-filter-branch' does 'not' call
> +This hook is invoked by commands that rewrite commits ('git commit
> +--amend', 'git-rebase'; currently 'git-filter-branch' does 'not' call
>  it!).  Its first argument denotes the command it was invoked by:
>  currently one of `amend` or `rebase`.  Further command-dependent
>  arguments may be passed in the future.

Hmm, I wonder if that is actually intentional. `git commit --amend`
could be run exactly like that and would do what this paragraph expects
of it. The 'git-rebase' is a Git subcommand name, i.e., not some
copy-paste command-line ready for use. If it were something like `git
rebase -i HEAD~5`, I would expect the backticks.

A second discrepancy is the dash in "git commit" vs "git-rebase" and
"git-ls-remote". That could perhaps be explained by the same reasoning.

Martin

[PATCH 1/6] doc: fix formatting inconsistency in githooks.txt

[Andreas Heiduk]

The section 'post-rewrite' in 'githooks.txt' renders only one command
using backticks (`git commit`) but the other commands using single quotes
('git-rebase'). Align this formatting to use single quotes.

Signed-off-by: Andreas Heiduk 
---
 Documentation/githooks.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt
index f877f7b7cd..070e745b41 100644
--- a/Documentation/githooks.txt
+++ b/Documentation/githooks.txt
@@ -417,8 +417,8 @@ to abort.
 post-rewrite
 
 
-This hook is invoked by commands that rewrite commits (`git commit
---amend`, 'git-rebase'; currently 'git-filter-branch' does 'not' call
+This hook is invoked by commands that rewrite commits ('git commit
+--amend', 'git-rebase'; currently 'git-filter-branch' does 'not' call
 it!).  Its first argument denotes the command it was invoked by:
 currently one of `amend` or `rebase`.  Further command-dependent
 arguments may be passed in the future.
-- 
2.16.2