[v9,36/37] doc: clarify fsmonitor-watchman specification

Message ID	20210527000856.695702-37-emilyshaffer@google.com (mailing list archive)
State	New, archived
Headers	show Return-Path: <git-owner@kernel.org> Date: Wed, 26 May 2021 17:08:55 -0700 In-Reply-To: <20210527000856.695702-1-emilyshaffer@google.com> Message-Id: <20210527000856.695702-37-emilyshaffer@google.com> Mime-Version: 1.0 References: <20210527000856.695702-1-emilyshaffer@google.com> Subject: [PATCH v9 36/37] doc: clarify fsmonitor-watchman specification From: Emily Shaffer <emilyshaffer@google.com> To: git@vger.kernel.org Cc: Emily Shaffer <emilyshaffer@google.com> Content-Type: text/plain; charset="UTF-8" Precedence: bulk
Series	propose config-based hooks \| expand [v9,00/37] propose config-based hooks [v9,01/37] doc: propose hooks managed by the config [v9,02/37] hook: introduce git-hook subcommand [v9,03/37] hook: include hookdir hook in list [v9,04/37] hook: teach hook.runHookDir [v9,05/37] hook: implement hookcmd.<name>.skip [v9,06/37] parse-options: parse into strvec [v9,07/37] hook: add 'run' subcommand [v9,08/37] hook: introduce hook_exists() [v9,09/37] hook: support passing stdin to hooks [v9,10/37] run-command: allow stdin for run_processes_parallel [v9,11/37] hook: allow parallel hook execution [v9,12/37] hook: allow specifying working directory for hooks [v9,13/37] run-command: add stdin callback for parallelization [v9,14/37] hook: provide stdin by string_list or callback [v9,15/37] run-command: allow capturing of collated output [v9,16/37] hooks: allow callers to capture output [v9,17/37] commit: use config-based hooks [v9,18/37] am: convert applypatch hooks to use config [v9,19/37] merge: use config-based hooks for post-merge hook [v9,20/37] gc: use hook library for pre-auto-gc hook [v9,21/37] rebase: teach pre-rebase to use hook.h [v9,22/37] read-cache: convert post-index-change hook to use config [v9,23/37] receive-pack: convert push-to-checkout hook to hook.h [v9,24/37] git-p4: use 'git hook' to run hooks [v9,25/37] hooks: convert 'post-checkout' hook to hook library [v9,26/37] hook: convert 'post-rewrite' hook to config [v9,27/37] transport: convert pre-push hook to use config [v9,28/37] reference-transaction: look for hooks in config [v9,29/37] receive-pack: convert 'update' hook to hook.h [v9,30/37] proc-receive: acquire hook list from hook.h [v9,31/37] post-update: use hook.h library [v9,32/37] receive-pack: convert receive hooks to hook.h [v9,33/37] bugreport: use hook_exists instead of find_hook [v9,34/37] git-send-email: use 'git hook run' for 'sendemail-validate' [v9,35/37] run-command: stop thinking about hooks [v9,36/37] doc: clarify fsmonitor-watchman specification [v9,37/37] docs: link githooks and git-hook manpages

Message ID

20210527000856.695702-37-emilyshaffer@google.com (mailing list archive)

State

New, archived

Headers

Date: Wed, 26 May 2021 17:08:55 -0700
In-Reply-To: <20210527000856.695702-1-emilyshaffer@google.com>
Message-Id: <20210527000856.695702-37-emilyshaffer@google.com>
Mime-Version: 1.0
References: <20210527000856.695702-1-emilyshaffer@google.com>
Subject: [PATCH v9 36/37] doc: clarify fsmonitor-watchman specification
From: Emily Shaffer <emilyshaffer@google.com>
To: git@vger.kernel.org
Cc: Emily Shaffer <emilyshaffer@google.com>
Content-Type: text/plain; charset="UTF-8"
Precedence: bulk

Series

propose config-based hooks | expand

Commit Message

Emily Shaffer May 27, 2021, 12:08 a.m. UTC

fsmonitor-watchman is not specified in the same way that other hooks
are. In fsmonitor.c:query_fsmonitor(), the path stored in
'core_fsmonitor' is executed directly via
run-command.h:capture_command(). 'core_fsmonitor' is set during 'git
update-index' via config.c:git_config_get_fsmonitor(). Neither
builtin/update-index.c, nor config.c, nor fsmonitor.c check  that the
path given is in '.git/hooks'.

None of the existing hook execution code is used by fsmonitor.c to
invoke fsmonitor-watchman, because that executable isn't expected to
reside in '.git/hooks'.

Furthermore, it doesn't make sense to specify the fsmonitor-watchman
hook more than once, and that hook itself may soon be superseded by
native logic to talk to an fsmonitor daemon directly from the Git
executable. (See <e019cc71-ac39-44a4-0a23-b3b7decec754@jeffhostetler.com>
for more information.)

Therefore, let's correct the user-facing documentation around
fsmonitor-watchman and clarify that it won't be supported by
config-based hooks.

Signed-off-by: Emily Shaffer <emilyshaffer@google.com>
---
 Documentation/githooks.txt | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt
index 78cc4e0872..42e66d4e2d 100644
--- a/Documentation/githooks.txt
+++ b/Documentation/githooks.txt
@@ -649,9 +649,12 @@  e-mails.
 fsmonitor-watchman
 ~~~~~~~~~~~~~~~~~~
 
-This hook is invoked when the configuration option `core.fsmonitor` is
-set to `.git/hooks/fsmonitor-watchman` or `.git/hooks/fsmonitor-watchmanv2`
-depending on the version of the hook to use.
+This hook is invoked when the configuration option `core.fsmonitor` is set to a
+path containing an executable. It *cannot* be specified via the usual
+`hook.fsmonitor-watchman.command` configuration or by providing an executable
+in `.git/hooks/fsmonitor-watchman`. The arguments provided to the hook are
+determined by the value of the `core.fsmonitorHookVersion` configuration
+option.
 
 Version 1 takes two arguments, a version (1) and the time in elapsed
 nanoseconds since midnight, January 1, 1970.

[v9,36/37] doc: clarify fsmonitor-watchman specification

Commit Message

Patch