| git-receive-pack(1) |
| =================== |
| |
| NAME |
| ---- |
| git-receive-pack - Receive what is pushed into the repository |
| |
| |
| SYNOPSIS |
| -------- |
| [verse] |
| 'git-receive-pack' <directory> |
| |
| DESCRIPTION |
| ----------- |
| Invoked by 'git send-pack' and updates the repository with the |
| information fed from the remote end. |
| |
| This command is usually not invoked directly by the end user. |
| The UI for the protocol is on the 'git send-pack' side, and the |
| program pair is meant to be used to push updates to remote |
| repository. For pull operations, see linkgit:git-fetch-pack[1]. |
| |
| The command allows for creation and fast-forwarding of sha1 refs |
| (heads/tags) on the remote end (strictly speaking, it is the |
| local end 'git-receive-pack' runs, but to the user who is sitting at |
| the send-pack end, it is updating the remote. Confused?) |
| |
| There are other real-world examples of using update and |
| post-update hooks found in the Documentation/howto directory. |
| |
| 'git-receive-pack' honours the receive.denyNonFastForwards config |
| option, which tells it if updates to a ref should be denied if they |
| are not fast-forwards. |
| |
| A number of other receive.* config options are available to tweak |
| its behavior, see linkgit:git-config[1]. |
| |
| OPTIONS |
| ------- |
| <directory>:: |
| The repository to sync into. |
| |
| pre-receive Hook |
| ---------------- |
| Before any ref is updated, if $GIT_DIR/hooks/pre-receive file exists |
| and is executable, it will be invoked once with no parameters. The |
| standard input of the hook will be one line per ref to be updated: |
| |
| sha1-old SP sha1-new SP refname LF |
| |
| The refname value is relative to $GIT_DIR; e.g. for the master |
| head this is "refs/heads/master". The two sha1 values before |
| each refname are the object names for the refname before and after |
| the update. Refs to be created will have sha1-old equal to 0\{40}, |
| while refs to be deleted will have sha1-new equal to 0\{40}, otherwise |
| sha1-old and sha1-new should be valid objects in the repository. |
| |
| When accepting a signed push (see linkgit:git-push[1]), the signed |
| push certificate is stored in a blob and an environment variable |
| `GIT_PUSH_CERT` can be consulted for its object name. See the |
| description of `post-receive` hook for an example. In addition, the |
| certificate is verified using GPG and the result is exported with |
| the following environment variables: |
| |
| `GIT_PUSH_CERT_SIGNER`:: |
| The name and the e-mail address of the owner of the key that |
| signed the push certificate. |
| |
| `GIT_PUSH_CERT_KEY`:: |
| The GPG key ID of the key that signed the push certificate. |
| |
| `GIT_PUSH_CERT_STATUS`:: |
| The status of GPG verification of the push certificate, |
| using the same mnemonic as used in `%G?` format of `git log` |
| family of commands (see linkgit:git-log[1]). |
| |
| `GIT_PUSH_CERT_NONCE`:: |
| The nonce string the process asked the signer to include |
| in the push certificate. If this does not match the value |
| recorded on the "nonce" header in the push certificate, it |
| may indicate that the certificate is a valid one that is |
| being replayed from a separate "git push" session. |
| |
| `GIT_PUSH_CERT_NONCE_STATUS`:: |
| `UNSOLICITED`;; |
| "git push --signed" sent a nonce when we did not ask it to |
| send one. |
| `MISSING`;; |
| "git push --signed" did not send any nonce header. |
| `BAD`;; |
| "git push --signed" sent a bogus nonce. |
| `OK`;; |
| "git push --signed" sent the nonce we asked it to send. |
| `SLOP`;; |
| "git push --signed" sent a nonce different from what we |
| asked it to send now, but in a previous session. See |
| `GIT_PUSH_CERT_NONCE_SLOP` environment variable. |
| |
| `GIT_PUSH_CERT_NONCE_SLOP`:: |
| "git push --signed" sent a nonce different from what we |
| asked it to send now, but in a different session whose |
| starting time is different by this many seconds from the |
| current session. Only meaningful when |
| `GIT_PUSH_CERT_NONCE_STATUS` says `SLOP`. |
| Also read about `receive.certNonceSlop` variable in |
| linkgit:git-config[1]. |
| |
| This hook is called before any refname is updated and before any |
| fast-forward checks are performed. |
| |
| If the pre-receive hook exits with a non-zero exit status no updates |
| 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 |
| and is executable, it is invoked once per ref, with three parameters: |
| |
| $GIT_DIR/hooks/update refname sha1-old sha1-new |
| |
| The refname parameter is relative to $GIT_DIR; e.g. for the master |
| head this is "refs/heads/master". The two sha1 arguments are |
| the object names for the refname before and after the update. |
| Note that the hook is called before the refname is updated, |
| so either sha1-old is 0\{40} (meaning there is no such ref yet), |
| or it should match what is recorded in refname. |
| |
| The hook should exit with non-zero status if it wants to disallow |
| updating the named ref. Otherwise it should exit with zero. |
| |
| Successful execution (a zero exit status) of this hook does not |
| ensure the ref will actually be updated, it is only a prerequisite. |
| As such it is not a good idea to send notices (e.g. email) from |
| this hook. Consider using the post-receive hook instead. |
| |
| post-receive Hook |
| ----------------- |
| After all refs were updated (or attempted to be updated), if any |
| ref update was successful, and if $GIT_DIR/hooks/post-receive |
| file exists and is executable, it will be invoked once with no |
| parameters. The standard input of the hook will be one line |
| for each successfully updated ref: |
| |
| sha1-old SP sha1-new SP refname LF |
| |
| The refname value is relative to $GIT_DIR; e.g. for the master |
| head this is "refs/heads/master". The two sha1 values before |
| each refname are the object names for the refname before and after |
| the update. Refs that were created will have sha1-old equal to |
| 0\{40}, while refs that were deleted will have sha1-new equal to |
| 0\{40}, otherwise sha1-old and sha1-new should be valid objects in |
| the repository. |
| |
| The `GIT_PUSH_CERT*` environment variables can be inspected, just as |
| in `pre-receive` hook, after accepting a signed push. |
| |
| Using this hook, it is easy to generate mails describing the updates |
| to the repository. This example script sends one mail message per |
| ref listing the commits pushed to the repository, and logs the push |
| certificates of signed pushes with good signatures to a logger |
| service: |
| |
| #!/bin/sh |
| # mail out commit update information. |
| while read oval nval ref |
| do |
| if expr "$oval" : '0*$' >/dev/null |
| then |
| echo "Created a new ref, with the following commits:" |
| git rev-list --pretty "$nval" |
| else |
| echo "New commits:" |
| git rev-list --pretty "$nval" "^$oval" |
| fi | |
| mail -s "Changes to ref $ref" commit-list@mydomain |
| done |
| # log signed push certificate, if any |
| if test -n "${GIT_PUSH_CERT-}" && test ${GIT_PUSH_CERT_STATUS} = G |
| then |
| ( |
| echo expected nonce is ${GIT_PUSH_NONCE} |
| git cat-file blob ${GIT_PUSH_CERT} |
| ) | mail -s "push certificate from $GIT_PUSH_CERT_SIGNER" push-log@mydomain |
| fi |
| exit 0 |
| |
| The exit code from this hook invocation is ignored, however a |
| non-zero exit code will generate an error message. |
| |
| Note that it is possible for refname to not have sha1-new when this |
| hook runs. This can easily occur if another user modifies the ref |
| after it was updated by 'git-receive-pack', but before the hook was able |
| to evaluate it. It is recommended that hooks rely on sha1-new |
| rather than the current value of refname. |
| |
| post-update Hook |
| ---------------- |
| After all other processing, if at least one ref was updated, and |
| if $GIT_DIR/hooks/post-update file exists and is executable, then |
| post-update will be called with the list of refs that have been updated. |
| This can be used to implement any repository wide cleanup tasks. |
| |
| The exit code from this hook invocation is ignored; the only thing |
| left for 'git-receive-pack' to do at that point is to exit itself |
| anyway. |
| |
| This hook can be used, for example, to run `git update-server-info` |
| if the repository is packed and is served via a dumb transport. |
| |
| #!/bin/sh |
| 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). For safety, any ref updates |
| from within `pre-receive` are automatically rejected. |
| |
| |
| SEE ALSO |
| -------- |
| linkgit:git-send-pack[1], linkgit:gitnamespaces[7] |
| |
| GIT |
| --- |
| Part of the linkgit:git[1] suite |