From: "Ævar Arnfjörð Bjarmason" <avarab@gmail•com>
To: git@vger•kernel.org
Cc: "Junio C Hamano" <gitster@pobox•com>,
"Jacob Keller" <jacob.keller@gmail•com>,
"Eric Sunshine" <sunshine@sunshineco•com>,
"Ævar Arnfjörð Bjarmason" <avarab@gmail•com>
Subject: [PATCH v3 1/3] githooks.txt: Improve the intro section
Date: Mon, 25 Apr 2016 14:14:23 +0000 [thread overview]
Message-ID: <1461593665-31395-2-git-send-email-avarab@gmail.com> (raw)
In-Reply-To: <1461593665-31395-1-git-send-email-avarab@gmail.com>
In-Reply-To: <CAPig+cRYBChNVT2cixdzMCvO36Np-RdvTuccFshRoUDWnJv1Rw@mail.gmail.com>
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 <avarab@gmail•com>
---
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
next prev parent reply other threads:[~2016-04-25 14:15 UTC|newest]
Thread overview: 17+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-04-24 20:20 [PATCH 1/3] githooks.txt: Improve the intro section Ævar Arnfjörð Bjarmason
2016-04-24 20:20 ` [PATCH 2/3] githooks.txt: Amend dangerous advice about 'update' hook ACL Ævar Arnfjörð Bjarmason
2016-04-24 20:32 ` Jacob Keller
2016-04-24 21:26 ` [PATCH v2 " Ævar Arnfjörð Bjarmason
2016-04-25 18:29 ` [PATCH " Junio C Hamano
2016-04-26 17:39 ` Ævar Arnfjörð Bjarmason
2016-04-24 20:20 ` [PATCH 3/3] githooks.txt: Minor improvements to the grammar & phrasing Ævar Arnfjörð Bjarmason
2016-04-25 18:33 ` Junio C Hamano
2016-04-26 16:55 ` Ævar Arnfjörð Bjarmason
2016-04-25 5:35 ` [PATCH 1/3] githooks.txt: Improve the intro section Eric Sunshine
2016-04-25 14:14 ` [PATCH v3 0/3] Improvements to githooks.txt documentation Ævar Arnfjörð Bjarmason
2016-04-25 18:34 ` Junio C Hamano
2016-04-25 14:14 ` Ævar Arnfjörð Bjarmason [this message]
2016-04-25 14:14 ` [PATCH v3 2/3] githooks.txt: Amend dangerous advice about 'update' hook ACL Ævar Arnfjörð Bjarmason
2016-04-25 14:14 ` [PATCH v3 3/3] githooks.txt: Minor improvements to the grammar & phrasing Ævar Arnfjörð Bjarmason
2016-04-25 18:23 ` [PATCH 1/3] githooks.txt: Improve the intro section Junio C Hamano
2016-04-26 17:51 ` Ævar Arnfjörð Bjarmason
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1461593665-31395-2-git-send-email-avarab@gmail.com \
--to=avarab@gmail$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=gitster@pobox$(echo .)com \
--cc=jacob.keller@gmail$(echo .)com \
--cc=sunshine@sunshineco$(echo .)com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox