253 lines
9.1 KiB
Plaintext
253 lines
9.1 KiB
Plaintext
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
|