[PATCH v6 1/4] githooks.txt: Improve the intro section
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 that we change the working directory 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 <avarab@gmail.com>
---
Documentation/git-init.txt | 7 ++++++-
Documentation/githooks.txt | 31 +++++++++++++++++++------------
2 files changed, 25 insertions(+), 13 deletions(-)
diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index 8174d27..6364e5d 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -130,7 +130,12 @@ 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 sample hook files.
+
+The sample hooks are all disabled by default, To enable one of the
+sample hooks rename it by removing its `.sample` suffix.
+
+See linkgit:githooks[5] for more general info on hook execution.
EXAMPLES
--------
diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt
index a2f59b1..0d94337 100644
--- a/Documentation/githooks.txt
+++ b/Documentation/githooks.txt
@@ -13,18 +13,25 @@ $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 actions at certain points in git's execution. Hooks that don't
+have the executable bit set are ignored.
+
+Before Git invokes a hook, it changes its working directory to either
+the root of the working tree in a non-bare repository, or to the
+$GIT_DIR in a bare repository.
+
+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
+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
+with Git.
+
+The currently supported hooks are described below.
HOOKS
-----
--
2.1.3
Ævar Arnfjörð Bjarmason <avarab@gmail.com>