From b0d08a504bee17dfc46f761e166ff2c20c59a91a Mon Sep 17 00:00:00 2001
From: Francis Daly <francis@daoine.org>
Date: Wed, 22 Mar 2006 09:53:57 +0000
Subject: Format tweaks for asciidoc.

Some documentation "options" were followed by independent preformatted
paragraphs. Now they are associated plain text paragraphs. The
difference is clear in the generated html.

Signed-off-by: Junio C Hamano <junkio@cox.net>
---
 Documentation/git-grep.txt        | 14 +++++++-------
 Documentation/git-whatchanged.txt |  6 +++---
 2 files changed, 10 insertions(+), 10 deletions(-)

(limited to 'Documentation')

diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
index fbd2394481..d55456ae93 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -24,13 +24,13 @@ OPTIONS
 
 <option>...::
 	Either an option to pass to `grep` or `git-ls-files`.
-
-	The following are the specific `git-ls-files` options
-	that may be given: `-o`, `--cached`, `--deleted`, `--others`,
-	`--killed`, `--ignored`, `--modified`, `--exclude=*`,
-	`--exclude-from=*`, and `--exclude-per-directory=*`.
-
-	All other options will be passed to `grep`.
++
+The following are the specific `git-ls-files` options
+that may be given: `-o`, `--cached`, `--deleted`, `--others`,
+`--killed`, `--ignored`, `--modified`, `--exclude=\*`,
+`--exclude-from=\*`, and `--exclude-per-directory=\*`.
++
+All other options will be passed to `grep`.
 
 <pattern>::
 	The pattern to look for.  The first non option is taken
diff --git a/Documentation/git-whatchanged.txt b/Documentation/git-whatchanged.txt
index f02f939baa..641cb7ea97 100644
--- a/Documentation/git-whatchanged.txt
+++ b/Documentation/git-whatchanged.txt
@@ -47,9 +47,9 @@ OPTIONS
 	By default, differences for merge commits are not shown.
 	With this flag, show differences to that commit from all
 	of its parents.
-
-	However, it is not very useful in general, although it
-	*is* useful on a file-by-file basis.
++
+However, it is not very useful in general, although it
+*is* useful on a file-by-file basis.
 
 Examples
 --------
-- 
cgit v1.2.1


From 6250ad1e7aacbcb9a2a8944e0c664f1e7ec93ef6 Mon Sep 17 00:00:00 2001
From: Jon Loeliger <jdl@jdl.com>
Date: Fri, 24 Mar 2006 21:21:07 -0600
Subject: Clarify and expand some hook documentation.

Clarify update and post-update hooks.
Made a few references to the hooks documentation.

Signed-off-by: Jon Loeliger <jdl@jdl.com>
Signed-off-by: Junio C Hamano <junkio@cox.net>
---
 Documentation/git.txt               |  2 ++
 Documentation/hooks.txt             | 51 +++++++++++++++++++++++++++----------
 Documentation/repository-layout.txt |  2 ++
 3 files changed, 42 insertions(+), 13 deletions(-)

(limited to 'Documentation')

diff --git a/Documentation/git.txt b/Documentation/git.txt
index de3934d098..0c424ff851 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -531,6 +531,8 @@ File/Directory Structure
 
 Please see link:repository-layout.html[repository layout] document.
 
+Read link:hooks.html[hooks] for more details about each hook.
+
 Higher level SCMs may provide and manage additional information in the
 `$GIT_DIR`.
 
diff --git a/Documentation/hooks.txt b/Documentation/hooks.txt
index 4ad1920ec1..3824a9517c 100644
--- a/Documentation/hooks.txt
+++ b/Documentation/hooks.txt
@@ -97,16 +97,31 @@ send out a commit notification e-mail.
 update
 ------
 
-This hook is invoked by `git-receive-pack`, which is invoked
-when a `git push` is done against the repository.  It takes
-three parameters, name of the ref being updated, old object name
-stored in the ref, and the new objectname to be stored in the
-ref.  Exiting with non-zero status from this hook prevents
-`git-receive-pack` from updating the ref.
-
-This can be used to prevent 'forced' update on certain refs by
+This hook is invoked by `git-receive-pack` on the remote repository,
+which is happens when a `git push` is done on a local repository.
+Just before updating the ref on the remote repository, the update hook
+is invoked.  It's exit status determins the success or failure of
+the ref update.
+
+The hook executes once for each ref to be updated, and takes
+three parameters:
+    - the name of the ref being updated,
+    - the old object name stored in the ref,
+    - and the new objectname to be stored in the ref.
+
+A zero exit from the update hook allows the ref to be updated.
+Exiting with a non-zero status prevents `git-receive-pack`
+from updating the ref.
+
+This hook can be used to prevent 'forced' update on certain refs by
 making sure that the object name is a commit object that is a
 descendant of the commit object named by the old object name.
+That is, to enforce a "fast forward only" policy.
+
+It could also be used to log the old..new status.  However, it
+does not know the entire set of branches, so it would end up
+firing one e-mail per ref when used naively, though.
+
 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.
@@ -115,20 +130,30 @@ The standard output of this hook is sent to /dev/null; if you
 want to report something to the git-send-pack on the other end,
 you can redirect your output to your stderr.
 
+
 post-update
 -----------
 
-This hook is invoked by `git-receive-pack`, which is invoked
-when a `git push` is done against the repository.  It takes
-variable number of parameters; each of which is the name of ref
-that was actually updated.
+This hook is invoked by `git-receive-pack` on the remote repository,
+which is happens when a `git push` is done on a local repository.
+It executes on the remote repository once after all the refs have
+been updated.
+
+It takes a variable number of parameters, each of which is the
+name of ref that was actually updated.
 
 This hook is meant primarily for notification, and cannot affect
 the outcome of `git-receive-pack`.
 
+The post-update hook can tell what are the heads that were pushed,
+but it does not know what their original and updated values are,
+so it is a poor place to do log old..new.
+
 The default post-update hook, when enabled, runs
 `git-update-server-info` to keep the information used by dumb
-transport up-to-date.
+transports (eg, http) up-to-date.  If you are publishing
+a git repository that is accessible via http, you should
+probably enable this hook.
 
 The standard output of this hook is sent to /dev/null; if you
 want to report something to the git-send-pack on the other end,
diff --git a/Documentation/repository-layout.txt b/Documentation/repository-layout.txt
index 1f19bf86dd..98fbe7db52 100644
--- a/Documentation/repository-layout.txt
+++ b/Documentation/repository-layout.txt
@@ -89,6 +89,8 @@ hooks::
 	commands.  A handful of sample hooks are installed when
 	`git init-db` is run, but all of them are disabled by
 	default.  To enable, they need to be made executable.
+	Read link:hooks.html[hooks] for more details about
+	each hook.
 
 index::
 	The current index file for the repository.  It is
-- 
cgit v1.2.1


From 6a1640ffc6431d66fa33c8256fd19b5ee0bc1b47 Mon Sep 17 00:00:00 2001
From: Jon Loeliger <jdl@jdl.com>
Date: Fri, 24 Mar 2006 21:27:13 -0600
Subject: Removed bogus "<snap>" identifier.

Signed-off-by: Jon Loeliger <jdl@jdl.com>
Signed-off-by: Junio C Hamano <junkio@cox.net>
---
 Documentation/git.txt | 4 ----
 1 file changed, 4 deletions(-)

(limited to 'Documentation')

diff --git a/Documentation/git.txt b/Documentation/git.txt
index 0c424ff851..fe34f50dc5 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -521,10 +521,6 @@ HEAD::
 	a valid head 'name'
 	(i.e. the contents of `$GIT_DIR/refs/heads/<head>`).
 
-<snap>::
-	a valid snapshot 'name'
-	(i.e. the contents of `$GIT_DIR/refs/snap/<snap>`).
-
 
 File/Directory Structure
 ------------------------
-- 
cgit v1.2.1