How to Merge Git Submodules into Parent Repository Cleanly: Preserving Commit History with an Officially Supported Method

Git submodules are a powerful feature for including external repositories within a parent project, allowing teams to manage dependencies separately. However, over time, you may find that a submodule is no longer necessary as a standalone repository—perhaps the code has become tightly integrated with the parent project, or maintaining a separate repo adds unnecessary complexity. When this happens, merging the submodule into the parent repository while preserving its commit history becomes critical for maintaining traceability and context.

This guide walks through an officially supported Git method to merge a submodule into its parent repository cleanly. We’ll use Git’s built-in subtree merge strategy, which ensures the submodule’s commit history is preserved and its files are seamlessly integrated into the parent project.

Table of Contents#

  1. Understanding Git Submodules: Why Merging Might Be Necessary
  2. Preparation: Backup and Prerequisites
  3. Step 1: Add the Submodule as a Remote in the Parent Repository
  4. Step 2: Fetch the Submodule’s Commit History
  5. Step 3: Merge the Submodule into the Parent Repository with Subtree Strategy
  6. Step 4: Clean Up Submodule Artifacts
  7. Verification: Ensure History and Files Are Preserved
  8. Troubleshooting Common Issues
  9. References

1. Understanding Git Submodules: Why Merging Might Be Necessary#

A Git submodule is a reference to a specific commit in an external repository, stored in the parent project’s .gitmodules file. Submodules keep dependencies isolated, but they introduce complexity:

  • Developers must run git submodule update to fetch submodule code.
  • Submodule commits are not visible in the parent’s history, making debugging harder.
  • CI/CD pipelines may require extra configuration to handle submodules.

Merging a submodule into the parent repo eliminates these pain points by integrating the submodule’s code and history directly into the parent project.

2. Preparation: Backup and Prerequisites#

Before merging, take these critical steps to avoid data loss:

Backup the Parent Repository#

Create a backup branch to revert to if something goes wrong:

# In the parent repository  
git checkout main  # Or your default branch  
git checkout -b backup-before-submodule-merge

Ensure the Submodule is Up-to-Date#

Update the submodule to its latest commit to avoid merging outdated code:

# In the parent repository  
git submodule update --init --recursive  # Fetch submodule code  
cd path/to/submodule  # e.g., vendor/libfoo  
git checkout main  # Or the submodule's default branch  
git pull origin main  # Pull latest changes  
cd -  # Return to parent repo root  
git add path/to/submodule  # Stage the updated submodule commit hash  
git commit -m "Update submodule to latest commit before merging"

Document Submodule Details#

Note the submodule’s:

  • Path in the parent repo (e.g., vendor/libfoo).
  • Remote URL (e.g., https://github.com/example/libfoo.git).
  • Default branch (e.g., main).

3. Step 1: Add the Submodule as a Remote in the Parent Repository#

To merge the submodule’s history into the parent, we first fetch the submodule’s commits into the parent repo. Add the submodule’s repository as a remote in the parent:

# In the parent repository  
git remote add -f submodule-remote https://github.com/example/libfoo.git
  • -f: Fetches the submodule’s commits immediately.
  • submodule-remote: A temporary name for the submodule’s remote (can be any name).

4. Step 2: Fetch the Submodule’s Commit History#

Ensure the parent repo has all the submodule’s commits:

git fetch submodule-remote  # Fetches all branches/tags from the submodule

Verify the submodule’s branches are available:

git branch -r | grep submodule-remote  # Should list submodule-remote/main, etc.

5. Step 3: Merge the Submodule into the Parent Repository with Subtree Strategy#

Use Git’s subtree merge strategy to integrate the submodule’s code into the parent repo while preserving history. This strategy tells Git to align the submodule’s root directory with a specific folder in the parent repo (the original submodule path).

Merge the Submodule’s Branch#

Run the merge command with the subtree strategy, specifying the submodule’s path as the prefix:

# Syntax: git merge -s subtree --no-commit <remote>/<branch> --strategy-option=prefix=<submodule-path>  
git merge -s subtree --no-commit submodule-remote/main --strategy-option=prefix=vendor/libfoo
  • -s subtree: Uses the subtree merge strategy.
  • --no-commit: Stages changes but doesn’t commit, allowing review before finalizing.
  • submodule-remote/main: The submodule’s branch to merge (use your submodule’s default branch).
  • --strategy-option=prefix=vendor/libfoo: Places the submodule’s files into vendor/libfoo (its original path).

Review and Commit the Merge#

Check that the submodule’s files are correctly placed in vendor/libfoo:

ls -la vendor/libfoo  # Verify files exist  
git status  # Should show new/modified files in vendor/libfoo

If everything looks correct, commit the merge:

git commit -m "Merge submodule 'vendor/libfoo' into parent repo"

The parent repo now contains all the submodule’s files and commit history!

6. Step 4: Clean Up Submodule Artifacts#

With the submodule merged, remove its leftover configuration:

Remove the Submodule Entry from .gitmodules#

git rm --cached vendor/libfoo  # Removes the submodule from .gitmodules and staging

Delete the Submodule Directory#

rm -rf vendor/libfoo  # Delete the submodule’s working directory  
rm -rf .git/modules/vendor/libfoo  # Remove Git’s internal submodule cache

Remove the Submodule from .git/config#

git config --remove-section submodule.vendor/libfoo  # Removes submodule config

Commit Cleanup Changes#

git commit -m "Remove submodule 'vendor/libfoo' after merging"

7. Verification: Ensure History and Files Are Preserved#

Check Merged Files#

Confirm the submodule’s files are present in the parent repo:

ls -la vendor/libfoo  # Should match the submodule’s original files

Verify Commit History#

Use git log to check that the submodule’s commits are now part of the parent’s history:

git log -- vendor/libfoo  # Shows commits from the submodule

Test the Parent Repository#

Run tests or build the project to ensure merging didn’t break functionality:

# Example: Run tests (adjust for your project)  
make test

8. Troubleshooting Common Issues#

Merge Conflicts#

If Git detects conflicts (e.g., overlapping files in vendor/libfoo), resolve them manually:

git status  # Identify conflicted files  
# Edit files to resolve conflicts  
git add <conflicted-files>  
git commit -m "Resolve merge conflicts from submodule merge"

Submodule Files Not Appearing#

If files are missing, ensure the prefix in the merge command matches the submodule’s original path (e.g., vendor/libfoo). Re-run the merge with the correct prefix.

Nested Submodules#

This guide assumes a single-level submodule. For nested submodules (submodules within the submodule), repeat the process for each nested submodule first.

9. References#

By following these steps, you’ll merge a Git submodule into the parent repository cleanly, preserving its commit history using Git’s officially supported subtree merge strategy. This approach simplifies your project structure while maintaining full traceability of the submodule’s development.

2025-12