Change the documentation so that:
* We don't talk about "little scripts". Hooks can be as big as you
want, and don't have to be scripts, just call them "programs".
* We note what happens with chdir() before a hook is called, nothing
documented this explicitly, but the current behavior is
predictable. It helps a lot to know what directory these hooks will
be executed from.
* We don't make claims about the example hooks which may not be true
depending on the configuration of 'init.templateDir'. Clarify that
we're talking about the default settings of git-init in those cases,
and move some of this documentation into git-init's documentation
about the default templates.
* We briefly note in the intro that hooks can get their arguments in
various different ways, and that how exactly is described below for
each hook.
Signed-off-by: Ævar Arnfjörð Bjarmason <redacted>
---
Documentation/git-init.txt | 6 +++++-
Documentation/githooks.txt | 32 ++++++++++++++++++++------------
2 files changed, 25 insertions(+), 13 deletions(-)
@@ -130,7 +130,11 @@ 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, suggested-"exclude patterns" (see linkgit:gitignore[5]), and sample hook files (see linkgit:githooks[5]).+"exclude patterns" (see linkgit:gitignore[5]), and example hook files.++The example are all disabled by default. To enable a hook, rename it+by removing its `.sample` suffix. See linkgit:githooks[5] for more+info on hook execution. EXAMPLES --------
@@ -13,18 +13,26 @@ $GIT_DIR/hooks/* DESCRIPTION ------------Hooks are little scripts you can place in `$GIT_DIR/hooks`-directory to trigger action at certain points. When-'git init' is run, a handful of example hooks are copied into the-`hooks` directory of the new repository, but by default they are-all disabled. To enable a hook, rename it by removing its `.sample`-suffix.--NOTE: It is also a requirement for a given hook to be executable.-However - in a freshly initialized repository - the `.sample` files are-executable by default.--This document describes the currently defined hooks.+Hooks are programs you can place in the `$GIT_DIR/hooks` directory to+trigger action at certain points. Hooks that don't have the executable+bit set are ignored.++When a hook is called in a non-bare repository the working directory+is guaranteed to be the root of the working tree, in a bare repository+the working directory will be the path to the repository. I.e. hooks+don't need to worry about the user's current working directory.++Hooks can get their arguments via the environment, command-line+arguments, and stdin. See the documentation for each below hook for+details.++When 'git init' is run it may depending on its configuration copy+hooks to the new repository, see the the "TEMPLATE DIRECTORY" section+in linkgit:git-init[1] for details. When the rest of this document+refers to "default hooks" we're talking about the default template+shipped with Git.++The currently supported hooks are described below. HOOKS -----
Any ACL you implement via an 'update' hook isn't actual access control
if the user has login access to the machine running git, because they
can trivially just built their own git version which doesn't run the
hook.
Change the documentation to take this dangerous edge case into account,
and remove the mention of the advice originating on the mailing list,
the users reading this don't care where the idea came up.
Signed-off-by: Ævar Arnfjörð Bjarmason <redacted>
---
Documentation/githooks.txt | 10 +++++++---
1 file changed, 7 insertions(+), 3 deletions(-)
@@ -275,9 +275,13 @@ does not know the entire set of branches, so it would end up firing one e-mail per ref when used naively, though. The <<post-receive,'post-receive'>> hook is more suited to that.-Another use suggested on the mailing list is to use this hook to-implement access control which is finer grained than the one-based on filesystem group.+Another use for this hook to implement access control which is finer+grained than the one based on filesystem group. Note that if the user+pushing has a normal login shell on the machine receiving the push+implementing access control like this can be trivially bypassed by+just using not executing the hook. In those cases consider using+e.g. linkgit:git-shell[1] as the login shell to restrict the user's+access. Both standard output and standard error output are forwarded to 'git send-pack' on the other end, so you can simply `echo` messages
Change:
* Sentences that needed "the" or "a" to either add those or change them
so they don't need them.
* The little tangent about "You can use this to do X (if your project
wants to do X)" can just be shortened to "e.g. if you want to do X".
* s/parameter/parameters/ when the plural made more sense.
Most of this goes all the way back to the initial introduction of
hooks.txt in v0.99.5-76-g6d35cc7 by Junio.
Signed-off-by: Ævar Arnfjörð Bjarmason <redacted>
---
Documentation/githooks.txt | 34 +++++++++++++++++-----------------
1 file changed, 17 insertions(+), 17 deletions(-)
@@ -40,15 +40,15 @@ HOOKS applypatch-msg ~~~~~~~~~~~~~~-This hook is invoked by 'git am' script. It takes a single+This hook is invoked by 'git am'. It takes a single parameter, the name of the file that holds the proposed commit-log message. Exiting with non-zero status causes-'git am' to abort before applying the patch.+log message. Exiting with non-zero causes 'git am' to abort+before applying the patch. The hook is allowed to edit the message file in place, and can-be used to normalize the message into some project standard-format (if the project has one). It can also be used to refuse-the commit after inspecting the message file.+be used to e.g. normalize the message into some project standard+format. It can also be used to refuse the commit after inspecting+the message file. The default 'applypatch-msg' hook, when enabled, runs the 'commit-msg' hook, if the latter is enabled.
@@ -81,10 +81,10 @@ pre-commit ~~~~~~~~~~ This hook is invoked by 'git commit', and can be bypassed-with `--no-verify` option. It takes no parameter, and is+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 non-zero status from this script-causes the 'git commit' to abort.+making a commit. Exiting with a non-zero status from this script+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
@@ -123,15 +123,15 @@ commit-msg ~~~~~~~~~~ This hook is invoked by 'git commit', and can be bypassed-with `--no-verify` option. It takes a single parameter, the+with the `--no-verify` option. It takes a single parameter, the name of the file that holds the proposed commit log message.-Exiting with non-zero status causes the 'git commit' to+Exiting with a non-zero status causes the 'git commit' to abort.-The hook is allowed to edit the message file in place, and can-be used to normalize the message into some project standard-format (if the project has one). It can also be used to refuse-the commit after inspecting the message file.+The hook is allowed to edit the message file in place, and can be used+to e.g. normalize the message into some project standard format. It+can also be used to refuse the commit after inspecting the message+file. The default 'commit-msg' hook, when enabled, detects duplicate "Signed-off-by" lines, and aborts the commit if one is found.
@@ -139,8 +139,8 @@ The default 'commit-msg' hook, when enabled, detects duplicate post-commit ~~~~~~~~~~~-This hook is invoked by 'git commit'. It takes no-parameter, and is invoked after a commit is made.+This hook is invoked by 'git commit'. 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'.
From: Jacob Keller <hidden> Date: 2016-06-16 02:18:58
On Sun, Apr 24, 2016 at 1:20 PM, Ævar Arnfjörð Bjarmason
[off-list ref] wrote:
quoted hunk
Any ACL you implement via an 'update' hook isn't actual access control
if the user has login access to the machine running git, because they
can trivially just built their own git version which doesn't run the
hook.
Change the documentation to take this dangerous edge case into account,
and remove the mention of the advice originating on the mailing list,
the users reading this don't care where the idea came up.
Signed-off-by: Ævar Arnfjörð Bjarmason <redacted>
---
Documentation/githooks.txt | 10 +++++++---
1 file changed, 7 insertions(+), 3 deletions(-)
@@ -275,9 +275,13 @@ does not know the entire set of branches, so it would end up firing one e-mail per ref when used naively, though. The <<post-receive,'post-receive'>> hook is more suited to that.-Another use suggested on the mailing list is to use this hook to-implement access control which is finer grained than the one-based on filesystem group.+Another use for this hook to implement access control which is finer+grained than the one based on filesystem group. Note that if the user+pushing has a normal login shell on the machine receiving the push+implementing access control like this can be trivially bypassed by+just using not executing the hook. In those cases consider using
"by just using not executing the hook."
This grammar doesn't make sense. It doesn't quite match what you said
in the commit message either.
+e.g. linkgit:git-shell[1] as the login shell to restrict the user's
+access.
Both standard output and standard error output are forwarded to
'git send-pack' on the other end, so you can simply `echo` messages
--
2.1.3
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Any ACL you implement via an 'update' hook isn't actual access control
if the user has login access to the machine running git, because they
can trivially just built their own git version which doesn't run the
hook.
Change the documentation to take this dangerous edge case into account,
and remove the mention of the advice originating on the mailing list,
the users reading this don't care where the idea came up.
Signed-off-by: Ævar Arnfjörð Bjarmason <redacted>
---
"by just using not executing the hook."
Yeah that made no sense. Fixed in this version.
Documentation/githooks.txt | 10 +++++++---
1 file changed, 7 insertions(+), 3 deletions(-)
@@ -275,9 +275,13 @@ does not know the entire set of branches, so it would end up firing one e-mail per ref when used naively, though. The <<post-receive,'post-receive'>> hook is more suited to that.-Another use suggested on the mailing list is to use this hook to-implement access control which is finer grained than the one-based on filesystem group.+Another use for this hook to implement access control which is finer+grained than the one based on filesystem group. Note that if the user+pushing has a normal login shell on the machine receiving the push+implementing access control like this can be trivially bypassed by+just not executing the hook. In those cases consider using+e.g. linkgit:git-shell[1] as the login shell to restrict the user's+access. Both standard output and standard error output are forwarded to 'git send-pack' on the other end, so you can simply `echo` messages
@@ -130,7 +130,11 @@ The template directory will be one of the following (in order): The default template directory includes some directory structure, suggested-"exclude patterns" (see linkgit:gitignore[5]), and sample hook files (see linkgit:githooks[5]).+"exclude patterns" (see linkgit:gitignore[5]), and example hook files.++The example are all disabled by default. To enable a hook, rename it
s/example/examples/
quoted hunk
+by removing its `.sample` suffix. See linkgit:githooks[5] for more
+info on hook execution.
@@ -13,18 +13,26 @@ $GIT_DIR/hooks/*+Hooks are programs you can place in the `$GIT_DIR/hooks` directory to+trigger action at certain points. Hooks that don't have the executable+bit set are ignored.++When a hook is called in a non-bare repository the working directory+is guaranteed to be the root of the working tree, in a bare repository+the working directory will be the path to the repository. I.e. hooks+don't need to worry about the user's current working directory.++Hooks can get their arguments via the environment, command-line+arguments, and stdin. See the documentation for each below hook for+details.++When 'git init' is run it may depending on its configuration copy
s/may/&,/
s/configuration/&,/
+hooks to the new repository, see the the "TEMPLATE DIRECTORY" section
+in linkgit:git-init[1] for details. When the rest of this document
+refers to "default hooks" we're talking about the default template
+shipped with Git.
+
+The currently supported hooks are described below.
This includes minor grammar edits pointed out by Eric Sunshine + the
one v2 patch I sent out in response to comments by Jacob Keller.
I thought it was less confusing to just send out a whole v3 series
than ask Junio to piece together v1..v3 of various patches.
Ævar Arnfjörð Bjarmason (3):
githooks.txt: Improve the intro section
githooks.txt: Amend dangerous advice about 'update' hook ACL
githooks.txt: Minor improvements to the grammar & phrasing
Documentation/git-init.txt | 6 +++-
Documentation/githooks.txt | 72 +++++++++++++++++++++++++++-------------------
2 files changed, 47 insertions(+), 31 deletions(-)
--
2.1.3
Change the documentation so that:
* We don't talk about "little scripts". Hooks can be as big as you
want, and don't have to be scripts, just call them "programs".
* We note what happens with chdir() before a hook is called, nothing
documented this explicitly, but the current behavior is
predictable. It helps a lot to know what directory these hooks will
be executed from.
* We don't make claims about the example hooks which may not be true
depending on the configuration of 'init.templateDir'. Clarify that
we're talking about the default settings of git-init in those cases,
and move some of this documentation into git-init's documentation
about the default templates.
* We briefly note in the intro that hooks can get their arguments in
various different ways, and that how exactly is described below for
each hook.
Signed-off-by: Ævar Arnfjörð Bjarmason <redacted>
---
Documentation/git-init.txt | 6 +++++-
Documentation/githooks.txt | 32 ++++++++++++++++++++------------
2 files changed, 25 insertions(+), 13 deletions(-)
@@ -130,7 +130,11 @@ 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, suggested-"exclude patterns" (see linkgit:gitignore[5]), and sample hook files (see linkgit:githooks[5]).+"exclude patterns" (see linkgit:gitignore[5]), and example hook files.++The example hooks are all disabled by default. To enable a hook,+rename it by removing its `.sample` suffix. See linkgit:githooks[5]+for more info on hook execution. EXAMPLES --------
@@ -13,18 +13,26 @@ $GIT_DIR/hooks/* DESCRIPTION ------------Hooks are little scripts you can place in `$GIT_DIR/hooks`-directory to trigger action at certain points. When-'git init' is run, a handful of example hooks are copied into the-`hooks` directory of the new repository, but by default they are-all disabled. To enable a hook, rename it by removing its `.sample`-suffix.--NOTE: It is also a requirement for a given hook to be executable.-However - in a freshly initialized repository - the `.sample` files are-executable by default.--This document describes the currently defined hooks.+Hooks are programs you can place in the `$GIT_DIR/hooks` directory to+trigger action at certain points. Hooks that don't have the executable+bit set are ignored.++When a hook is called in a non-bare repository the working directory+is guaranteed to be the root of the working tree, in a bare repository+the working directory will be the path to the repository. I.e. hooks+don't need to worry about the user's current working directory.++Hooks can get their arguments via the environment, command-line+arguments, and stdin. See the documentation for each below hook for+details.++When 'git init' is run it may, depending on its configuration, copy+hooks to the new repository, see the the "TEMPLATE DIRECTORY" section+in linkgit:git-init[1] for details. When the rest of this document+refers to "default hooks" we're talking about the default template+shipped with Git.++The currently supported hooks are described below. HOOKS -----
Any ACL you implement via an 'update' hook isn't actual access control
if the user has login access to the machine running git, because they
can trivially just built their own git version which doesn't run the
hook.
Change the documentation to take this dangerous edge case into account,
and remove the mention of the advice originating on the mailing list,
the users reading this don't care where the idea came up.
Signed-off-by: Ævar Arnfjörð Bjarmason <redacted>
---
Documentation/githooks.txt | 10 +++++++---
1 file changed, 7 insertions(+), 3 deletions(-)
@@ -275,9 +275,13 @@ does not know the entire set of branches, so it would end up firing one e-mail per ref when used naively, though. The <<post-receive,'post-receive'>> hook is more suited to that.-Another use suggested on the mailing list is to use this hook to-implement access control which is finer grained than the one-based on filesystem group.+Another use for this hook to implement access control which is finer+grained than the one based on filesystem group. Note that if the user+pushing has a normal login shell on the machine receiving the push+implementing access control like this can be trivially bypassed by+just not executing the hook. In those cases consider using+e.g. linkgit:git-shell[1] as the login shell to restrict the user's+access. Both standard output and standard error output are forwarded to 'git send-pack' on the other end, so you can simply `echo` messages
Change:
* Sentences that needed "the" or "a" to either add those or change them
so they don't need them.
* The little tangent about "You can use this to do X (if your project
wants to do X)" can just be shortened to "e.g. if you want to do X".
* s/parameter/parameters/ when the plural made more sense.
Most of this goes all the way back to the initial introduction of
hooks.txt in v0.99.5-76-g6d35cc7 by Junio.
Signed-off-by: Ævar Arnfjörð Bjarmason <redacted>
---
Documentation/githooks.txt | 34 +++++++++++++++++-----------------
1 file changed, 17 insertions(+), 17 deletions(-)
@@ -40,15 +40,15 @@ HOOKS applypatch-msg ~~~~~~~~~~~~~~-This hook is invoked by 'git am' script. It takes a single+This hook is invoked by 'git am'. It takes a single parameter, the name of the file that holds the proposed commit-log message. Exiting with non-zero status causes-'git am' to abort before applying the patch.+log message. Exiting with non-zero causes 'git am' to abort+before applying the patch. The hook is allowed to edit the message file in place, and can-be used to normalize the message into some project standard-format (if the project has one). It can also be used to refuse-the commit after inspecting the message file.+be used to e.g. normalize the message into some project standard+format. It can also be used to refuse the commit after inspecting+the message file. The default 'applypatch-msg' hook, when enabled, runs the 'commit-msg' hook, if the latter is enabled.
@@ -81,10 +81,10 @@ pre-commit ~~~~~~~~~~ This hook is invoked by 'git commit', and can be bypassed-with `--no-verify` option. It takes no parameter, and is+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 non-zero status from this script-causes the 'git commit' to abort.+making a commit. Exiting with a non-zero status from this script+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
@@ -123,15 +123,15 @@ commit-msg ~~~~~~~~~~ This hook is invoked by 'git commit', and can be bypassed-with `--no-verify` option. It takes a single parameter, the+with the `--no-verify` option. It takes a single parameter, the name of the file that holds the proposed commit log message.-Exiting with non-zero status causes the 'git commit' to+Exiting with a non-zero status causes the 'git commit' to abort.-The hook is allowed to edit the message file in place, and can-be used to normalize the message into some project standard-format (if the project has one). It can also be used to refuse-the commit after inspecting the message file.+The hook is allowed to edit the message file in place, and can be used+to e.g. normalize the message into some project standard format. It+can also be used to refuse the commit after inspecting the message+file. The default 'commit-msg' hook, when enabled, detects duplicate "Signed-off-by" lines, and aborts the commit if one is found.
@@ -139,8 +139,8 @@ The default 'commit-msg' hook, when enabled, detects duplicate post-commit ~~~~~~~~~~~-This hook is invoked by 'git commit'. It takes no-parameter, and is invoked after a commit is made.+This hook is invoked by 'git commit'. 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'.