Web lists-archives.com

[PATCH 2/3] receive-pack: document user-visible quarantine effects

Commit 722ff7f87 (receive-pack: quarantine objects until
pre-receive accepts, 2016-10-03) changed the underlying
details of how we take in objects. This is mostly
transparent to the user, but there are a few things they
might notice. Let's document them.

Signed-off-by: Jeff King <peff@xxxxxxxx>
 Documentation/git-receive-pack.txt | 28 ++++++++++++++++++++++++++++
 Documentation/githooks.txt         |  3 +++
 2 files changed, 31 insertions(+)

diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt
index 0ccd5fbc7..7267ecfbe 100644
--- a/Documentation/git-receive-pack.txt
+++ b/Documentation/git-receive-pack.txt
@@ -114,6 +114,8 @@ will be performed, and the update, post-receive and post-update
 hooks will not be invoked either.  This can be useful to quickly
 bail out if the update is not to be supported.
+See the notes on the quarantine environment below.
 update Hook
 Before each ref is updated, if $GIT_DIR/hooks/update file exists
@@ -214,6 +216,32 @@ if the repository is packed and is served via a dumb transport.
 	exec git update-server-info
+Quarantine Environment
+When `receive-pack` takes in objects, they are placed into a temporary
+"quarantine" directory within the `$GIT_DIR/objects` directory and
+migrated into the main object store only after the `pre-receive` hook
+has completed. If the push fails before then, the temporary directory is
+removed entirely.
+This has a few user-visible effects and caveats:
+  1. Pushes which fail due to problems with the incoming pack, missing
+     objects, or due to the `pre-receive` hook will not leave any
+     on-disk data. This is usually helpful to prevent repeated failed
+     pushes from filling up your disk, but can make debugging more
+     challenging.
+  2. Any objects created by the `pre-receive` hook will be created in
+     the quarantine directory (and migrated only if it succeeds).
+  3. The `pre-receive` hook MUST NOT update any refs to point to
+     quarantined objects. Other programs accessing the repository will
+     not be able to see the objects (and if the pre-receive hook fails,
+     those refs would become corrupted).
 linkgit:git-send-pack[1], linkgit:gitnamespaces[7]
diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt
index 9565dc3fd..32343ae29 100644
--- a/Documentation/githooks.txt
+++ b/Documentation/githooks.txt
@@ -256,6 +256,9 @@ environment variables will not be set. If the client selects
 to use push options, but doesn't transmit any, the count variable
 will be set to zero, `GIT_PUSH_OPTION_COUNT=0`.
+See the section on "Quarantine Environment" in
+linkgit:git-receive-pack[1] for some caveats.