Back to git
Using subtrees
One of the key benefits of subtrees is to be able to mix project-specific customizations with general-purpose fixes and enhancements. - Medium
General steps for getting started with subtrees:
- Go into the parent (project) directory. It must be clean or the subtree command will throw an error.
- The desired subtree or child repo should also exist on the remote (server repo), upload it if not.
- Create a reference name for the remote of the subtree, in other words tell git you have another remote to talk to. This edits the .git/config file. Run the command git remote add <subtreename> <subtree.gitrepo.remoteURL>
- Tell Git to add the child repo to your parent project as a subtree with git subtree add --prefix=<localpath> <subtreename> <subtreebranch> --squash
- Find the subtree files inside parent/<localpath>.
Notes:
- <localpath> is the location in the parent repo in which you want the subtree contents to reside, a chance to create layers of folders if you want; to keep it to one single level of depth with the same name, simply make this equal to the <subtreename> reference you picked
- <subtreebranch> is the branch within the subtree repo you want to get, like master or dev
- subtrees do not have their own .git folders, indeed locally they not separate repos but become part of the parent repo
How it works
If you make a change to files inside the parent/subtree and commit and push the parent remote will be updated but the subtree's remote repo will not. i.e. you'll see the file changed in the remote parent/subtree/filename location but not in the remote subtree/filename location.
To push the subtree changes ALSO so that everyone can see them at the subtree remote repo use git subtree push --prefix=<localpath> <subtreename> <subtreebranch>
You can get subtree updates with the same command except with pull.
Some issues to remember when working with subtrees
- It isn't readily apparent that part of the main repo is built from a subtree
- You can't easily list the subtrees in your project
- You can't, at least easily, list the remote repositories of the subtrees (is this remedied by using a .gittrees file?)
- The logs are slightly confusing when you update the host repository with subtree commits, then push the subtree to its host, and then pull the subtree.
A word about submodules
Git is not designed to handle submodules within subtrees.