Autogenerated manpages for v2.47.0-rc0

[git-manpages.git] / man1 / git-receive-pack.1

'\" 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: 2024-09-25
.\"    Manual: Git Manual
.\"    Source: Git 2.47.0.rc0
.\"  Language: English
.\"
.TH "GIT\-RECEIVE\-PACK" "1" "2024-09-25" "Git 2\&.47\&.0\&.rc0" "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?service=git\-receive\-pack\fR
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
\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