Git proxy settings

The Necessity of Git Proxy Settings

Git proxy settings are crucial for developers, especially in corporate network environments or under certain special network conditions. Accessing remote repositories through a proxy server can resolve issues like connection timeouts and slow speeds, as well as bypass certain network restrictions.

HTTP/HTTPS Proxy Configuration

Git supports using a proxy when accessing remote repositories via the HTTP/HTTPS protocol. The configuration methods are as follows:

# Set global HTTP proxy
git config --global http.proxy http://proxy.example.com:8080

# Set global HTTPS proxy
git config --global https.proxy https://proxy.example.com:8080

# Remove proxy settings
git config --global --unset http.proxy
git config --global --unset https.proxy

To set a proxy for a specific repository, omit the --global parameter:

git config http.proxy http://proxy.example.com:8080

SOCKS Proxy Configuration

For proxy servers using the SOCKS protocol, Git also provides support:

# Set SOCKS5 proxy
git config --global http.proxy socks5://127.0.0.1:1080
git config --global https.proxy socks5://127.0.0.1:1080

# Or use SOCKS5h (supports DNS resolution via proxy)
git config --global http.proxy socks5h://127.0.0.1:1080
git config --global https.proxy socks5h://127.0.0.1:1080

SSH Protocol Proxy Configuration

Proxy configuration for the SSH protocol requires settings in the SSH configuration file:

# Edit the ~/.ssh/config file
Host github.com
    User git
    ProxyCommand nc -X 5 -x 127.0.0.1:1080 %h %p

For Windows systems, use the connect.exe tool:

Host github.com
    User git
    ProxyCommand connect -S 127.0.0.1:1080 %h %p

Setting Proxy via Environment Variables

In addition to Git configuration, proxies can also be set via environment variables:

# Linux/macOS
export http_proxy="http://proxy.example.com:8080"
export https_proxy="http://proxy.example.com:8080"

# Windows
set http_proxy=http://proxy.example.com:8080
set https_proxy=http://proxy.example.com:8080

Proxy Authentication

If the proxy server requires authentication, include the username and password in the URL:

git config --global http.proxy http://username:password@proxy.example.com:8080

Or use environment variables:

export http_proxy="http://username:password@proxy.example.com:8080"

Excluding Specific Domains from Proxy

In some cases, you may need to exclude internal domains from using the proxy:

git config --global http.proxy http://proxy.example.com:8080
git config --global http.noProxy "example.com,*.example.org,localhost"

Viewing Current Proxy Configuration

To view the current proxy settings:

git config --global --get http.proxy
git config --global --get https.proxy

Priority of Proxy Settings

The priority of Git proxy settings, from highest to lowest, is:

1. Repository-local configuration
2. Global configuration
3. Environment variables

Troubleshooting Common Issues

Proxy Connection Failure: Check if the proxy address and port are correct and ensure the proxy server is running properly.

SSL Certificate Issues: You can temporarily disable SSL verification (not recommended for production environments):

git config --global http.sslVerify false

Slow Proxy Speed: Try switching to a different proxy server or check the network conditions.

Cross-Platform Proxy Setting Differences

Windows systems may require additional configuration:

# For Git Bash
git config --global http.proxy 'http://127.0.0.1:1080'
git config --global https.proxy 'http://127.0.0.1:1080'

# For CMD/PowerShell
git config --global http.proxy http://127.0.0.1:1080
git config --global https.proxy http://127.0.0.1:1080

Using PAC Files for Automatic Proxy Configuration

For complex proxy environments, PAC files can be used:

// Example PAC file content
function FindProxyForURL(url, host) {
    if (shExpMatch(host, "*.github.com")) {
        return "PROXY proxy.example.com:8080";
    }
    return "DIRECT";
}

Then reference it in the Git configuration:

git config --global http.proxy pac+http://example.com/proxy.pac

Practical Scenarios for Proxy Settings

1. Corporate Intranet Development: Access external Git repositories via a corporate proxy.
2. Cross-Border Collaboration: Resolve access issues to platforms like GitHub.
3. CI/CD Environments: Configure proxies on build servers to access private repositories.

Advanced Proxy Configuration Techniques

For scenarios requiring frequent proxy switching, create aliases:

# Add to .bashrc or .zshrc
alias git-proxy-on="git config --global http.proxy http://127.0.0.1:1080"
alias git-proxy-off="git config --global --unset http.proxy"

Or use scripts to automatically detect network environments and switch proxies:

#!/bin/bash
if ping -c 1 github.com &> /dev/null; then
    git config --global --unset http.proxy
else
    git config --global http.proxy http://127.0.0.1:1080
fi

Proxy Settings and Git Submodules

When using Git submodules, proxy settings are automatically inherited from the parent repository. To set a proxy specifically for a submodule, run the configuration command in the submodule directory.

Proxy Settings and Git LFS

Git LFS also follows Git's proxy configuration, but large file transfers may require additional adjustments:

git config --global lfs.http.proxy http://proxy.example.com:8080

Persisting Proxy Settings

To synchronize proxy settings across different machines, include the configuration in a Git include file:

# Create ~/.gitconfig-proxy
[http]
    proxy = http://proxy.example.com:8080

# Reference in the main configuration file
[include]
    path = ~/.gitconfig-proxy

Security Considerations for Proxy Settings

1. Avoid storing passwords in plaintext in configuration files.
2. Use SSH key authentication instead of HTTP basic authentication.
3. Regularly check and update proxy configurations.
4. Disable proxies for internal networks.

Debugging Proxy Settings

When the proxy isn't working, use the following commands to debug:

GIT_CURL_VERBOSE=1 git clone https://github.com/example/repo.git
GIT_TRACE=1 git clone https://github.com/example/repo.git