git-receive-pack
Receive what is pushed into the repository
SYNOPSIS
git-receive -pack <directory>
DESCRIPTION
Invoked by gitsend -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 gitsend -pack side, and the program pair is meant to be used to push updates to remote repository . For pull operations, see 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 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: .RS 4
sha1 -old SP sha1 -new SP refname LF .RE 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 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 gitlog family of commands (see 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 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 .
sha1 -old SP sha1 -new SP refname LF .RE 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 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 gitlog family of commands (see 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 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 .
"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: .RS 4
sha1 -old SP sha1 -new SP refname LF .RE 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: .RS 4
#!/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 .RE 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 .
sha1 -old SP sha1 -new SP refname LF .RE 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: .RS 4
#!/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 .RE 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 gitupdate -server -info if the repository is packed and is served via a dumb transport . .RS 4
#!/bin/sh exec git update -server -info .RE
#!/bin/sh exec git update -server -info .RE
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: '-04' 1. '+01' .sp -1
" 1." 4.2 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 . '-04' 2. '+01' .sp -1
" 2." 4.2 Any objects created by the pre-receive hook will be created in the quarantine directory (and migrated only if it succeeds) . '-04' 3. '+01' .sp -1
" 3." 4.2 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 .
" 1." 4.2 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 . '-04' 2. '+01' .sp -1
" 2." 4.2 Any objects created by the pre-receive hook will be created in the quarantine directory (and migrated only if it succeeds) . '-04' 3. '+01' .sp -1
" 3." 4.2 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 .
GIT
Part of the git (1)suite
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: .RS 4
$GIT_DIR/hooks/update refname sha1 -old sha1 -new .RE 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 .
$GIT_DIR/hooks/update refname sha1 -old sha1 -new .RE 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 .
SEE ALSO
git-send-pack(1), gitnamespaces(7)
