1GIT-RECEIVE-PACK(1)               Git Manual               GIT-RECEIVE-PACK(1)
2
3
4

NAME

6       git-receive-pack - Receive what is pushed into the repository
7

SYNOPSIS

9       git receive-pack <git-dir>
10

DESCRIPTION

12       Invoked by git send-pack and updates the repository with the
13       information fed from the remote end.
14
15       This command is usually not invoked directly by the end user. The UI
16       for the protocol is on the git send-pack side, and the program pair is
17       meant to be used to push updates to a remote repository. For pull
18       operations, see git-fetch-pack(1).
19
20       The command allows for the creation and fast-forwarding of sha1 refs
21       (heads/tags) on the remote end (strictly speaking, it is the local end
22       git-receive-pack runs, but to the user who is sitting at the send-pack
23       end, it is updating the remote. Confused?)
24
25       There are other real-world examples of using update and post-update
26       hooks found in the Documentation/howto directory.
27
28       git-receive-pack honours the receive.denyNonFastForwards config option,
29       which tells it if updates to a ref should be denied if they are not
30       fast-forwards.
31
32       A number of other receive.* config options are available to tweak its
33       behavior, see git-config(1).
34

OPTIONS

36       <git-dir>
37           The repository to sync into.
38
39       --http-backend-info-refs
40           Used by git-http-backend(1) to serve up
41           $GIT_URL/info/refs?service=git-receive-pack requests. See
42           --http-backend-info-refs in git-upload-pack(1).
43

PRE-RECEIVE HOOK

45       Before any ref is updated, if $GIT_DIR/hooks/pre-receive file exists
46       and is executable, it will be invoked once with no parameters. The
47       standard input of the hook will be one line per ref to be updated:
48
49           sha1-old SP sha1-new SP refname LF
50
51       The refname value is relative to $GIT_DIR; e.g. for the master head
52       this is "refs/heads/master". The two sha1 values before each refname
53       are the object names for the refname before and after the update. Refs
54       to be created will have sha1-old equal to 0{40}, while refs to be
55       deleted will have sha1-new equal to 0{40}, otherwise sha1-old and
56       sha1-new should be valid objects in the repository.
57
58       When accepting a signed push (see git-push(1)), the signed push
59       certificate is stored in a blob and an environment variable
60       GIT_PUSH_CERT can be consulted for its object name. See the description
61       of post-receive hook for an example. In addition, the certificate is
62       verified using GPG and the result is exported with the following
63       environment variables:
64
65       GIT_PUSH_CERT_SIGNER
66           The name and the e-mail address of the owner of the key that signed
67           the push certificate.
68
69       GIT_PUSH_CERT_KEY
70           The GPG key ID of the key that signed the push certificate.
71
72       GIT_PUSH_CERT_STATUS
73           The status of GPG verification of the push certificate, using the
74           same mnemonic as used in %G?  format of git log family of commands
75           (see git-log(1)).
76
77       GIT_PUSH_CERT_NONCE
78           The nonce string the process asked the signer to include in the
79           push certificate. If this does not match the value recorded on the
80           "nonce" header in the push certificate, it may indicate that the
81           certificate is a valid one that is being replayed from a separate
82           "git push" session.
83
84       GIT_PUSH_CERT_NONCE_STATUS
85
86           UNSOLICITED
87               "git push --signed" sent a nonce when we did not ask it to send
88               one.
89
90           MISSING
91               "git push --signed" did not send any nonce header.
92
93           BAD
94               "git push --signed" sent a bogus nonce.
95
96           OK
97               "git push --signed" sent the nonce we asked it to send.
98
99           SLOP
100               "git push --signed" sent a nonce different from what we asked
101               it to send now, but in a previous session. See
102               GIT_PUSH_CERT_NONCE_SLOP environment variable.
103
104       GIT_PUSH_CERT_NONCE_SLOP
105           "git push --signed" sent a nonce different from what we asked it to
106           send now, but in a different session whose starting time is
107           different by this many seconds from the current session. Only
108           meaningful when GIT_PUSH_CERT_NONCE_STATUS says SLOP. Also read
109           about receive.certNonceSlop variable in git-config(1).
110
111       This hook is called before any refname is updated and before any
112       fast-forward checks are performed.
113
114       If the pre-receive hook exits with a non-zero exit status no updates
115       will be performed, and the update, post-receive and post-update hooks
116       will not be invoked either. This can be useful to quickly bail out if
117       the update is not to be supported.
118
119       See the notes on the quarantine environment below.
120

UPDATE HOOK

122       Before each ref is updated, if $GIT_DIR/hooks/update file exists and is
123       executable, it is invoked once per ref, with three parameters:
124
125           $GIT_DIR/hooks/update refname sha1-old sha1-new
126
127       The refname parameter is relative to $GIT_DIR; e.g. for the master head
128       this is "refs/heads/master". The two sha1 arguments are the object
129       names for the refname before and after the update. Note that the hook
130       is called before the refname is updated, so either sha1-old is 0{40}
131       (meaning there is no such ref yet), or it should match what is recorded
132       in refname.
133
134       The hook should exit with non-zero status if it wants to disallow
135       updating the named ref. Otherwise it should exit with zero.
136
137       Successful execution (a zero exit status) of this hook does not ensure
138       the ref will actually be updated, it is only a prerequisite. As such it
139       is not a good idea to send notices (e.g. email) from this hook.
140       Consider using the post-receive hook instead.
141

POST-RECEIVE HOOK

143       After all refs were updated (or attempted to be updated), if any ref
144       update was successful, and if $GIT_DIR/hooks/post-receive file exists
145       and is executable, it will be invoked once with no parameters. The
146       standard input of the hook will be one line for each successfully
147       updated ref:
148
149           sha1-old SP sha1-new SP refname LF
150
151       The refname value is relative to $GIT_DIR; e.g. for the master head
152       this is "refs/heads/master". The two sha1 values before each refname
153       are the object names for the refname before and after the update. Refs
154       that were created will have sha1-old equal to 0{40}, while refs that
155       were deleted will have sha1-new equal to 0{40}, otherwise sha1-old and
156       sha1-new should be valid objects in the repository.
157
158       The GIT_PUSH_CERT* environment variables can be inspected, just as in
159       pre-receive hook, after accepting a signed push.
160
161       Using this hook, it is easy to generate mails describing the updates to
162       the repository. This example script sends one mail message per ref
163       listing the commits pushed to the repository, and logs the push
164       certificates of signed pushes with good signatures to a logger service:
165
166           #!/bin/sh
167           # mail out commit update information.
168           while read oval nval ref
169           do
170                   if expr "$oval" : '0*$' >/dev/null
171                   then
172                           echo "Created a new ref, with the following commits:"
173                           git rev-list --pretty "$nval"
174                   else
175                           echo "New commits:"
176                           git rev-list --pretty "$nval" "^$oval"
177                   fi |
178                   mail -s "Changes to ref $ref" commit-list@mydomain
179           done
180           # log signed push certificate, if any
181           if test -n "${GIT_PUSH_CERT-}" && test ${GIT_PUSH_CERT_STATUS} = G
182           then
183                   (
184                           echo expected nonce is ${GIT_PUSH_NONCE}
185                           git cat-file blob ${GIT_PUSH_CERT}
186                   ) | mail -s "push certificate from $GIT_PUSH_CERT_SIGNER" push-log@mydomain
187           fi
188           exit 0
189
190       The exit code from this hook invocation is ignored, however a non-zero
191       exit code will generate an error message.
192
193       Note that it is possible for refname to not have sha1-new when this
194       hook runs. This can easily occur if another user modifies the ref after
195       it was updated by git-receive-pack, but before the hook was able to
196       evaluate it. It is recommended that hooks rely on sha1-new rather than
197       the current value of refname.
198

POST-UPDATE HOOK

200       After all other processing, if at least one ref was updated, and if
201       $GIT_DIR/hooks/post-update file exists and is executable, then
202       post-update will be called with the list of refs that have been
203       updated. This can be used to implement any repository wide cleanup
204       tasks.
205
206       The exit code from this hook invocation is ignored; the only thing left
207       for git-receive-pack to do at that point is to exit itself anyway.
208
209       This hook can be used, for example, to run git update-server-info if
210       the repository is packed and is served via a dumb transport.
211
212           #!/bin/sh
213           exec git update-server-info
214

QUARANTINE ENVIRONMENT

216       When receive-pack takes in objects, they are placed into a temporary
217       "quarantine" directory within the $GIT_DIR/objects directory and
218       migrated into the main object store only after the pre-receive hook has
219       completed. If the push fails before then, the temporary directory is
220       removed entirely.
221
222       This has a few user-visible effects and caveats:
223
224        1. Pushes which fail due to problems with the incoming pack, missing
225           objects, or due to the pre-receive hook will not leave any on-disk
226           data. This is usually helpful to prevent repeated failed pushes
227           from filling up your disk, but can make debugging more challenging.
228
229        2. Any objects created by the pre-receive hook will be created in the
230           quarantine directory (and migrated only if it succeeds).
231
232        3. The pre-receive hook MUST NOT update any refs to point to
233           quarantined objects. Other programs accessing the repository will
234           not be able to see the objects (and if the pre-receive hook fails,
235           those refs would become corrupted). For safety, any ref updates
236           from within pre-receive are automatically rejected.
237

SEE ALSO

239       git-send-pack(1), gitnamespaces(7)
240

GIT

242       Part of the git(1) suite
243
244
245
246Git 2.43.0                        11/20/2023               GIT-RECEIVE-PACK(1)
Impressum