Skip to content
Tutorials Center
My learning

Topics

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.

Terminal
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

Bash A short alias for a repository

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.

Bash pushInsteadOf and the longest prefix

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

Terminal
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 -v also 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 an includeIf for one directory).
  • pushInsteadOf and remote.<name>.pushurl solve similar problems: pushurl sets an explicit push URL for one remote, while pushInsteadOf rewrites 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 treats name:path as an SSH-style URL otherwise.
  • Debugging: GIT_TRACE=1 git fetch prints the URL that was actually used.