http-push Git Command Guide

The git http-push protocol implements client-side HTTP pushing for sending Git objects and updating references to remote repositories served over HTTP/HTTPS.

HTTP Push Protocol Features:

Reference Updates: Update remote repository branches and tags over HTTP
Atomic Operations: Ensure all-or-nothing reference updates
Authentication Required: Mandatory HTTP authentication for push operations
Efficient Transfer: Use smart HTTP protocol for optimized object pushing
Hook Execution: Trigger server-side hooks during push operations
Security Integration: Work with web server authentication and ACL systems

Protocol Mechanisms:

Push Negotiation:

# Discovery of remote capabilities
GET /repo.git/info/refs?service=git-receive-pack

# Push negotiation and pack sending
POST /repo.git/git-receive-pack
# Client sends reference updates and pack data
# Server responds with status and any errors

Reference Update Format:

<old-sha> <new-sha> <ref-name> LF
# Multiple ref updates in single request
# Empty old-sha for new branches: 0000000000000000000000000000000000000000 <new-sha> refs/heads/feature

Authentication and Security:

HTTP Basic Authentication:

git push https://username:token@github.com/user/repo.git branch
# Or configure credential helper
git config credential.helper store
git push https://github.com/user/repo.git branch

SSL/TLS Configuration:

git config http.sslVerify true
git config http.sslCAInfo /path/to/ca-bundle.crt
git config http.sslCert /path/to/client-cert.pem
git config http.sslKey /path/to/client-key.pem

Access Control Integration:

# Server-side hooks receive authenticated user info
User-Agent: git/2.34.0
Authorization: Basic dXNlcjpwYXNz
Content-Type: application/x-git-receive-pack-request

Push Scenarios and Limitations:

Fast-Forward Push:

# Server accepts if new-sha is descendant of old-sha
0000000000000000000000000000000000000000 1234567890abcdef1234567890abcdef12345678 refs/heads/main

Non-Fast-Forward Push (Requires Force):

# Server rejects unless force push enabled
oldheadsha 1234567890abcdef1234567890abcdef12345678 refs/heads/main

Branch Protection:

# Server can implement custom validation
# Reject pushes to protected branches
# Require code review approvals

git http-push Command Samples:

Basic push to HTTP remote

git push https://git.example.com/repo.git master

Push master branch to HTTP-authenticated repository.

Force push with authentication

git push --force https://user:token@github.com/user/repo.git develop

Force push despite non-fast-forward conflicts.

Push all branches via HTTPS

git push https://user@github.com/user/repo.git --all

Push all local branches to HTTPS remote.

Push with proxy configuration

git -c http.proxy=http://proxy.example.com:8080 push origin

Push through corporate HTTP proxy.

Push with custom SSL settings

git -c http.sslVerify=false push https://internal.git.server/repo.git main

Push bypassing SSL verification (not recommended for production).

Atomic multi-ref push

git push https://git.example.com/repo.git refs/heads/feature1 refs/heads/feature2

Update multiple references atomically over HTTP.

Push new tags

git push https://git.example.com/repo.git --tags

Push all local tags to HTTP remote repository.

Push mirrored repository

git push https://git.example.com/mirror/repo.git --mirror

Mirror complete repository over HTTP push protocol.

Why do HTTP pushes often require authentication while HTTP clones don’t?

Clones are read operations that may be public. Pushes are write operations that always require authentication to prevent unauthorized changes.

Why is HTTP push slower than SSH push?

HTTP has more protocol overhead and connection setup. SSH uses persistent connections and optimized protocol. HTTP push requires full TLS handshake per operation.

Can I push without authentication?

No, HTTP push operations always require authentication. Web server must provide authentication challenge. Anonymous pushes are impossible over HTTP.

How do pre-receive hooks work with HTTP push?

Hooks execute on server after authentication and before references update. Hooks receive authenticated user context and can implement custom authorization logic.

What’s the difference between HTTP and SSH push security?

Both require authentication, but HTTP uses web standards (Basic/Digest/OAuth). SSH uses cryptographic key pairs. HTTP can integrate with enterprise SSO systems.

How do I handle push size limits?

Web servers may impose post size limits. Configure http.postBuffer for large pushes. Server-side nginx/apache may need increased client_max_body_size limits.

Can HTTP push work with Git LFS?

Yes, HTTP push protocol supports Git LFS seamlessly. LFS pointers and actual file uploads work through same authenticated HTTP connections.

How do I migrate from SSH to HTTP push?

Change remote URL from ssh://git@example.com/repo.git to https://git@example.com/repo.git. Configure appropriate authentication mechanism (tokens vs SSH keys).

Why do some pushes fail with “RPC failed” errors?

Usually network timeouts or buffer size issues. Increase http.postBuffer and timeout settings. Check firewall/proxy configurations blocking large POST requests.

Can I push to multiple remotes over HTTP?

Yes, use git push all or configure multiple HTTP remotes. Each push is independent and uses separate HTTP connections.

How do I debug failed HTTP push operations?

Set GIT_CURL_VERBOSE=1 for detailed HTTP logs, check Git version compatibility, verify authentication credentials, and inspect web server error logs.

Applications of the http-push command

Cloud Repository Services: Primary push method for GitHub, GitLab, Bitbucket using HTTPS
Enterprise Firewall Traversal: Push through corporate proxies and firewalls that block SSH
Automation Pipelines: HTTP push in CI/CD systems using tokens/authentication
Shared Hosting: Push to repositories hosted on web servers and platforms
Distributed Teams: HTTP access when team member firewall rules block SSH port
Backup Systems: HTTP as reliable push method for automated backup solutions