How to configure a proxy to work with git

Git is a distributed version control system which included a rich set of functionalities. Using git to perform day to day tasks with its minimal set of commands should be easy, but for specific scenario, you're going to need some help.

Quite often, you'll find yourself in a situation where you need to access the git repository from behind a corporate firewall, and even with an authenticating proxy. Chinese users may suffer from this problem a lot, thanks to their Great Firewall that blocks a large amount of the public internet. If you are having problems accessing Github, you may find something useful in our guide on accessing Github in China.

This article is going to help you understand which kind of proxy git supports, how to configure a proxy for git to automatically used every time it needs to download something and how to quickly feed a proxy to its command for one time use.

Git's supported proxy protocols

Git supports only HTTP/HTTPS and SOCKS4/5 proxies. For more information, consult git documentation page.

If you want to use a SOCKS proxy in Linux, you can use the built-in ssh command to open a SOCKS proxy tunnelled to a local HTTP port.

On Windows, you could download an application built for this purpose, which could be PuTTY or MxTunnel. Windows users can also "SOCKSify" git using free software like SocksCap (discontinued), FreeCap or WideCap.

For other exotic protocols like Internet Gopher, SSL, TLS, etc, you have to tunnel them to a local HTTP or SOCKS proxy. The tunnelling process can be done using well-known open source software like Privoxy or Squid. You have to consult their official documentation for the exact steps.

Use a HTTP proxy in git commands

Usually, to use a proxy in a program, you need to edit the configuration file. Git, on the other hand, allows you to feed the proxy directly into the configuration for quick usage. An example command for a HTTP proxy looks like below :

git config --global http.proxy http://username:[email protected]_server.com:port
Code language: PHP (php)

In case you want to specify the proxy for a specific domain, you need to feed its domain name in between http.proxy so that it looks something like :

git config --global http.http://specific_domain.com.proxy http://username:[email protected]_server.com:port
Code language: PHP (php)

Notice that you need to put the full URL of the proxy so that Git can automatically recognize the protocol.

Use a HTTPS proxy in git commands

If you are behind a firewall, or your organization employs man-in-the-middle HTTPS proxying and use their own certificate, the commands will have to change as well.

git config --global http.https://specific_domain.com.proxy http://username:[email protected]_server.com:port git config --global http.https://specific_domain.com.sslVerify false
Code language: PHP (php)

You still put the proxy full URL in between http.proxy, but notice how the URL changes from http://specific_domain.com to https://specific_domain.com.

To help you quickly get around any problem, you could disable SSL verification by setting http.https://specific_domain.com.sslVerify to false like the example above. But for long term use, consider getting the root CA and put it right into Git's configuration file. You can do it either by specifying http.sslCAInfo or http.sslCAPath in the command line as well.

If you have any issues regarding HTTPS/SSL proxies, please consult the following sections on git documentation.

  • http.sslVerify
  • http.sslCAInfo
  • http.sslCAPath
  • http.sslKey
  • http.sslCert
  • http.sslCertPasswordProtected

Configure a proxy permanently in git config file

The settings described above can be converted to permanent configuration in git config file, which often sits in ~/.gitconfig for your users or .git/config inside your repository. Configs can be set globally for all connections from your users by feeding --global switch in the commands.

Setting a global proxy using --global switch

Configure a global proxy if you need all git actions to traverse through the proxy

git config --global http.proxy http://username:[email protected]_server.com:port
Code language: PHP (php)

Set a proxy for only a domain

If you want git to connect to only one or a few domains through proxy, you can insert the domain name as part of the configuration key as following:

git config --global http.https://domain.com.proxy http://username:[email protected]_server.com:port
Code language: PHP (php)

Disable HTTPS verification for troubleshooting errors

If you're getting an unable to access 'https://...': Unknown SSL protocol error in connection to ...:443, then you may switch off SSL verification for the current operation by using the -c http.sslVerify=false option.

git -c http.sslVerify=false clone https://domain.com/example.git
Code language: PHP (php)

Or better yet, change the settings so that from now on every operation on the repository must bypass HTTPS checks

git config http.sslVerify false
Code language: JavaScript (javascript)

Remove proxy setting for a git repository

First you need to list all the proxy settings for the current repository using this command

git config --get-regexp http.*
Code language: JavaScript (javascript)

Then, unset the proxy setting you want with one of the syntax below :

git config --unset http.proxy git config --unset http.https://domain.com.proxy git config --unset http.sslVerify git config --unset http.https://domain.com.sslVerify
Code language: PHP (php)

Remove proxy setting for all git repository

Similar to the method above mentioned, you can unset proxy settings for all git repository by feeding --global into the commands, so they now looks like these

# List all proxy settings git config --global --get-regexp http.* # Or git config --global --get http.proxy # Remove proxy settings git config --global --unset http.proxy git config --global --unset http.https://domain.com.proxy git config --global --unset http.sslVerify git config --global --unset http.https://domain.com.sslVerify
Code language: PHP (php)

Configure a SOCKS proxy in git

Since git 1.6.6, it switches to a smart HTTP protocol similar to that used by ssh:// or git://. The underlying library enabling git's HTTP connection is libcurl, which supports various types of proxies like SOCKS4/4a and SOCKS5.

Connection through a SOCKS5 proxy can simply be done using the same syntax as mentioned earlier in this post, the only difference is the protocol in proxy URL must be changed to socks5:// or socks4://

Use a SOCKS5 proxy globally

git config --global http.proxy socks5://proxy_server.com:port
Code language: PHP (php)

Use a SOCKS5 proxy for a domain

git config --global http.https://domain.com.proxy socks5://proxy_server.com:port
Code language: PHP (php)
Click to rate this post!
[Total: 0 Average: 0]

Leave a Comment