HOWTO · Git

How to Configure a Proxy to Work With Git

Configure HTTP, HTTPS, and SOCKS proxies for Git, choose a setting scope, and inspect or remove proxy settings.

On this page

When a corporate firewall blocks Git traffic, configure Git to send requests through your organization’s proxy. You can apply a proxy to one command, save it in the current repository, or save it globally for your user. The examples use documentation-only hostnames and credentials; replace them with values supplied by your network administrator.

Choose a proxy protocol and scope

HTTP, HTTPS, SOCKS4, and SOCKS5 identify proxy URL schemes or proxy protocol options. The destination URL and proxy URL describe different connections: for example, Git can fetch an https:// destination through an http:// proxy. They do not need to match.

Use git -c http.proxy=PROXY_URL COMMAND to set a proxy for one Git command. A repository-local setting applies in the current repository, while --global saves a setting in your user-level Git configuration and affects your repositories. A system-level setting may also be supplied by an administrator. More specific applicable settings can override broader ones, so inspect the effective value when behavior differs from what you expect.

Proxy URLs containing usernames or passwords may require URL encoding for reserved characters. Avoid putting real credentials in shared commands, scripts, or shell history. Use an approved credential helper or your organization’s secret-handling method when available.

Configure an HTTP proxy

For a single operation, add the proxy with Git’s -c option. For example, the inline command git -c http.proxy=http://proxy.example:8080 clone https://git.example/team/project.git applies the proxy only to that clone. Substitute the proxy host and port provided by your administrator.

You can also set a proxy only for a matching destination URL by using the URL-specific key http.https://git.example.proxy. This is useful when other Git hosts should connect directly or use a different proxy. The URL pattern is matched by Git’s URL configuration rules, so use the destination scheme and host you actually access.

Run this example with a temporary Git config file. It stores a sample HTTP proxy value and reads it back; it does not change your repository or user configuration.

set -eu
config_file="$(mktemp)"
trap 'rm -f "$config_file"' EXIT
git config --file "$config_file" http.proxy http://proxy.example:8080
git config --file "$config_file" --get http.proxy

Configure an HTTPS proxy for Git traffic

For an HTTPS destination, configure the proxy against that destination, such as http.https://git.example.proxy. The proxy itself may still use an http:// URL; that describes the connection from Git to the proxy, while HTTPS describes the destination connection. If your proxy endpoint supports TLS, use the HTTPS proxy scheme specified by your administrator.

An error such as unable to access 'https://...': Unknown SSL protocol error in connection to ...:443 is a clue that the proxy and destination connection may not be negotiating as expected. Check the proxy scheme, host, port, and firewall policy first. If the proxy intercepts TLS, configure Git to trust the certificate authority your organization provides, using the documented certificate configuration for your environment. Do not turn off certificate verification as a routine fix: that removes protection against an untrusted or intercepted connection. If an administrator asks you to use a temporary verification override for diagnosis, limit it to one command and restore normal verification immediately afterward.

Save proxy settings in Git configuration

To store a proxy for the current repository, run git config http.proxy http://proxy.example:8080 from that repository. To save the same setting for your user across repositories, use git config --global http.proxy http://proxy.example:8080. These saved settings persist until changed or removed. A destination-specific value can be stored with git config --global http.https://git.example.proxy http://proxy.example:8080.

The http.proxy key is a Git configuration setting; --global is a command-line option that selects user-level scope. Use repository-local configuration when only one checkout needs the proxy, and global configuration when the same network route applies to your Git work generally. Check with your administrator before saving credentials in either scope because configuration files can be copied or backed up.

Inspect and remove proxy settings

List HTTP-related settings and their origins with git config --show-origin --get-regexp '^http\.'. The command git config --get http.proxy checks only the generic http.proxy value. To check the effective proxy setting applicable to an HTTPS destination, use git config --get-urlmatch http.proxy https://git.example, replacing the URL with the destination you need to reach. A missing result means no matching value was found for that query; other configuration scopes may still supply one.

Remove a repository-local proxy with git config --unset-all http.proxy. Remove a global one with git config --global --unset-all http.proxy. For a destination-specific entry, replace the key with the exact configured key, for example http.https://git.example.proxy. If you added an SSL verification override, remove that key at the same scope as well, such as git config --unset-all http.sslVerify or git config --global --unset-all http.sslVerify.

Removing one key does not clear every proxy setting. Repeat the inspection for the repository and global scopes, and remove any URL-specific entries separately. --unset-all removes all values for that key at the selected scope; it does not change broader, narrower, or system configuration.

Configure a SOCKS proxy in Git

Git proxy URLs can use socks4:// or socks5:// when the proxy service supports that protocol. For a one-command operation, use a form such as git -c http.proxy=socks5://proxy.example:1080 fetch. To save a general SOCKS5 proxy for your user, run git config --global http.proxy socks5://proxy.example:1080; for a particular HTTPS destination, use git config --global http.https://git.example.proxy socks5://proxy.example:1080.

Choose SOCKS4 or SOCKS5 according to the service and authentication support configured by your organization. Keep the scheme spelling exact, use the assigned port, and inspect the resulting Git configuration if a request still bypasses the proxy or cannot connect.