git-http-backend
Serve Git repositories over HTTP
SYNOPSIS
Typically invoked by a web server as a CGI or FastCGI script, not directly by a user. The common invocation pattern from a web server's perspective looks like this: git-http-backend
Its behavior is primarily controlled by environment variables set by the web server and Git configuration settings within the repository or system.
PARAMETERS
GIT_PROJECT_ROOT
Specifies the base directory from which Git repositories are served. The path requested by the client is interpreted relative to this root. This environment variable must be set for git-http-backend to function correctly.
GIT_HTTP_EXPORT_ALL
If set to "true" or "1", all Git repositories under GIT_PROJECT_ROOT are made available for fetching, even if they don't contain a git-daemon-export-ok file. This setting overrides the per-repository export control.
GIT_HTTP_MAX_REQUEST_BUFFER
Defines the maximum size in bytes of the request body that git-http-backend will read from the web server. This helps prevent very large or malicious requests from consuming excessive memory.
GIT_DIR
Usually set automatically by the web server based on the URL path to point to the specific Git repository being accessed (e.g., /path/to/repo.git).
REMOTE_USER
Set by the web server after successful authentication. git-http-backend can use this variable for authorization checks if configured, but typically it's the web server's responsibility to handle access control.
GIT_HTTP_LOW_SPEED_LIMIT / GIT_HTTP_LOW_SPEED_TIME
Similar to curl's options, these detect too-slow clients or connections. If the transfer speed drops below GIT_HTTP_LOW_SPEED_LIMIT bytes per second for GIT_HTTP_LOW_SPEED_TIME seconds, the connection is aborted. Useful for mitigating denial-of-service attacks.
GIT_HTTP_UPLOAD_PACK_REQUEST_DEFLATE
If set to "1", enables deflate compression for the request body of the git-upload-pack protocol.
GIT_HTTP_RECEIVE_PACK_REQUEST_DEFLATE
If set to "1", enables deflate compression for the request body of the git-receive-pack protocol (push operations).
DESCRIPTION
git-http-backend is a server-side program that acts as a Common Gateway Interface (CGI) or FastCGI application to serve Git repositories over HTTP and HTTPS protocols. It is typically invoked by a web server (such as Apache or Nginx) configured to execute CGI scripts. Unlike git-daemon, which operates on its own dedicated port, git-http-backend leverages the web server's existing infrastructure, including its authentication, authorization, logging, and SSL/TLS capabilities.
When a client initiates a Git operation (like git clone, git pull, or git push) over HTTP/S, the web server receives the request and executes git-http-backend. This backend then processes the request, communicates with the Git repository, and sends the appropriate Git protocol responses back to the client via the web server. It supports both "smart" HTTP protocol (efficient pack transfers using git-upload-pack and git-receive-pack) and "dumb" HTTP protocol (simpler file serving for older clients or basic browsing).
It's crucial for git-http-backend to be configured correctly with environment variables, particularly GIT_PROJECT_ROOT, to locate repositories. Pushing functionality is enabled by default in modern Git versions, but can be controlled with the http.receivepack configuration setting.
CAVEATS
1. Direct Invocation: git-http-backend is not intended for direct execution by end-users. It relies on a web server (like Apache, Nginx, or Lighttpd) to handle HTTP requests, set up the environment, and pass data via CGI or FastCGI.
2. Web Server Configuration: Proper functionality heavily depends on correct web server configuration, including mapping URLs to the script, setting necessary environment variables (GIT_PROJECT_ROOT being critical), and configuring authentication and authorization rules.
3. Security: While git-http-backend handles the Git protocol, security (authentication, authorization) is primarily the responsibility of the surrounding web server infrastructure. Misconfigurations can expose repositories.
4. Performance: As a CGI application, each request might spawn a new process, potentially impacting performance for high-traffic servers. FastCGI or more advanced setups can mitigate this.
5. Push Support: Pushing over HTTP/S requires the http.receivepack Git configuration option to be enabled (it's often true by default in recent Git versions). The web server must also allow POST requests to the script.
REPOSITORY EXPORT CONTROL
By default, git-http-backend only serves repositories that contain a special file named git-daemon-export-ok in their root directory. This acts as an explicit opt-in mechanism for public access. Alternatively, setting the GIT_HTTP_EXPORT_ALL environment variable to "true" or "1" will override this behavior and make all repositories under GIT_PROJECT_ROOT available for fetching.
ENABLING GIT PUSH OVER HTTP
For clients to be able to push (write) to a repository over HTTP/S, two conditions must be met:
1. The web server must be configured to allow POST requests to the git-http-backend script.
2. The repository being pushed to must have the Git configuration variable http.receivepack set to true. This can be done using `git config http.receivepack true` inside the repository. This setting is often true by default in newer Git versions, but it's important to verify.
HISTORY
The git-http-backend was introduced early in Git's development as a flexible way to serve repositories over standard HTTP/S protocols, leveraging existing web server infrastructure. This allowed for easier integration with corporate networks, firewalls, and existing authentication mechanisms, contrasting with the custom Git protocol served by git-daemon. Its evolution has focused on robustness, performance improvements, and adapting to modern Git protocol features, solidifying its role as a primary method for serving Git repositories, especially in enterprise environments.
SEE ALSO
git-daemon(1), git-upload-pack(1), git-receive-pack(1), gitweb(1), git-config(1)