#git-repository #github #git #git-remote #local-git #gitlab #fork

app add-remote

An interactive CLI tool to add a remote fork to a local Git repository

10 stable releases

3.0.3 Jun 9, 2024
3.0.1 Nov 27, 2020
2.2.2 Apr 13, 2019
2.0.1 Jun 24, 2018
0.9.0 Aug 20, 2017

#40 in Development tools

Download history 22/week @ 2024-04-01 120/week @ 2024-06-03 237/week @ 2024-06-10

357 downloads per month

Apache-2.0 OR MIT

827 lines


An interactive CLI tool to add a remote fork to a local Git repository. When run from a Git repo, it queries GitLab or GitHub as appropriate for the full list of forks and offers simple choices for adding one under a local alias. The added fork will be configured with a pull-url only; the push-url will be disabled.

Demonstration of add-remote


cargo install add-remote


Simply cd to a Git repository and run add-remote.


add-remote will display all forks which aren't currently copied locally, then ask you to choose one and to provide an alias for it.

Preferred Fork

It will offer a default selection (i.e. just hit return to select it) if it can. The default will be chosen as follows:

  • if there's only one fork available, it will be selected, or else
  • the main fork/source owner if not already added locally, or else
  • the fork indicated by the Git config value of add-remote.preferredFork if set, and if that fork is not already added locally

You can set add-remote.preferredFork (e.g. to CasperLabs) by running:

git config --global --add add-remote.preferredFork CasperLabs

Fork Aliases

Having chosen the fork to add, you will then be asked to provide an alias for it. Again, a default value will be presented, chosen as follows:

  • if this is the main fork/source owner, uses the Git config value of add-remote.mainForkOwnerAlias if set, or else uses "upstream"
  • uses the Git config value from the map of aliases under the subkey add-remote.forkAlias if set
  • uses the fork-owner's name

You can set add-remote.mainForkOwnerAlias (e.g. to owner) by running:

git config --global --add add-remote.mainForkOwnerAlias owner

Default aliases can be added to your .gitconfig file under the subkey add-remote.forkAlias.<owner's name> by running e.g:

git config --global --add add-remote.forkAlias.anthonywilliams Anthony
git config --global --add add-remote.forkAlias.hsutter Herb

Personal Access Tokens

To use add-remote with any GitLab repository or with a private GitHub one, you need to provide a Personal Access Token via git config.

For GitLab, create a token ensuring it has "read_api" scope, then add it to your .gitconfig:

git config --global --add add-remote.gitLabToken <GitLab Token's Value>

For GitHub, create a token ensuring it has full "repo" scope, then add it along with your GitHub username separated with a colon : to your .gitconfig:

git config --global --add add-remote.gitHubToken <GitHub Username:GitHub Token's Value>

Having run these Git config commands, your .gitconfig should contain the following:

    preferredFork = CasperLabs
    mainForkOwnerAlias = owner
    gitLabToken = <GitLab Token's Value>
    gitHubToken = <GitHub Username:GitHub Token's Value>
[add-remote "forkAlias"]
    anthonywilliams = Anthony
    hsutter = Herb


add-remote only works with projects hosted on GitLab or GitHub.


Licensed under either of

at your option.


Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.


~234K SLoC