Git Reference ยท Configuration Options
url.<base>.insteadOf setting
Reference for url.<base>.insteadOf and pushInsteadOf: rewrite URL prefixes so short aliases work, HTTPS becomes SSH, or mirrors replace slow hosts.
url.<base>.insteadOf tells Git to replace any URL that starts with a given prefix by <base> plus the rest of the URL. It works on every URL Git uses: clones, fetches, pushes, submodule URLs and git ls-remote. Typical uses are short aliases (gh:user/repo), forcing SSH instead of HTTPS, and redirecting to a nearby mirror, all without editing any repository.
pushInsteadOf does the same but only for pushes, so you can fetch over HTTPS and push over SSH.
git config --global url."[email protected]:".insteadOf "https://github.com/" git config --global url."[email protected]:".pushInsteadOf "https://github.com/" git config --global url."https://mirror.example.com/".insteadOf "https://upstream.example.com/"
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Syntax
git config url.<base>.insteadOf <prefix> git config url.<base>.pushInsteadOf <prefix> git ls-remote --get-url <remote-or-url>
| Name | Description |
|---|---|
<base> |
The replacement prefix, which becomes the subsection name (quote it in the command line). |
insteadOf |
A URL prefix to replace with <base> for every operation. Can be set several times for one base. |
pushInsteadOf |
A prefix to replace only when pushing. Takes precedence over insteadOf for pushes. |
How it works: Git compares the URL with every configured prefix, picks the longest prefix that matches the beginning, and swaps it for <base>. The stored remote URL is not modified; the rewrite happens each time the URL is used.
Edge cases: the match is plain text and case-sensitive. A prefix that matches nothing does nothing and gives no warning. Rewriting happens once; the result is not rewritten again.
Usage notes
- Use
git ls-remote --get-url <remote>to see the final URL after rewriting.git remote -valso shows rewritten fetch and push URLs, as the second example demonstrates. - HTTPS to SSH (
url."[email protected]:".insteadOf "https://github.com/") is the common fix for tools that hard-code HTTPS URLs, including submodules and dependency managers that call Git. - Rewrites apply to submodules too, which makes it easy to point a project's submodules at an internal mirror without changing
.gitmodules. - Do not commit it to shared config files unless everyone wants it; this is usually a personal or CI-machine setting (
--global, or anincludeIffor one directory). pushInsteadOfandremote.<name>.pushurlsolve similar problems:pushurlsets an explicit push URL for one remote, whilepushInsteadOfrewrites a prefix for many.- Local aliases like
work:are not valid Git URL schemes by themselves; the alias works only because the rewrite turns it into a real URL before use. Git treatsname:pathas an SSH-style URL otherwise. - Debugging:
GIT_TRACE=1 git fetchprints the URL that was actually used.