Skip to main content

Create working trees of other Git repositories and track them in your parent repository.

Project description


The git-subrepo command is a tool to create a worktree of a remote Git repository and tracking its files.

Advantages over submodules

  • Avoid depending on the longevity of the submodule's remote repository
  • Track changes to the sub repository in the parent


You can get the latest stable version from PyPI. We recommended creating an alias in your Git configuration file so you can access the tool via the git command-line.

$ pip install nr.git-subrepo
$ git config --global alias.subrepo '!nr git-subrepo'
$ git subrepo --version

You may choose to install the tool directly from the source repository. This allows you to get the latest development version.

$ pip install git+
$ git subrepo --version

Usage Example

Any time that you think about adding a Git submodule, you can add a sub repository instead. The git subrepo tool allows you to conveniently add, remove and stage sub repositories. It also provides you with a tool to convert existing Git submodules to sub repositories.

To add a new sub repository:

$ git subrepo add -s

Similar to git submodule, the add command will use the basename of the provided URL as the default path to place the Git worktree at. In the case above, it will be ./library.

$ git -C library remote get-url origin
$ git status
Changes to be committed:
    new file: .gitsubrepos
    new file: library/

The -s option in the add command is used to automatically stage the added sub repository. You can use the git subrepo stage command instead to explicitly add all changes in the sub repository and the proper Git ref to the .gitsubrepos file.

If you have uncommited changes in a sub repository, your changes will be reflected for your sub repository only inside the parent repository. They will not be reflected in the actual sub repository or its remote.

Copyright © 2018 Niklas Rosenstein

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for nr.git-subrepo, version 1.0.1
Filename, size File type Python version Upload date Hashes
Filename, size nr.git-subrepo-1.0.1.tar.gz (7.5 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page