{"meta":{"title":"About Git subtree merges","intro":"If you need to manage multiple projects within a single repository, you can use a subtree merge to handle all the references.","product":"Get started","breadcrumbs":[{"href":"/en/get-started","title":"Get started"},{"href":"/en/get-started/using-git","title":"Using Git"},{"href":"/en/get-started/using-git/about-git-subtree-merges","title":"About Git subtree merges"}],"documentType":"article"},"body":"# About Git subtree merges\n\nIf you need to manage multiple projects within a single repository, you can use a subtree merge to handle all the references.\n\n## About subtree merges\n\nTypically, a subtree merge is used to contain a repository within a repository. The \"subrepository\" is stored in a folder of the main repository.\n\nThe best way to explain subtree merges is to show by example. We will:\n\n* Make an empty repository called `test` that represents our project.\n* Merge another repository into it as a subtree called `Spoon-Knife`.\n* The `test` project will use that subproject as if it were part of the same repository.\n* Fetch updates from `Spoon-Knife` into our `test` project.\n\n## Setting up the empty repository for a subtree merge\n\n1. Open <span class=\"platform-mac\">Terminal</span><span class=\"platform-linux\">Terminal</span><span class=\"platform-windows\">Git Bash</span>.\n\n2. Create a new directory and navigate to it.\n\n   ```shell\n   mkdir test\n   cd test\n   ```\n\n3. Initialize a new Git repository.\n\n   ```shell\n   $ git init\n   > Initialized empty Git repository in /Users/octocat/tmp/test/.git/\n   ```\n\n4. Create and commit a new file.\n\n   ```shell\n   $ touch .gitignore\n   $ git add .gitignore\n   $ git commit -m \"initial commit\"\n   > [main (root-commit) 3146c2a] initial commit\n   >  0 files changed, 0 insertions(+), 0 deletions(-)\n   >  create mode 100644 .gitignore\n   ```\n\n## Adding a new repository as a subtree\n\n1. Add a new remote URL pointing to the separate project that we're interested in.\n\n   ```shell\n   $ git remote add -f spoon-knife https://github.com/octocat/Spoon-Knife.git\n   > Updating spoon-knife\n   > warning: no common commits\n   > remote: Counting objects: 1732, done.\n   > remote: Compressing objects: 100% (750/750), done.\n   > remote: Total 1732 (delta 1086), reused 1558 (delta 967)\n   > Receiving objects: 100% (1732/1732), 528.19 KiB | 621 KiB/s, done.\n   > Resolving deltas: 100% (1086/1086), done.\n   > From https://github.com/octocat/Spoon-Knife\n   >  * [new branch]      main     -> Spoon-Knife/main\n   ```\n\n2. Merge the `Spoon-Knife` project into the local Git project. This doesn't change any of your files locally, but it does prepare Git for the next step.\n\n   If you're using Git 2.9 or above:\n\n   ```shell\n   $ git merge -s ours --no-commit --allow-unrelated-histories spoon-knife/main\n   > Automatic merge went well; stopped before committing as requested\n   ```\n\n   If you're using Git 2.8 or below:\n\n   ```shell\n   $ git merge -s ours --no-commit spoon-knife/main\n   > Automatic merge went well; stopped before committing as requested\n   ```\n\n3. Create a new directory called **spoon-knife**, and copy the Git history of the `Spoon-Knife` project into it.\n\n   ```shell\n   $ git read-tree --prefix=spoon-knife/ -u spoon-knife/main\n   > fatal: refusing to merge unrelated histories\n   ```\n\n4. Commit the changes to keep them safe.\n\n   ```shell\n   $ git commit -m \"Subtree merged in spoon-knife\"\n   > [main fe0ca25] Subtree merged in spoon-knife\n   ```\n\nAlthough we've only added one subproject, any number of subprojects can be incorporated into a Git repository.\n\n> \\[!TIP]\n> If you create a fresh clone of the repository in the future, the remotes you've added will not be created for you. You will have to add them again using [the `git remote add` command](/en/get-started/git-basics/managing-remote-repositories).\n\n## Synchronizing with updates and changes\n\nWhen a subproject is added, it is not automatically kept in sync with the upstream changes. You will need to update the subproject with the following command:\n\n```shell\ngit pull -s subtree REMOTE-NAME BRANCH-NAME\n```\n\nFor the example above, this would be:\n\n```shell\ngit pull -s subtree spoon-knife main\n```\n\n## Further reading\n\n* [The \"Advanced Merging\" chapter from the *Pro Git* book](https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging)\n* [How to use the subtree merge strategy](https://www.kernel.org/pub/software/scm/git/docs/howto/using-merge-subtree.html)"}