Re: [PATCH v9 37/37] docs: link githooks and git-hook manpages

From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date: Jun 3, 2021, 09:18 UTC
Message-ID: <8735tz713a.fsf@evledraar.gmail.com>
In-Reply-To: <20210527000856.695702-38-emilyshaffer@google.com>

On Wed, May 26 2021, Emily Shaffer wrote:

> Since users may have an easier time finding 'man githooks' or 'git help
> githooks' through tab-completion or muscle memory, reference the 'git
> hook' commands. And in the 'git hook' manual, point users back to 'man
> githooks' for specifics about the hook events themselves.

Ok, there should be a cross-reference...

> +HOOKS
> +-----

But this should be a "SEE ALSO" section.

Show 15 quoted lines

> +For a list of hooks which can be configured and how they work, see
> +linkgit:githooks[5].
> +
>  CONFIGURATION
>  -------------
>  include::config/hook.txt[]
> diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt
> index 42e66d4e2d..d780cb3b18 100644
> --- a/Documentation/githooks.txt
> +++ b/Documentation/githooks.txt
> @@ -7,15 +7,16 @@ githooks - Hooks used by Git
>  
>  SYNOPSIS
>  --------
> +'git hook'

And ditto here, it makes no sense in a githooks(5) to put "git hook" in the SYNOPSIS section (which is usually commands to be run), that'll just spew out the --help output for "git hook" itself.

Show 10 quoted lines

>  $GIT_DIR/hooks/* (or \`git config core.hooksPath`/*)
>  
>  
>  DESCRIPTION
>  -----------
>  
> -Hooks are programs you can place in a hooks directory to trigger
> -actions at certain points in git's execution. Hooks that don't have
> -the executable bit set are ignored.
> +Hooks are programs you can specify in your config (see linkgit:git-hook[1]) or

For most other things we link back to git-config[1] for such "see", even though we have the included config in the specific command.

I can see how this makes more sense in a way, but would prefer to have us be consistent.

Show 5 quoted lines

> +place in a hooks directory to trigger actions at certain points in git's
> +execution. Hooks that don't have the executable bit set are ignored.
>  
>  By default the hooks directory is `$GIT_DIR/hooks`, but that can be
>  changed via the `core.hooksPath` configuration variable (see

Not a new issue, but is that "are ignored" not something that pre-dates "advice.ignoredHook"? I.e. we don't ignore them anymore, we warn about them, no?