git-receive-pack

git-receive-pack [--quiet] [--stateless-rpc] [--exec-cmd=cmd] [--exec-path=path] [--not-from-email] directory

directory
    The path to the Git repository where changes will be received.

--quiet
    Suppress all output from git-receive-pack.

--stateless-rpc
    Enable stateless RPC mode, typically used with the smart HTTP protocol to handle requests that do not maintain state across multiple connections.

--exec-cmd=cmd
    For internal use. Specifies the command to execute, overriding the default Git command logic.

--exec-path=path
    For internal use. Specifies the path to search for Git programs when executing internal commands.

--not-from-email
    For internal use. Indicates that the operation is not originating from an email-based push (e.g., git-am).

git-receive-pack is an essential plumbing command within Git, primarily responsible for handling incoming Git object data and reference updates during a git push operation. It runs on the remote server where the repository resides. When a client executes git push, it communicates with the server, which invokes git-receive-pack to receive the compressed pack-file containing new or updated Git objects (commits, trees, blobs, tags). This command validates the received objects and then attempts to update the corresponding references (branches, tags) in the remote repository.

It enforces various rules, such as ensuring fast-forward updates by default and executing server-side hooks (pre-receive, update, post-receive) to allow administrators to implement custom logic, security checks, or integrate with external systems. It’s a low-level component that users rarely invoke directly, instead relying on higher-level commands like git push to orchestrate its execution over various transport protocols like SSH or the native Git protocol.

git-receive-pack is a low-level plumbing command and is not intended for direct invocation by end-users; it's automatically called by git push on the remote server. Proper file system permissions are crucial for the repository directory. Server-side hooks (pre-receive, update, post-receive) are executed by this command and can abort a push based on custom logic or policies, making them vital for repository management and security.

git-receive-pack operates over various transport protocols, including SSH, the native Git protocol (often via git-daemon), and the smart HTTP protocol. It handles the specific negotiation and data transfer mechanisms for each, making it adaptable to different deployment scenarios.

This command invokes three critical server-side hooks during a push operation:
pre-receive: Executed once before any references are updated. It can be used to enforce project-wide policies, such as checking commit messages or preventing specific changes.
update: Executed once for each reference being updated. It provides a per-reference control point, allowing administrators to restrict updates to certain branches or tags based on specific criteria.
post-receive: Executed once after all references have been successfully updated. This hook is commonly used for integration tasks, such as triggering CI/CD pipelines, sending notifications, or deploying code.

git-receive-pack is responsible for validating the integrity of the incoming pack-file and ensuring that reference updates (e.g., branch fast-forwards) adhere to Git's rules. By default, it only permits 'fast-forward' pushes, preventing non-linear history changes unless explicitly forced by the client using git push --force.

As a core component of Git's distributed nature, git-receive-pack has been an integral part of the Git project since its early development. Its design evolved alongside the Git protocol and the git push command, enabling secure and efficient transmission of repository changes and reference updates across network boundaries. It underpins Git's ability to allow multiple developers to contribute to a shared repository.

git-push(1), git-upload-pack(1), git-hooks(5), git-send-pack(1)