[PATCH v3 1/3] githooks.txt: Improve the intro section
From: Ævar Arnfjörð Bjarmason <hidden>
Date: 2016-06-16 02:18:58
Subsystem:
documentation, the rest · Maintainers:
Jonathan Corbet, Linus Torvalds
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(-)
diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index 8174d27..cc3be7d 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt@@ -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 --------
diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt
index a2f59b1..6db515e 100644
--- a/Documentation/githooks.txt
+++ b/Documentation/githooks.txt@@ -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 -----
--
2.1.3