protocol-capabilities Git Command Guide

The Git protocol capabilities define the features and commands supported by Git clients and servers during network communication. Understanding protocol capabilities is essential for implementing custom Git servers, debugging network issues, and ensuring compatibility between different Git versions.

Git Protocol Architecture:

Protocol Versions:

Git Protocols:
├── Version 0: Original protocol (dumb/HTTP, SSH, Git)
├── Version 1: Pack-based protocol (default)
└── Version 2: Stateless protocol (modern, efficient)

Transport Methods:

Available Transports:
├── Local: file://, /path/to/repo
├── SSH: ssh://, git@github.com:user/repo.git
├── HTTP/HTTPS: https://github.com/user/repo.git
├── Git: git://github.com/user/repo.git
└── Custom: ext::command, etc.

Core Protocol Capabilities:

Essential Capabilities:

Capability	Description	Version
multi_ack	Multiple ACK for efficient negotiation	v1
multi_ack_detailed	Detailed ACK with common commits	v1
no-done	Skip ‘done’ packet for efficiency	v1
thin-pack	Send thin packs to save bandwidth	v1
side-band	Progress reporting during transfer	v1
side-band-64k	64KB side-band for large progress	v1
ofs-delta	Offset-based deltas	v1
agent	Client agent identification	v1

Advanced Capabilities:

Capability	Description	Version
shallow	Shallow clone support	v1
deepen-since	Deepen by date	v1
deepen-not	Exclude specific refs	v1
deepen-relative	Relative deepening	v1
no-progress	Suppress progress reporting	v1
include-tag	Include annotated tags	v1
report-status	Report operation status	v1
delete-refs	Allow ref deletion	v1
quiet	Quiet operation	v1
atomic	Atomic ref updates	v1

Version 2 Capabilities:

Capability	Description
fetch	Fetch command support
server-option	Server option support
object-format	Object format specification
session-id	Session identification
object-info	Object information queries
bundle-uri	Bundle URI support

Protocol Handshake Process:

Version 1 Handshake:

Client → Server: git-upload-pack /project.git
Server → Client: Capabilities list
Client → Server: want/have negotiation
Server → Client: Pack data transfer

Version 2 Handshake:

Client → Server: git-upload-pack /project.git
Server → Client: version 2
Client → Server: command=fetch
Server → Client: capability-advertisement
Client → Server: command parameters
Server → Client: response

Capability Negotiation:

Client Capability Advertisement:

# Client sends supported capabilities
git ls-remote --upload-pack="git upload-pack --advertise-capabilities"
# Output shows server capabilities

# Check specific capability
git ls-remote --upload-pack="git upload-pack" 2>&1 | grep "capability-name"

Server Capability Detection:

# Detect server capabilities
git ls-remote origin
# Implicitly shows supported capabilities

# Verbose capability detection
GIT_TRACE_PACKET=1 git ls-remote origin 2>&1 | head -20

Custom Capability Implementation:

# Implement custom server capability
#!/bin/bash
# Custom Git server with extended capabilities

custom_upload_pack() {
    echo "version 2"
    echo ""
    echo "capability-advertisement"
    echo "fetch"
    echo "server-option"
    echo "object-info"
    echo "custom-feature"
    echo ""
}

# Usage in custom Git server
custom_upload_pack

Transport-Specific Capabilities:

HTTP/HTTPS Capabilities:

HTTP-Specific Capabilities:
├── smart HTTP transport
├── dumb HTTP fallback
├── authentication support
├── proxy support
├── SSL/TLS encryption
└── compression support

SSH Capabilities:

SSH-Specific Capabilities:
├── public key authentication
├── agent forwarding
├── port forwarding
├── connection multiplexing
└── host key verification

Git Protocol Capabilities:

Git-Protocol Capabilities:
├── anonymous access
├── read-only operations
├── firewall-friendly
└── minimal server requirements

Debugging Protocol Issues:

Packet-Level Debugging:

# Enable packet tracing
GIT_TRACE_PACKET=1 git clone <url>

# Trace all Git operations
GIT_TRACE=1 git fetch origin

# Debug specific protocol
GIT_CURL_VERBOSE=1 git clone https://github.com/user/repo.git

Capability Negotiation Debugging:

# Check advertised capabilities
git ls-remote --upload-pack="git upload-pack --advertise-capabilities" <url>

# Test capability support
echo "0000" | git upload-pack --stateless-rpc <url> | head -10

# Debug version negotiation
GIT_TRACE=2 git clone --verbose <url> 2>&1 | grep -i "version\|capability"

Network Issue Diagnosis:

# Test basic connectivity
telnet github.com 9418  # Git protocol
curl -I https://github.com  # HTTPS

# Check DNS resolution
nslookup github.com

# Test SSH connection
ssh -T git@github.com

# Debug proxy issues
export GIT_CURL_VERBOSE=1
export GIT_TRACE_CURL=1

Implementing Custom Git Servers:

Basic Git Server Setup:

#!/bin/bash
# Basic Git server implementation

git_server() {
    local repo_path="$1"
    local command="$2"

    case "$command" in
        "git-upload-pack")
            # Handle fetch/clone operations
            git upload-pack "$repo_path"
            ;;
        "git-receive-pack")
            # Handle push operations
            git receive-pack "$repo_path"
            ;;
        *)
            echo "Unsupported command: $command"
            exit 1
            ;;
    esac
}

# Usage
git_server "/path/to/repo.git" "git-upload-pack"

Advanced Server with Capabilities:

#!/bin/bash
# Advanced Git server with custom capabilities

advanced_git_server() {
    local repo_path="$1"
    local command="$2"

    # Advertise custom capabilities
    echo "version 2"
    echo ""
    echo "capability-advertisement"
    echo "fetch"
    echo "server-option"
    echo "object-info"
    echo "custom-backup"
    echo "custom-mirror"
    echo ""

    # Handle commands
    case "$command" in
        "fetch")
            handle_fetch "$repo_path"
            ;;
        "custom-backup")
            handle_backup "$repo_path"
            ;;
        *)
            echo "Command not supported"
            ;;
    esac
}

handle_fetch() {
    local repo="$1"
    # Implement fetch logic with custom capabilities
    echo "Custom fetch implementation"
}

handle_backup() {
    local repo="$1"
    # Implement backup logic
    echo "Custom backup implementation"
}

Protocol Version Detection:

# Detect client protocol version
detect_protocol_version() {
    local input

    # Read initial client message
    read -r input

    if [[ "$input" == "git-upload-pack "* ]]; then
        echo "Protocol v1 detected"
        handle_v1_protocol "$input"
    elif [[ "$input" == "version 2"* ]]; then
        echo "Protocol v2 detected"
        handle_v2_protocol
    else
        echo "Unknown protocol"
    fi
}

handle_v1_protocol() {
    # Implement v1 protocol handling
    echo "V1 protocol handler"
}

handle_v2_protocol() {
    # Implement v2 protocol handling
    echo "V2 protocol handler"
}

Security Considerations:

Capability-Based Access Control:

# Implement capability-based security
secure_capability_check() {
    local user="$1"
    local capability="$2"
    local repo="$3"

    # Check user permissions for capability
    case "$capability" in
        "receive-pack")
            # Check push permissions
            check_push_permission "$user" "$repo"
            ;;
        "upload-pack")
            # Check pull permissions
            check_pull_permission "$user" "$repo"
            ;;
        "custom-admin")
            # Check admin permissions
            check_admin_permission "$user"
            ;;
        *)
            echo "Unknown capability: $capability"
            return 1
            ;;
    esac
}

# Usage
if secure_capability_check "$USER" "receive-pack" "$REPO"; then
    allow_push
else
    deny_push
fi

Transport Security:

# Configure secure transports
git config --global url."https://".insteadOf git://
git config --global url."ssh://git@".insteadOf https://

# SSH key management
ssh-keygen -t ed25519 -C "git-server"
ssh-copy-id git@server

# Certificate validation
git config --global http.sslVerify true
git config --global http.sslCAInfo /path/to/ca-bundle.crt

Audit Logging:

# Implement protocol audit logging
audit_git_operations() {
    local user="$1"
    local operation="$2"
    local repo="$3"
    local capabilities="$4"

    # Log operation details
    echo "$(date): $user - $operation on $repo (capabilities: $capabilities)" >> git-audit.log

    # Log to centralized system
    curl -X POST "https://audit.example.com/api/log" \
         -H "Content-Type: application/json" \
         -d "{\"user\":\"$user\",\"operation\":\"$operation\",\"repo\":\"$repo\",\"capabilities\":\"$capabilities\"}"
}

# Usage in server
audit_git_operations "$USER" "fetch" "$REPO" "multi_ack,side_band"

Performance Optimization:

Protocol Tuning:

# Optimize protocol performance
git config --global core.compression 9
git config --global pack.compression 9
git config --global transfer.fsckObjects false

# Configure connection pooling
git config --global http.maxRequests 100
git config --global http.minSessions 10

# Enable protocol v2
git config --global protocol.version 2

Server-Side Optimization:

# Optimize Git server performance
git config --global uploadpack.allowFilter true
git config --global uploadpack.allowAnySHA1InWant true
git config --global receive.advertisePushOptions true

# Enable bitmap indexes
git repack -a -d --write-bitmap-index

# Configure large repository handling
git config --global pack.windowMemory "1g"
git config --global pack.packSizeLimit "2g"

Client-Side Optimization:

# Optimize client connections
git config --global http.postBuffer 524288000  # 500MB
git config --global http.lowSpeedLimit 0
git config --global http.lowSpeedTime 999999

# Enable parallel fetching
git config --global fetch.parallel 4
git config --global submodule.fetchJobs 4

Troubleshooting Common Issues:

Capability Mismatch Errors:

# Debug capability negotiation
GIT_TRACE=1 git clone <url> 2>&1 | grep -i "capability\|feature"

# Check server capabilities
git ls-remote --upload-pack="git upload-pack --advertise-capabilities" <url>

# Force protocol version
GIT_PROTOCOL=version=2 git clone <url>

Connection Timeouts:

# Diagnose connection issues
timeout 10 git ls-remote <url>

# Check network connectivity
ping -c 3 $(echo "<url>" | sed 's|.*://||' | cut -d/ -f1)

# Debug SSL issues
openssl s_client -connect $(echo "<url>" | sed 's|https://||' | cut -d/ -f1):443

Protocol Version Conflicts:

# Force specific protocol version
export GIT_PROTOCOL=version=1
git clone <url>

export GIT_PROTOCOL=version=2
git clone <url>

# Check version support
git ls-remote --upload-pack="git upload-pack --advertise-capabilities" <url> | grep "version"

Authentication Failures:

# Debug authentication issues
GIT_CURL_VERBOSE=1 git clone <url>

# Test credentials
echo "url=https://github.com" > ~/.git-credentials
echo "username=your-username" >> ~/.git-credentials
git config --global credential.helper store

# SSH debugging
ssh -v git@github.com

Caution

Protocol capabilities affect Git’s network behavior. Changes can break compatibility. Test thoroughly before deploying custom implementations.

Real-World Usage Examples:

Custom Git Server Implementation:

#!/bin/bash
# Complete custom Git server with capability management

CUSTOM_GIT_SERVER_VERSION="1.0"

custom_git_server() {
    local repo_path="$1"
    local command="$2"

    # Server identification
    echo "# Custom Git Server v$CUSTOM_GIT_SERVER_VERSION"
    echo ""

    # Capability advertisement
    advertise_capabilities

    # Command processing
    process_command "$command" "$repo_path"
}

advertise_capabilities() {
    cat << EOF
version 2
capability-advertisement
fetch
server-option
object-info
custom-stats
custom-backup
custom-mirror

EOF
}

process_command() {
    local command="$1"
    local repo="$2"

    case "$command" in
        "fetch")
            handle_fetch "$repo"
            ;;
        "custom-stats")
            handle_stats "$repo"
            ;;
        "custom-backup")
            handle_backup "$repo"
            ;;
        "custom-mirror")
            handle_mirror "$repo"
            ;;
        *)
            echo "error: unsupported command '$command'"
            exit 1
            ;;
    esac
}

handle_fetch() {
    local repo="$1"
    echo "Starting fetch operation for $repo"

    # Implement fetch with custom capabilities
    git upload-pack "$repo" 2>/dev/null || {
        echo "error: fetch failed"
        exit 1
    }
}

handle_stats() {
    local repo="$1"
    echo "Repository statistics for $repo:"
    echo "Commits: $(git rev-list --all --count)"
    echo "Branches: $(git branch -r | wc -l)"
    echo "Tags: $(git tag | wc -l)"
    echo "Size: $(du -sh "$repo" | cut -f1)"
}

handle_backup() {
    local repo="$1"
    local backup_file="${repo##*/}-backup-$(date +%Y%m%d).bundle"

    echo "Creating backup: $backup_file"
    git bundle create "$backup_file" --all

    echo "Backup created successfully"
}

handle_mirror() {
    local repo="$1"
    local mirror_url="$2"

    echo "Mirroring $repo to $mirror_url"

    # Implement mirroring logic
    git push --mirror "$mirror_url" 2>/dev/null && {
        echo "Mirror updated successfully"
    } || {
        echo "error: mirror update failed"
        exit 1
    }
}

# Usage
# custom_git_server "/path/to/repo.git" "fetch"

Protocol Analysis and Monitoring:

# Analyze Git protocol usage
analyze_protocol_usage() {
    local log_file="$1"

    echo "Protocol Usage Analysis"
    echo "======================="

    # Count protocol versions
    echo "Protocol versions used:"
    grep -o "version [0-9]" "$log_file" | sort | uniq -c | sort -nr

    # Count capabilities requested
    echo ""
    echo "Capabilities requested:"
    grep -o "cap-[a-zA-Z0-9_-]*" "$log_file" | sort | uniq -c | sort -nr | head -10

    # Count commands executed
    echo ""
    echo "Commands executed:"
    grep -o "command=[a-zA-Z0-9_-]*" "$log_file" | sed 's/command=//' | sort | uniq -c | sort -nr

    # Performance metrics
    echo ""
    echo "Performance metrics:"
    grep -o "duration=[0-9.]*" "$log_file" | sed 's/duration=//' | awk '
        {sum+=$1; count++} END {
            if(count>0) {
                print "Average duration:", sum/count, "seconds"
                print "Total operations:", count
            }
        }
    '
}

# Usage
analyze_protocol_usage "/var/log/git-server.log"

Enterprise Protocol Compliance:

# Implement enterprise protocol compliance
enterprise_protocol_compliance() {
    local repo="$1"
    local user="$2"
    local operation="$3"

    echo "Enterprise Protocol Compliance Check"
    echo "===================================="

    # Check protocol version compliance
    if ! check_protocol_version; then
        echo "ERROR: Unsupported protocol version"
        log_compliance_violation "unsupported_protocol" "$user" "$repo"
        exit 1
    fi

    # Check capability compliance
    if ! check_capability_compliance "$operation"; then
        echo "ERROR: Non-compliant capability usage"
        log_compliance_violation "capability_violation" "$user" "$repo"
        exit 1
    fi

    # Check encryption compliance
    if ! check_encryption_compliance; then
        echo "ERROR: Insecure connection detected"
        log_compliance_violation "encryption_violation" "$user" "$repo"
        exit 1
    fi

    # Check rate limiting
    if ! check_rate_limits "$user"; then
        echo "ERROR: Rate limit exceeded"
        log_compliance_violation "rate_limit_exceeded" "$user" "$repo"
        exit 1
    fi

    echo "✓ All compliance checks passed"
}

check_protocol_version() {
    # Implement protocol version checking
    [[ "$GIT_PROTOCOL" =~ ^(version=2|)$ ]]  # Allow v2 or default
}

check_capability_compliance() {
    local operation="$1"
    # Implement capability compliance checking
    case "$operation" in
        "fetch"|"clone")
            return 0  # Allowed
            ;;
        "push")
            # Check push permissions
            return 0  # Implement actual check
            ;;
        *)
            return 1  # Denied
            ;;
    esac
}

check_encryption_compliance() {
    # Check for encrypted connection
    [[ "$GIT_PROTOCOL" == "https" ]] || [[ -n "$SSH_CLIENT" ]]
}

check_rate_limits() {
    local user="$1"
    # Implement rate limiting logic
    return 0  # Placeholder
}

log_compliance_violation() {
    local violation_type="$1"
    local user="$2"
    local repo="$3"

    echo "$(date): COMPLIANCE_VIOLATION - $violation_type - User: $user - Repo: $repo" >> compliance.log

    # Send alert to security team
    # send_security_alert "$violation_type" "$user" "$repo"
}

# Usage in Git hooks
enterprise_protocol_compliance "$REPO" "$USER" "$GIT_COMMAND"

Tip

Understand Git protocol capabilities for implementing custom servers and debugging network issues. Protocol v2 offers better performance and cleaner architecture.

What’s the difference between Git protocol v1 and v2?

V1 uses stateful connections with capability negotiation per operation; V2 uses stateless connections with upfront capability advertisement, better performance and simpler implementation.

How do I check what capabilities a Git server supports?

Use git ls-remote with GIT_TRACE_PACKET=1 to see advertised capabilities, or check server documentation for supported protocol versions.

Can I implement custom protocol capabilities?

Yes, extend Git server with custom capabilities for specialized features. Clients must support the capability or gracefully degrade.

What’s the impact of protocol capabilities on performance?

Proper capability negotiation enables optimizations like thin packs, side-band progress, and efficient delta transfer, significantly improving clone/fetch performance.

How do I debug protocol capability issues?

Use GIT_TRACE=1 and GIT_TRACE_PACKET=1 to trace protocol negotiations, check server logs for capability advertisement, and verify client/server version compatibility.

Can protocol capabilities affect security?

Yes, capabilities control available operations. Implement proper access controls and validate capability usage in custom Git servers.

What’s the relationship between capabilities and Git commands?

Capabilities define what operations are supported. Commands like fetch, push, and clone use different capability sets based on required functionality.

How do I implement capability negotiation in a custom server?

Advertise supported capabilities in initial handshake, parse client requests, validate capability usage, and implement corresponding functionality.

Can I disable specific protocol capabilities?

Configure server to not advertise certain capabilities, or implement access controls that reject unsupported capability usage.

What’s the future of Git protocol capabilities?

Protocol v2 is the current standard with ongoing improvements. New capabilities are added for features like bundle URIs and object info queries.

Applications of Git protocol capabilities

1. Custom Server Implementation: Build specialized Git servers with custom capabilities for enterprise requirements
2. Network Debugging: Diagnose and resolve Git network communication issues using capability analysis
3. Performance Optimization: Leverage protocol capabilities for efficient data transfer and reduced bandwidth usage
4. Security Implementation: Implement access controls and audit trails based on protocol capability usage
5. Compatibility Management: Ensure Git client/server compatibility across different versions and implementations
6. Protocol Evolution: Stay current with Git protocol developments and implement new capabilities as they emerge