Share the contents of a repository with one or more other repositories as an external subtree or sub-repository in the other host repositories.

  • Update external_repo with changes in host_repo subtree
  • Update host_repo subtree with changes in external_repo
  • Switch between branches of subtree

Add External as a Remote

Add the external_repo URL to local Git as a remote repository that commands can refer to using the --prefix flag.
git remote add -f <name> <url>

  • <name> -> use the same name of the external_repo, NOT as an explicit path
  • <url> -> the external_repo's HTTPS or SSH address

Example
git remote add -f appservice ssh.dev.azure.com:v3/company/group/appservice

Add Subtree to Parent

Merge the external_repo as a subtree into the host_repo with a merge commit that does not include the external_repo's commit history.
git subtree add --prefix=<prefix> <repository> <ref> --squash

  • <prefix> - the local directory name, which is the name used for the external_repo's url added with "remote" command
  • <repository> - the same name as the prefix (yep, same as prefix)
  • <ref> - the external_repo's branch name

Example
git subtree add --prefix appservice appservice main --squash

Push this host_repo commit to origin as usual

Push host subtree changes to external repo

Change to root of host_repo
cd ../host_repo

Add, commit as usual
git commit -a -m 'changing subtree from parent'

Push host_repo subtree changes to origin as usual (including subtree)
git push origin feature/make_this_feature

Push host_repo subtree changes to remote/external
git subtree push --prefix <prefix> <repository> <external_branch>

  • <prefix> -> is name used for the external repo's url added with "remote" command
  • <repository> -> is the local git repo name of the external repo (NOT beginning with a ./)
  • <ref> -> is the external repo branch name

Example
git subtree push --prefix appservice appservice main

Change to root of external_repo
cd ../external_repo

Pull subtree changes
git pull origin master (or just git pull)

Pull external changes to host repo subtree

Change to root of external_repo
cd ../external_repo

Add, commit as usual
git commit -a -m 'changing subtree from external'

Push external_repo changes to origin main branch as usual
git push origin main

Change to the host_repo/subtree directory (even though you're specifying the prefix)
cd ../host_repo/subtree

Merge changes made to external_repo into the host_repo with a merge commit that does not include the external_repo's commit history
git subtree pull --prefix=<host_repo_name> external_repo_name --squash

Example
git subtree pull --prefix=appservice appservice --squash

Add a merge commit comment like 'pulling in updates to subtree from external_repo'.

Switch between branches of subtree

git rm -r appservice; git commit -m 'switching subtree branches';
git subtree add --prefix appservice appservice feature/update_feature --squash

Manage remote

git remote remove appservice

Sanity notes

  • External is usually used as a reference library.
  • Have both host and external as local repos.
  • Do push/pull only on established main/develop type branches.
  • Pull external repo changes from subtree directory of parent repo!!

References

Git subtree tutorial and demo - video
Mastering git subtrees
Learn git subtree
When to use git subtree
How to use git subtree to manage multiple project repositories