There are many scenarios when you want to clone a git repository inside another git repository, mainly when your project depends on another library, which is not available through pip for various reasons. You might have heard about Git Submodule. It gives a complete solution to refer to and track revisions of another repo inside your main repo. But it introduces extra complexity, confusion, and learning curves. For small projects, instead of Git Submodule, we recommend directly cloning a repo inside another repo for so-called repo nesting.
1. Use case when you need Repo Nesting – pyrulechat
pyrulechat is an open-source rule-based chatbot engine. It is designed to be directly integrated into your Python project. Its source code also needs to be slightly modified to fit your project. This is a perfect use case you should consider repo nesting.
2. How to Manually Nest Repositories
To manually nest a repository within another, follow these steps:
2.1 Navigate to Your Main Project’s Root Directory
You can nest another repo anywhere in your main project’s repo. Usually, you want to keep another repo in the main project’s root or ./lib/ directory.
Follow this tutorial if you don’t know how to check out a private Git repository.
2.2 Clone the second Repo
Let’s still take pyrulechat as an example.
git clone https://github.com/wholehope/pyrulechat.git2.3 Ask Main Repo Ignore the second Repo
At this point, under your main repo. You’ll notice pyrulechat directory is untracked by git status.
You do not want your main repo to be aware of the second repo. You can edit .gitignore of the main repo to exclude pyrulechat. You’ll also need to push .gitignore to remote.
As shown in the diagram, add pyrulechat/ in .gitignore.
2.4. Clarifying git nesting in README.md
Adding step-by-step instructions in your README.md to let others know how they should clone your repo.
# How to Clone
mia-chat uses open-source pyrulechat. After clone the main repo mia-chat, you'll also need to clone pyrulechat repo under mia-chat.
```bash
git clone https://github.com/chatmia/mia-chat.git
cd mia-chat
git clone https://github.com/wholehope/pyrulechat.git
```2.5 Check your git config
Since you effectively use two different repos, double check your git config’s user user.name and user.email are what you want them to appear in those two repositories.
git config --list
git config user.name "Your Name"
git config user.email "your_email@example.com"3. Pros of Manual Repository Nesting
- Simplicity: This approach is straightforward, requiring no Git submodule commands. It’s as simple as cloning a repository and adding a line to
.gitignore. - Flexibility: You have complete control over the nested repository without affecting your main project’s Git history.
- Ease of Updates: Updating the nested repository is as simple as navigating to its directory and pulling the latest changes.
4. Cons of Manual Repository Nesting
- Lack of Version Tracking: The main repository doesn’t track the nested repository’s version. This can lead to issues if your project depends on a specific version of the nested repository.
- No Direct Repository Link: The connection between your project and the nested repository isn’t as straightforward as with submodules. New team members might not immediately realize the nested repository’s importance or role.
- Potential for Confusion: This method can be confusing, especially in large teams where clarity and explicit dependency management are crucial.
- Manual Updates: Unlike submodules that let you update all dependencies with a single command, you must manually navigate to and update each nested repository.
5. Conclusion
For small projects, I recommend using direct clone and nesting. For larger projects or if a good number of people are working on a project, I recommend using Git Submodule. You can get a good idea of Git Submodule (a good tutorial) on YouTube.