2015-01-22-git-subtree.md

layout	title	date	categories	tags
post	Git Subtree Ready Reference	2015-01-22 04:00:00 -0800	development	git development git subtree

Git Subtrees allow easily tracking and contributing to remote repositories. The advantage over submodules is that the tracked subdirectory is contained within the current repository repository history so no initialization and update cycle is required when cloning the project. Additionally, the history of the subtree may be fully tracked or squashed.

these notes use the following articles as reference:

• Alternatives To Git Submodule: Git Subtree
• Managing Nested Libraries Using the GIT Subtree Merge Workflow
• 6.7 Git Tools - Subtree Merging
• Moving A Subdirectory Into A Separate Git Repository

track a remote repository, squash commits

1. add subtree as a remote

   git remote add -f $REMOTE_NAME $REMOTE_URI

2. setup remote as a subtree with a relative local path. this will fetch and merge.

   git subtree add --prefix $LOCAL_PATH $REMOTE_NAME $REMOTE_BRANCH --squash

3. fetch and merge (pull) when the subtree remote has updates

   git subtree pull --prefix $LOCAL_PATH $REMOTE_NAME $REMOTE_BRANCH
   

track a subdirectory of a remote repository, keep full history

1. clone remote repository as a new project

   git clone $REMOTE_URI

2. discard everything but the subdirectory wanted, this will make the wanted directory the project root with full working history.

   git checkout -b $WORK_BRANCH
   git filter-branch --subdirectory-filter $WANTED_DIRECTORY HEAD -- --all
   git reset --hard
   git gc --aggressive
   git prune
   

3. setup new remote to contain project, and push to master branch at that location

   git push --set-upstream $NEW_REMOTE_NAME $WORK_BRANCH:master
   

4. use that new repository as a subtree in either project to commit changes to both repositories. if you'd like the full history in your project, leave off the --squash during submodule commands.