How to Merge Repositories in GitHub?

Merging repositories in GitHub is a common need when you want to combine two or more related projects, consolidate codebases, or integrate changes from one repository into another. While GitHub doesn’t have a direct “merge repositories” feature, you can achieve this by leveraging Git’s capabilities.

This blog walks you through the steps to merge repositories in GitHub, ensuring your work is organized and efficient.

Why Merge Repositories?

Here are some common scenarios where merging repositories can be beneficial:

1. Project Consolidation: Combine related projects into a single repository.
2. Team Collaboration: Merge different teams’ codebases into a central repository.
3. Archival: Integrate smaller repositories into a larger repository for better organization.

---

Steps to Merge Repositories in GitHub

Step 1: Clone the Primary Repository

The primary repository is the one you want to retain as the main repository after the merge.

git clone https://github.com/<username>/<primary-repository>.git
cd <primary-repository>

---

Step 2: Add the Secondary Repository as a Remote

Add the repository you want to merge into the primary repository as a remote:

git remote add secondary https://github.com/<username>/<secondary-repository>.git

Fetch the data from the secondary repository:

git fetch secondary

---

Step 3: Create a New Branch for the Merge

It’s a good practice to create a separate branch for merging:

git checkout -b merge-secondary

---

Step 4: Merge the Secondary Repository

Use the --allow-unrelated-histories flag to merge repositories that don’t share a common history:

git merge secondary/main --allow-unrelated-histories

Note: Replace main with the default branch name of the secondary repository if it’s different (e.g., master or develop).

---

Step 5: Resolve Merge Conflicts (if any)

If there are conflicting files, Git will pause the merge and notify you. Resolve conflicts by editing the conflicting files and marking them as resolved:

git add <file>

Continue the merge after resolving conflicts:

git commit

---

Step 6: Push the Changes to GitHub

After completing the merge, push the changes back to the primary repository on GitHub:

git push origin merge-secondary

If you’re confident with the changes, merge the merge-secondary branch into the primary branch (e.g., main) on GitHub using a pull request or locally:

git checkout main
git merge merge-secondary
git push origin main

---

Optional: Remove the Secondary Repository Remote

Once the merge is complete, you can remove the reference to the secondary repository:

git remote remove secondary

---

Best Practices for Merging Repositories

1. Backup Your Repositories: Always create backups of your repositories before starting a merge process.
2. Use Clear Commit Messages: Document the merge process with detailed commit messages for future reference.
3. Test Thoroughly: After merging, test the combined repository to ensure all features work as expected.
4. Archive or Delete the Secondary Repository: Once the merge is complete, decide whether to archive or delete the secondary repository to avoid confusion.

---

Common Issues and Troubleshooting

1. Merge Conflicts

Merge conflicts occur when the same file is modified in both repositories. Use a Git conflict resolution tool or manually edit conflicting files.

2. Large Repositories

If the repositories are large, the merge process may be slow. Consider using Git LFS (Large File Storage) for managing large files.

3. Unrelated Histories

When merging unrelated repositories, always use the --allow-unrelated-histories flag to avoid errors.

---

Conclusion

Merging repositories in GitHub is a powerful way to consolidate and organize projects. While it requires careful execution, the steps outlined in this guide ensure a smooth merging process.

By following best practices, resolving conflicts, and thoroughly testing the result, you can create a unified and efficient repository.