]>
Commit | Line | Data |
---|---|---|
2a245013 JH |
1 | git-receive-pack(1) |
2 | =================== | |
2a245013 JH |
3 | |
4 | NAME | |
5 | ---- | |
c3f0baac | 6 | git-receive-pack - Receive what is pushed into the repository |
2a245013 JH |
7 | |
8 | ||
9 | SYNOPSIS | |
10 | -------- | |
7791a1d9 | 11 | [verse] |
3e4ebe3a | 12 | 'git receive-pack' <git-dir> |
2a245013 JH |
13 | |
14 | DESCRIPTION | |
15 | ----------- | |
0b444cdb | 16 | Invoked by 'git send-pack' and updates the repository with the |
2a245013 JH |
17 | information fed from the remote end. |
18 | ||
19 | This command is usually not invoked directly by the end user. | |
0b444cdb | 20 | The UI for the protocol is on the 'git send-pack' side, and the |
2a245013 | 21 | program pair is meant to be used to push updates to remote |
483bc4f0 | 22 | repository. For pull operations, see linkgit:git-fetch-pack[1]. |
2a245013 | 23 | |
a75d7b54 | 24 | The command allows for creation and fast-forwarding of sha1 refs |
b1bf95bb | 25 | (heads/tags) on the remote end (strictly speaking, it is the |
ba020ef5 | 26 | local end 'git-receive-pack' runs, but to the user who is sitting at |
b1bf95bb JW |
27 | the send-pack end, it is updating the remote. Confused?) |
28 | ||
05ef58ec SP |
29 | There are other real-world examples of using update and |
30 | post-update hooks found in the Documentation/howto directory. | |
b1bf95bb | 31 | |
ba020ef5 | 32 | 'git-receive-pack' honours the receive.denyNonFastForwards config |
05ef58ec SP |
33 | option, which tells it if updates to a ref should be denied if they |
34 | are not fast-forwards. | |
35 | ||
c08db5a2 JK |
36 | A number of other receive.* config options are available to tweak |
37 | its behavior, see linkgit:git-config[1]. | |
38 | ||
05ef58ec SP |
39 | OPTIONS |
40 | ------- | |
f6a8ef07 | 41 | <git-dir>:: |
05ef58ec SP |
42 | The repository to sync into. |
43 | ||
98e2d9d6 ÆAB |
44 | --http-backend-info-refs:: |
45 | Used by linkgit:git-http-backend[1] to serve up | |
46 | `$GIT_URL/info/refs?service=git-receive-pack` requests. See | |
47 | `--http-backend-info-refs` in linkgit:git-upload-pack[1]. | |
48 | ||
76a8788c | 49 | PRE-RECEIVE HOOK |
05ef58ec SP |
50 | ---------------- |
51 | Before any ref is updated, if $GIT_DIR/hooks/pre-receive file exists | |
f43cd49f SP |
52 | and is executable, it will be invoked once with no parameters. The |
53 | standard input of the hook will be one line per ref to be updated: | |
05ef58ec | 54 | |
f43cd49f | 55 | sha1-old SP sha1-new SP refname LF |
05ef58ec | 56 | |
f43cd49f SP |
57 | The refname value is relative to $GIT_DIR; e.g. for the master |
58 | head this is "refs/heads/master". The two sha1 values before | |
05ef58ec | 59 | each refname are the object names for the refname before and after |
967506bb JK |
60 | the update. Refs to be created will have sha1-old equal to 0\{40}, |
61 | while refs to be deleted will have sha1-new equal to 0\{40}, otherwise | |
05ef58ec SP |
62 | sha1-old and sha1-new should be valid objects in the repository. |
63 | ||
a85b377d JH |
64 | When accepting a signed push (see linkgit:git-push[1]), the signed |
65 | push certificate is stored in a blob and an environment variable | |
66 | `GIT_PUSH_CERT` can be consulted for its object name. See the | |
d05b9618 JH |
67 | description of `post-receive` hook for an example. In addition, the |
68 | certificate is verified using GPG and the result is exported with | |
69 | the following environment variables: | |
70 | ||
71 | `GIT_PUSH_CERT_SIGNER`:: | |
72 | The name and the e-mail address of the owner of the key that | |
73 | signed the push certificate. | |
74 | ||
75 | `GIT_PUSH_CERT_KEY`:: | |
76 | The GPG key ID of the key that signed the push certificate. | |
77 | ||
78 | `GIT_PUSH_CERT_STATUS`:: | |
79 | The status of GPG verification of the push certificate, | |
80 | using the same mnemonic as used in `%G?` format of `git log` | |
81 | family of commands (see linkgit:git-log[1]). | |
a85b377d | 82 | |
b89363e4 JH |
83 | `GIT_PUSH_CERT_NONCE`:: |
84 | The nonce string the process asked the signer to include | |
85 | in the push certificate. If this does not match the value | |
86 | recorded on the "nonce" header in the push certificate, it | |
87 | may indicate that the certificate is a valid one that is | |
88 | being replayed from a separate "git push" session. | |
89 | ||
90 | `GIT_PUSH_CERT_NONCE_STATUS`:: | |
91 | `UNSOLICITED`;; | |
92 | "git push --signed" sent a nonce when we did not ask it to | |
93 | send one. | |
94 | `MISSING`;; | |
95 | "git push --signed" did not send any nonce header. | |
96 | `BAD`;; | |
97 | "git push --signed" sent a bogus nonce. | |
98 | `OK`;; | |
99 | "git push --signed" sent the nonce we asked it to send. | |
5732373d JH |
100 | `SLOP`;; |
101 | "git push --signed" sent a nonce different from what we | |
102 | asked it to send now, but in a previous session. See | |
103 | `GIT_PUSH_CERT_NONCE_SLOP` environment variable. | |
104 | ||
105 | `GIT_PUSH_CERT_NONCE_SLOP`:: | |
106 | "git push --signed" sent a nonce different from what we | |
107 | asked it to send now, but in a different session whose | |
108 | starting time is different by this many seconds from the | |
109 | current session. Only meaningful when | |
110 | `GIT_PUSH_CERT_NONCE_STATUS` says `SLOP`. | |
da0005b8 | 111 | Also read about `receive.certNonceSlop` variable in |
5732373d | 112 | linkgit:git-config[1]. |
b89363e4 | 113 | |
05ef58ec SP |
114 | This hook is called before any refname is updated and before any |
115 | fast-forward checks are performed. | |
116 | ||
117 | If the pre-receive hook exits with a non-zero exit status no updates | |
118 | will be performed, and the update, post-receive and post-update | |
119 | hooks will not be invoked either. This can be useful to quickly | |
120 | bail out if the update is not to be supported. | |
b1bf95bb | 121 | |
eaeed077 JK |
122 | See the notes on the quarantine environment below. |
123 | ||
76a8788c | 124 | UPDATE HOOK |
05ef58ec SP |
125 | ----------- |
126 | Before each ref is updated, if $GIT_DIR/hooks/update file exists | |
127 | and is executable, it is invoked once per ref, with three parameters: | |
b1bf95bb | 128 | |
05ef58ec | 129 | $GIT_DIR/hooks/update refname sha1-old sha1-new |
b1bf95bb | 130 | |
05ef58ec SP |
131 | The refname parameter is relative to $GIT_DIR; e.g. for the master |
132 | head this is "refs/heads/master". The two sha1 arguments are | |
133 | the object names for the refname before and after the update. | |
134 | Note that the hook is called before the refname is updated, | |
967506bb | 135 | so either sha1-old is 0\{40} (meaning there is no such ref yet), |
05ef58ec SP |
136 | or it should match what is recorded in refname. |
137 | ||
138 | The hook should exit with non-zero status if it wants to disallow | |
139 | updating the named ref. Otherwise it should exit with zero. | |
140 | ||
141 | Successful execution (a zero exit status) of this hook does not | |
02783075 | 142 | ensure the ref will actually be updated, it is only a prerequisite. |
05ef58ec SP |
143 | As such it is not a good idea to send notices (e.g. email) from |
144 | this hook. Consider using the post-receive hook instead. | |
145 | ||
76a8788c | 146 | POST-RECEIVE HOOK |
05ef58ec SP |
147 | ----------------- |
148 | After all refs were updated (or attempted to be updated), if any | |
149 | ref update was successful, and if $GIT_DIR/hooks/post-receive | |
04c8ce9c | 150 | file exists and is executable, it will be invoked once with no |
f43cd49f SP |
151 | parameters. The standard input of the hook will be one line |
152 | for each successfully updated ref: | |
05ef58ec | 153 | |
f43cd49f | 154 | sha1-old SP sha1-new SP refname LF |
05ef58ec | 155 | |
f43cd49f SP |
156 | The refname value is relative to $GIT_DIR; e.g. for the master |
157 | head this is "refs/heads/master". The two sha1 values before | |
05ef58ec SP |
158 | each refname are the object names for the refname before and after |
159 | the update. Refs that were created will have sha1-old equal to | |
967506bb JK |
160 | 0\{40}, while refs that were deleted will have sha1-new equal to |
161 | 0\{40}, otherwise sha1-old and sha1-new should be valid objects in | |
05ef58ec SP |
162 | the repository. |
163 | ||
d05b9618 | 164 | The `GIT_PUSH_CERT*` environment variables can be inspected, just as |
a85b377d JH |
165 | in `pre-receive` hook, after accepting a signed push. |
166 | ||
05ef58ec SP |
167 | Using this hook, it is easy to generate mails describing the updates |
168 | to the repository. This example script sends one mail message per | |
a85b377d | 169 | ref listing the commits pushed to the repository, and logs the push |
d05b9618 | 170 | certificates of signed pushes with good signatures to a logger |
a85b377d | 171 | service: |
b1bf95bb | 172 | |
38cadf9e MÅ |
173 | ---- |
174 | #!/bin/sh | |
175 | # mail out commit update information. | |
176 | while read oval nval ref | |
177 | do | |
178 | if expr "$oval" : '0*$' >/dev/null | |
a85b377d | 179 | then |
38cadf9e MÅ |
180 | echo "Created a new ref, with the following commits:" |
181 | git rev-list --pretty "$nval" | |
182 | else | |
183 | echo "New commits:" | |
184 | git rev-list --pretty "$nval" "^$oval" | |
185 | fi | | |
186 | mail -s "Changes to ref $ref" commit-list@mydomain | |
187 | done | |
188 | # log signed push certificate, if any | |
189 | if test -n "${GIT_PUSH_CERT-}" && test ${GIT_PUSH_CERT_STATUS} = G | |
190 | then | |
191 | ( | |
192 | echo expected nonce is ${GIT_PUSH_NONCE} | |
193 | git cat-file blob ${GIT_PUSH_CERT} | |
194 | ) | mail -s "push certificate from $GIT_PUSH_CERT_SIGNER" push-log@mydomain | |
195 | fi | |
196 | exit 0 | |
197 | ---- | |
2a245013 | 198 | |
05ef58ec SP |
199 | The exit code from this hook invocation is ignored, however a |
200 | non-zero exit code will generate an error message. | |
19614330 | 201 | |
05ef58ec SP |
202 | Note that it is possible for refname to not have sha1-new when this |
203 | hook runs. This can easily occur if another user modifies the ref | |
ba020ef5 | 204 | after it was updated by 'git-receive-pack', but before the hook was able |
05ef58ec SP |
205 | to evaluate it. It is recommended that hooks rely on sha1-new |
206 | rather than the current value of refname. | |
19614330 | 207 | |
76a8788c | 208 | POST-UPDATE HOOK |
05ef58ec SP |
209 | ---------------- |
210 | After all other processing, if at least one ref was updated, and | |
211 | if $GIT_DIR/hooks/post-update file exists and is executable, then | |
04c8ce9c | 212 | post-update will be called with the list of refs that have been updated. |
05ef58ec | 213 | This can be used to implement any repository wide cleanup tasks. |
eb0362a4 | 214 | |
05ef58ec | 215 | The exit code from this hook invocation is ignored; the only thing |
ba020ef5 | 216 | left for 'git-receive-pack' to do at that point is to exit itself |
05ef58ec | 217 | anyway. |
eb0362a4 | 218 | |
483bc4f0 | 219 | This hook can be used, for example, to run `git update-server-info` |
05ef58ec SP |
220 | if the repository is packed and is served via a dumb transport. |
221 | ||
38cadf9e MÅ |
222 | ---- |
223 | #!/bin/sh | |
224 | exec git update-server-info | |
225 | ---- | |
2a245013 | 226 | |
6d35cc76 | 227 | |
76a8788c | 228 | QUARANTINE ENVIRONMENT |
eaeed077 JK |
229 | ---------------------- |
230 | ||
231 | When `receive-pack` takes in objects, they are placed into a temporary | |
232 | "quarantine" directory within the `$GIT_DIR/objects` directory and | |
233 | migrated into the main object store only after the `pre-receive` hook | |
234 | has completed. If the push fails before then, the temporary directory is | |
235 | removed entirely. | |
236 | ||
237 | This has a few user-visible effects and caveats: | |
238 | ||
239 | 1. Pushes which fail due to problems with the incoming pack, missing | |
240 | objects, or due to the `pre-receive` hook will not leave any | |
241 | on-disk data. This is usually helpful to prevent repeated failed | |
242 | pushes from filling up your disk, but can make debugging more | |
243 | challenging. | |
244 | ||
245 | 2. Any objects created by the `pre-receive` hook will be created in | |
246 | the quarantine directory (and migrated only if it succeeds). | |
247 | ||
248 | 3. The `pre-receive` hook MUST NOT update any refs to point to | |
249 | quarantined objects. Other programs accessing the repository will | |
250 | not be able to see the objects (and if the pre-receive hook fails, | |
d8f4481c JK |
251 | those refs would become corrupted). For safety, any ref updates |
252 | from within `pre-receive` are automatically rejected. | |
eaeed077 JK |
253 | |
254 | ||
6d35cc76 JH |
255 | SEE ALSO |
256 | -------- | |
d49483f0 | 257 | linkgit:git-send-pack[1], linkgit:gitnamespaces[7] |
6d35cc76 | 258 | |
2a245013 JH |
259 | GIT |
260 | --- | |
9e1f0a85 | 261 | Part of the linkgit:git[1] suite |