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@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt
index 0ccd5fbc781deb3adcca4d28ec8a4ed0d9db9977..7267ecfbe85b6c8246af79d1fb1fcf3dadf74764 100644 (file)
--- 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.
 
 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
 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
 
 
        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).
+
+

 SEE ALSO
 --------
 linkgit:git-send-pack[1], linkgit:gitnamespaces[7]
 SEE ALSO
 --------
 linkgit:git-send-pack[1], linkgit:gitnamespaces[7]

diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt
index 9565dc3fda47d7c8a7290132c347b5a6f0d2422e..32343ae295e7c94a70f67e9abca542f22d992102 100644 (file)
--- 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`.
 
 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.
+

 [[update]]
 update
 ~~~~~~
 [[update]]
 update
 ~~~~~~