git-nested

An alternative to git-submodule and git-subtree for managing nested repositories.

📖 Documentation: https://thorsten-klein.github.io/git-nested/

What is git-nested?

git-nested puts another git repository into a folder of your repository. The files are ordinary files in ordinary commits. You can still pull new changes from the other repository, and push your changes back to it.

git nested clone https://github.com/user/lib ext/lib   # copy it in
git nested pull ext/lib                                # get new upstream changes
git nested push ext/lib                                # send your changes back
git nested status                                      # see where everything stands

A small .gitnested file in the folder remembers the URL, the branch and the upstream commit. So the commands stay short.

Why git-nested?

• Self-contained. Your repository has all files. A plain git clone gets everything. No access to the other repositories is needed.
• Simple. The commands feel like git.
• Clean history. By default one pull is one commit.
• Flexible. Each branch can have its nested repositories in another state.
• Safe to try. Everything is a normal commit. git reset undoes it.

Only people who pull or push nested repositories need git-nested. See Compared to submodule and subtree.

Install

pip install git-nested

git 2.23 and Python 3.10 or newer are needed. There is also a standalone executable that needs no Python. See Install git-nested for all ways, shell completion and the manual page.

Documentation

The full documentation is in doc/, and online at https://thorsten-klein.github.io/git-nested/.

• About git-nested
• git-nested in 5 minutes
• Everyday tasks
• How it works
• Command reference
• The .gitnested file
• Guides: conflicts, partial upstreams, pins, submodules and more

Help on the command line:

git nested --help          # the manual page
git nested pull --help     # one command: what it does, its options, examples

Contributing

Pull requests are welcome. See Development for the setup and the checks. The short version:

uv sync          # install everything
uv run poe all   # every check CI runs

Report security problems as described in SECURITY.md.

Authors

git-nested:

• Thorsten Klein - Python rewrite and enhancements

Original git-subrepo authors:

• Ingy döt Net - Original concept and implementation
• Magnus Carlsson - Contributor
• Austin Morgan - Contributor

License

MIT. See LICENSE.

Acknowledgments

This project is based on git-subrepo by Ingy döt Net. git-nested is a Python rewrite with some modified features and improvements.