git-receive-pack.1 (11780B)
- '\" t
- .\" Title: git-receive-pack
- .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
- .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
- .\" Date: 2025-03-14
- .\" Manual: Git Manual
- .\" Source: Git 2.49.0
- .\" Language: English
- .\"
- .TH "GIT\-RECEIVE\-PACK" "1" "2025-03-14" "Git 2\&.49\&.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 <git\-dir>
- .fi
- .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 a remote repository\&. For pull operations, see \fBgit-fetch-pack\fR(1)\&.
- .sp
- The command allows for the 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
- <git\-dir>
- .RS 4
- The repository to sync into\&.
- .RE
- .PP
- \-\-http\-backend\-info\-refs
- .RS 4
- Used by
- \fBgit-http-backend\fR(1)
- to serve up
- \fB$GIT_URL/info/refs\fR?service=git\-receive\-pack requests\&. See
- \fB\-\-http\-backend\-info\-refs\fR
- in
- \fBgit-upload-pack\fR(1)\&.
- .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 %G? format of
- \fBgit\fR
- \fBlog\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\fR \fBupdate\-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