[PATCH 2/3] receive-pack: document user-visible quarantine effects
- From
Jeff King <peff@peff.net>
- Date
- Apr 10, 2017, 22:13 UTC
- Message-ID
- <20170410221339.5fs26rzca6wk73de@sigill.intra.peff.net>
- In-Reply-To
- <20170410221058.2ao64wedg2pa6uc2@sigill.intra.peff.net>
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> --- 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). + + SEE ALSO -------- 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. + [[update]] update ~~~~~~
-- 2.12.2.952.g759391acc