Using the git config insteadof directive

Kenny DuMez
Kenny DuMez
Graphite software engineer


Note

This guide explains this concept in vanilla Git. For Graphite documentation, see our CLI docs.


In this guide, we'll explore how to simplify Git repository URLs using the git config command, specifically focusing on the insteadOf directive. This feature allows you to create shortcut aliases for long URLs, which can be especially handy for developers who frequently interact with multiple remote repositories that have lengthy URLs.

The git config command is a utility tool used to set Git configuration values on a global or local project level. These configurations control various aspects of Git's behavior. The insteadOf directive within git config is particularly useful for shortening remote repository URLs, making them easier to remember and use.

The insteadOf directive allows you to specify a shorthand alias for a portion of a URL. When you use the alias in a Git command, Git will replace it with the full URL. This feature can streamline commands and scripts where you interact with remote repositories.

To configure these URL shortcuts globally, so they apply to all your Git projects, you use the git config --global option. Below, we'll go through several examples of how to use insteadOf to simplify repository management.

Suppose you often access various remote repositories on GitHub and have to constantly input the entire URL of the Git repository. You can set a shorter alias like gh: to replace https://github.com/.

Terminal
git config --global url."https://github.com/".insteadOf "gh:"

With this configuration, any Git command that uses gh: will automatically expand to https://github.com/. Thus the repository URL https://github.com/your-org-name/your-repo-name becomes gh:your-org-name-your-repo-name.git

You can set up multiple shortcuts for different Git platforms. For instance, to add a shortcut for GitLab as well, you can run:

Terminal
git config --global url."https://gitlab.com/".insteadOf "gl:"

Now, you can use gl: in place of the full GitLab URL. Similarly to the above example, the URL https://gitlab.com/your-org-name/your-repo-name becomes gl:your-org-name-your-repo-name.git.

For repositories located in deeper subdirectories or those that use HTTPS with authentication, shortcuts can be even more beneficial. For example, to simplify the URL for a specific repository group or namespace you can run:

Terminal
git config --global url."https://github.com/your-org-name/".insteadOf "org:"

Then you can access the full URL of your various repos by simply typing org:your-repo-name.git.

With the shortcuts set, here’s how you would clone repositories using your new aliases:

  • Cloning from GitHub:

    Terminal
    git clone gh:MyRepository.git

    This expands to:

    Terminal
    git clone https://github.com/MyRepository.git
  • Cloning from GitLab:

    Terminal
    git clone gl:AnotherRepo.git

    This expands to:

    Terminal
    git clone https://gitlab.com/AnotherRepo.git

To see all configurations related to URL handling, including your insteadOf settings, you can use:

Terminal
git config --global --get-regexp url.*

This command will list all URL-related configurations that are set globally.

Using insteadOf can simplify the interaction with remote repositories, especially when dealing with multiple platforms or long URLs. It reduces the chance of errors in typing URLs and speeds up the process of setting up new repositories for cloning, pushing, and pulling.

For further reading on the insteadOf configuration directive, see the official Git documentation.

Graphite
Git stacked on GitHub

Stacked pull requests are easier to read, easier to write, and easier to manage.
Teams that stack ship better software, faster.

Or install our CLI.
Product Screenshot 1
Product Screenshot 2