diff options
Diffstat (limited to 'third_party/git/Documentation/git-receive-pack.txt')
| -rw-r--r-- | third_party/git/Documentation/git-receive-pack.txt | 256 |
1 files changed, 0 insertions, 256 deletions
diff --git a/third_party/git/Documentation/git-receive-pack.txt b/third_party/git/Documentation/git-receive-pack.txt deleted file mode 100644 index 25702ed73072..000000000000 --- a/third_party/git/Documentation/git-receive-pack.txt +++ /dev/null @@ -1,256 +0,0 @@ -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 |