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>
Jeff King committed
Apr 10, 2017 at 18:13 UTC
eaeed077a69ad1e26b0c329ac0f6cbd397f5be9e
2 files changed
+31
Documentation/git-receive-pack.txt
+28
@@ -114,6 +114,8 @@ will be performed, and the update, post-receive and post-update
114
hooks will not be invoked either. This can be useful to quickly
115
bail out if the update is not to be supported.
116
117
+See the notes on the quarantine environment below.
118
+
119
update Hook
120
-----------
121
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.
216
exec git update-server-info
217
218
219
+Quarantine Environment
220
+----------------------
221
+
222
+When `receive-pack` takes in objects, they are placed into a temporary
223
+"quarantine" directory within the `$GIT_DIR/objects` directory and
224
+migrated into the main object store only after the `pre-receive` hook
225
+has completed. If the push fails before then, the temporary directory is
226
+removed entirely.
227
+
228
+This has a few user-visible effects and caveats:
229
+
230
+ 1. Pushes which fail due to problems with the incoming pack, missing
231
+ objects, or due to the `pre-receive` hook will not leave any
232
+ on-disk data. This is usually helpful to prevent repeated failed
233
+ pushes from filling up your disk, but can make debugging more
234
+ challenging.
235
+
236
+ 2. Any objects created by the `pre-receive` hook will be created in
237
+ the quarantine directory (and migrated only if it succeeds).
238
+
239
+ 3. The `pre-receive` hook MUST NOT update any refs to point to
240
+ quarantined objects. Other programs accessing the repository will
241
+ not be able to see the objects (and if the pre-receive hook fails,
242
+ those refs would become corrupted).
243
+
244
+
245
SEE ALSO
246
--------
247
linkgit:git-send-pack[1], linkgit:gitnamespaces[7]
Documentation/githooks.txt
+3
@@ -256,6 +256,9 @@ environment variables will not be set. If the client selects
256
to use push options, but doesn't transmit any, the count variable
257
will be set to zero, `GIT_PUSH_OPTION_COUNT=0`.
258
259
+See the section on "Quarantine Environment" in
260
+linkgit:git-receive-pack[1] for some caveats.
261
+
262
[[update]]
263
update
264
~~~~~~