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