Managing Monorepos with Git Submodules: A Practical Guide

Introduction
What Are Git Submodules?
Setting Up a Monorepo with Submodules
Common Workflows (TLDR Style)
Managing Multiple Projects
Common Pitfalls and Solutions
Advanced Tips
Conclusion

1. Introduction

In modern software development, managing multiple projects within a single repository (monorepo) can streamline workflows and make code sharing easier. The most important value provided by monorepos is visibility - they give your team a unified view of the codebase, making it easier to understand dependencies, share code, and coordinate changes across projects. While dedicated monorepo tools like Lerna, Nx, or Turborepo offer sophisticated features, Git submodules provide a built-in solution that works across any technology stack.

This post documents my experience using Git submodules with monorepos.

2. What Are Git Submodules?

Git submodules allow you to keep a Git repository as a subdirectory of another Git repository. This lets you clone another repository into your project and keep your commits separate.

3. Setting Up a Monorepo with Submodules

3.1 Creating a New Monorepo

# Create the parent monorepo
mkdir my-monorepo
cd my-monorepo
git init
echo "# My Monorepo" > README.md
git add README.md
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/username/my-monorepo.git
git push -u origin main

3.2 Adding Existing Projects as Submodules

# From the monorepo root
git submodule add https://github.com/username/project-one.git packages/project-one
git submodule add https://github.com/username/project-two.git packages/project-two
git commit -m "Add project-one and project-two as submodules"
git push

3.3 Cloning a Monorepo with Submodules

# Option 1: Clone with submodules in one step
git clone --recurse-submodules https://github.com/username/my-monorepo.git

# Option 2: Clone first, then initialize submodules
git clone https://github.com/username/my-monorepo.git
cd my-monorepo
git submodule init
git submodule update

4. Common Workflows (TLDR Style)

4.1 Scenario 1: Working on a Submodule

# Navigate to the submodule
cd packages/project-one

# Create a branch
git checkout -b feature/new-feature

# Make changes, commit and push
git add .
git commit -m "Add new feature"
git push origin feature/new-feature

# Update the monorepo to point to the new commit
cd ../..
git add packages/project-one
git commit -m "Update project-one submodule"
git push

4.2 Scenario 2: Extracting an Existing Directory into a Submodule

# Create a new repo from the directory
cd my-monorepo/existing-dir
git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/username/extracted-project.git
git push -u origin main

# Remove directory from monorepo (but keep files)
cd ../
git rm --cached -r existing-dir
git commit -m "Remove directory in preparation for submodule"

# Add as submodule
git submodule add https://github.com/username/extracted-project.git existing-dir
git commit -m "Add extracted-project as submodule"
git push

4.3 Scenario 3: Updating All Submodules to Latest

# Update all submodules to latest on their tracked branch
git submodule update --remote
git add .
git commit -m "Update all submodules to latest version"
git push

4.4 Scenario 4: Creating a New Submodule from Scratch

# Create the repository first
mkdir new-module
cd new-module
git init
echo "# New Module" > README.md
git add README.md
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/username/new-module.git
git push -u origin main

# Go back to monorepo root and add as submodule
cd ..
git submodule add https://github.com/username/new-module.git packages/new-module
git commit -m "Add new-module as submodule"
git push

4.5 Scenario 5: Removing a Submodule

# Remove the submodule entry from .git/config
git submodule deinit -f packages/project-two

# Remove the submodule from .git/modules
rm -rf .git/modules/packages/project-two

# Remove the submodule files from the working tree and index
git rm -f packages/project-two

# Commit the changes
git commit -m "Remove project-two submodule"

5. Managing Multiple Projects

One of the advantages of using submodules in a monorepo is handling multiple projects effectively, regardless of their technology stack:

# Add various projects as submodules
git submodule add https://github.com/username/service-one.git services/service-one
git submodule add https://github.com/username/frontend-app.git frontend/frontend-app
git submodule add https://github.com/username/shared-lib.git libs/shared-lib

# Work on any project
cd services/service-one
# Install dependencies, build, etc. according to the project's requirements

6. Common Pitfalls and Solutions

6.1 Detached HEAD State

When you first check out a submodule, you'll be in a detached HEAD state.

Problem:

cd packages/project-one
git status
# HEAD detached at 1a2b3c4

Solution:

# If you want to make changes, checkout a branch first
git checkout main
# Or create a new branch
git checkout -b feature/my-changes

6.2 Forgetting to Push Submodule Changes

Problem: You've committed changes in a submodule but forgotten to push them.

Solution: Always push submodule changes before pushing the monorepo:

cd packages/project-one
git push origin main
cd ../..
git add packages/project-one
git commit -m "Update project-one submodule"
git push

6.3 Keeping Submodules in Sync

Problem: Team members have different versions of submodules.

Solution: After pulling the monorepo, update submodules:

git pull
git submodule update --init --recursive

6.4 Empty Repositories as Submodules

Problem: You can't add an empty repository as a submodule.

Solution: Initialize the repository with at least one commit before adding it as a submodule.

7. Advanced Tips

7.1 Using Specific Commits or Tags

cd packages/project-one
git checkout v1.0.0  # Checkout a specific tag
cd ../..
git add packages/project-one
git commit -m "Point project-one to v1.0.0"

7.2 Working with Branches in Submodules

# Configure submodules to track branches
git config -f .gitmodules submodule.packages/project-one.branch develop

# Update to the latest commit on the tracked branch
git submodule update --remote packages/project-one

7.3 Configuring IDE Support

Most modern IDEs like VS Code, JetBrains IDEs, and Visual Studio have good support for Git submodules. You might need to install specific extensions or configure settings for optimal experience.

8. Conclusion

Git submodules provide a powerful way to manage multiple projects within a monorepo structure. While they come with some complexity, understanding these common workflows makes working with submodules straightforward and efficient.

The enhanced visibility that monorepos provide is truly their greatest strength. By keeping related projects together, you gain a comprehensive view of your entire system, making it easier to understand relationships between components, track changes across projects, and ensure consistent standards across your codebase.

This approach works well across any technology stack. By separating concerns into submodules, you can maintain independent version histories while still keeping the convenience of a unified codebase view.

Remember to communicate with your team about submodule workflows to ensure everyone understands how to work with the repository structure effectively.

Table of Contents