| '\" t |
| .\" Title: git-receive-pack |
| .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] |
| .\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/> |
| .\" Date: 12/09/2018 |
| .\" Manual: Git Manual |
| .\" Source: Git 2.20.0 |
| .\" Language: English |
| .\" |
| .TH "GIT\-RECEIVE\-PACK" "1" "12/09/2018" "Git 2\&.20\&.0" "Git Manual" |
| .\" ----------------------------------------------------------------- |
| .\" * Define some portability stuff |
| .\" ----------------------------------------------------------------- |
| .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| .\" http://bugs.debian.org/507673 |
| .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html |
| .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| .ie \n(.g .ds Aq \(aq |
| .el .ds Aq ' |
| .\" ----------------------------------------------------------------- |
| .\" * set default formatting |
| .\" ----------------------------------------------------------------- |
| .\" disable hyphenation |
| .nh |
| .\" disable justification (adjust text to left margin only) |
| .ad l |
| .\" ----------------------------------------------------------------- |
| .\" * MAIN CONTENT STARTS HERE * |
| .\" ----------------------------------------------------------------- |
| .SH "NAME" |
| git-receive-pack \- Receive what is pushed into the repository |
| .SH "SYNOPSIS" |
| .sp |
| .nf |
| \fIgit\-receive\-pack\fR <directory> |
| .fi |
| .sp |
| .SH "DESCRIPTION" |
| .sp |
| Invoked by \fIgit send\-pack\fR and updates the repository with the information fed from the remote end\&. |
| .sp |
| This command is usually not invoked directly by the end user\&. The UI for the protocol is on the \fIgit send\-pack\fR side, and the program pair is meant to be used to push updates to remote repository\&. For pull operations, see \fBgit-fetch-pack\fR(1)\&. |
| .sp |
| The command allows for creation and fast\-forwarding of sha1 refs (heads/tags) on the remote end (strictly speaking, it is the local end \fIgit\-receive\-pack\fR runs, but to the user who is sitting at the send\-pack end, it is updating the remote\&. Confused?) |
| .sp |
| There are other real\-world examples of using update and post\-update hooks found in the Documentation/howto directory\&. |
| .sp |
| \fIgit\-receive\-pack\fR honours the receive\&.denyNonFastForwards config option, which tells it if updates to a ref should be denied if they are not fast\-forwards\&. |
| .sp |
| A number of other receive\&.* config options are available to tweak its behavior, see \fBgit-config\fR(1)\&. |
| .SH "OPTIONS" |
| .PP |
| <directory> |
| .RS 4 |
| The repository to sync into\&. |
| .RE |
| .SH "PRE\-RECEIVE HOOK" |
| .sp |
| 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: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| sha1\-old SP sha1\-new SP refname LF |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| 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\&. |
| .sp |
| When accepting a signed push (see \fBgit-push\fR(1)), the signed push certificate is stored in a blob and an environment variable \fBGIT_PUSH_CERT\fR can be consulted for its object name\&. See the description of \fBpost\-receive\fR hook for an example\&. In addition, the certificate is verified using GPG and the result is exported with the following environment variables: |
| .PP |
| \fBGIT_PUSH_CERT_SIGNER\fR |
| .RS 4 |
| The name and the e\-mail address of the owner of the key that signed the push certificate\&. |
| .RE |
| .PP |
| \fBGIT_PUSH_CERT_KEY\fR |
| .RS 4 |
| The GPG key ID of the key that signed the push certificate\&. |
| .RE |
| .PP |
| \fBGIT_PUSH_CERT_STATUS\fR |
| .RS 4 |
| The status of GPG verification of the push certificate, using the same mnemonic as used in |
| \fB%G?\fR |
| format of |
| \fBgit log\fR |
| family of commands (see |
| \fBgit-log\fR(1))\&. |
| .RE |
| .PP |
| \fBGIT_PUSH_CERT_NONCE\fR |
| .RS 4 |
| 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\&. |
| .RE |
| .PP |
| \fBGIT_PUSH_CERT_NONCE_STATUS\fR |
| .RS 4 |
| .PP |
| \fBUNSOLICITED\fR |
| .RS 4 |
| "git push \-\-signed" sent a nonce when we did not ask it to send one\&. |
| .RE |
| .PP |
| \fBMISSING\fR |
| .RS 4 |
| "git push \-\-signed" did not send any nonce header\&. |
| .RE |
| .PP |
| \fBBAD\fR |
| .RS 4 |
| "git push \-\-signed" sent a bogus nonce\&. |
| .RE |
| .PP |
| \fBOK\fR |
| .RS 4 |
| "git push \-\-signed" sent the nonce we asked it to send\&. |
| .RE |
| .PP |
| \fBSLOP\fR |
| .RS 4 |
| "git push \-\-signed" sent a nonce different from what we asked it to send now, but in a previous session\&. See |
| \fBGIT_PUSH_CERT_NONCE_SLOP\fR |
| environment variable\&. |
| .RE |
| .RE |
| .PP |
| \fBGIT_PUSH_CERT_NONCE_SLOP\fR |
| .RS 4 |
| "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 |
| \fBGIT_PUSH_CERT_NONCE_STATUS\fR |
| says |
| \fBSLOP\fR\&. Also read about |
| \fBreceive\&.certNonceSlop\fR |
| variable in |
| \fBgit-config\fR(1)\&. |
| .RE |
| .sp |
| This hook is called before any refname is updated and before any fast\-forward checks are performed\&. |
| .sp |
| 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\&. |
| .sp |
| See the notes on the quarantine environment below\&. |
| .SH "UPDATE HOOK" |
| .sp |
| Before each ref is updated, if $GIT_DIR/hooks/update file exists and is executable, it is invoked once per ref, with three parameters: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| $GIT_DIR/hooks/update refname sha1\-old sha1\-new |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| 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\&. |
| .sp |
| The hook should exit with non\-zero status if it wants to disallow updating the named ref\&. Otherwise it should exit with zero\&. |
| .sp |
| 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\&. |
| .SH "POST\-RECEIVE HOOK" |
| .sp |
| 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: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| sha1\-old SP sha1\-new SP refname LF |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| 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\&. |
| .sp |
| The \fBGIT_PUSH_CERT*\fR environment variables can be inspected, just as in \fBpre\-receive\fR hook, after accepting a signed push\&. |
| .sp |
| 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: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| #!/bin/sh |
| # mail out commit update information\&. |
| while read oval nval ref |
| do |
| if expr "$oval" : \(aq0*$\(aq >/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 |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| The exit code from this hook invocation is ignored, however a non\-zero exit code will generate an error message\&. |
| .sp |
| 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 \fIgit\-receive\-pack\fR, 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\&. |
| .SH "POST\-UPDATE HOOK" |
| .sp |
| 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\&. |
| .sp |
| The exit code from this hook invocation is ignored; the only thing left for \fIgit\-receive\-pack\fR to do at that point is to exit itself anyway\&. |
| .sp |
| This hook can be used, for example, to run \fBgit update\-server\-info\fR if the repository is packed and is served via a dumb transport\&. |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| #!/bin/sh |
| exec git update\-server\-info |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .SH "QUARANTINE ENVIRONMENT" |
| .sp |
| When \fBreceive\-pack\fR takes in objects, they are placed into a temporary "quarantine" directory within the \fB$GIT_DIR/objects\fR directory and migrated into the main object store only after the \fBpre\-receive\fR hook has completed\&. If the push fails before then, the temporary directory is removed entirely\&. |
| .sp |
| This has a few user\-visible effects and caveats: |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 1.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 1." 4.2 |
| .\} |
| Pushes which fail due to problems with the incoming pack, missing objects, or due to the |
| \fBpre\-receive\fR |
| 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\&. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 2.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 2." 4.2 |
| .\} |
| Any objects created by the |
| \fBpre\-receive\fR |
| hook will be created in the quarantine directory (and migrated only if it succeeds)\&. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 3.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 3." 4.2 |
| .\} |
| The |
| \fBpre\-receive\fR |
| 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 |
| \fBpre\-receive\fR |
| are automatically rejected\&. |
| .RE |
| .SH "SEE ALSO" |
| .sp |
| \fBgit-send-pack\fR(1), \fBgitnamespaces\fR(7) |
| .SH "GIT" |
| .sp |
| Part of the \fBgit\fR(1) suite |