Git Subtree Notes

These are some notes I kept based on the creation and subsequent update of our first Git Subtree.

As part of updating to use the latest version of jsdoc3, I created a fork of the project that could be used to both create pull-requests that can be merged into the upstream project and act as place to create BladeRunnerJS specific integration changes. One of the requirements we had to satisfy before we could start making use of Git Subtrees was the ability to specify the specific version of jsdoc3 we wanted to use.

We could have done this by creating a subtree that pointed to a specific version of the original project, but since we have integration changes we need to make anyway, I instead created a brjs branch in our fork of the project, which can be manually merged into when we want to upgrade to a later version, and which includes the integration changes we need for BladeRunnerJS to make use of jsdoc3.

Anyway, here are some details on the commands I used to both create the subtree, and later update it to use the latest changes within the brjs branch.

To make the subsequent commands shorter type:

git remote add jsdoc-brjs git@github.com:BladeRunnerJS/jsdoc.git

More generically this is git remote add <remote-name> <remote-url>

To create the initial subtree:

git subtree add --prefix=brjs-sdk/build-resources/includes/sdk/jsdoc-toolkit-resources/jsdoc-toolkit --squash jsdoc-brjs brjs

More generically: git subtree add --prefix=<path-to-subtree-root> --squash <remote-name> <remote-branch>

To push all outstanding sub-tree commits upstream:

git subtree push --prefix=brjs-sdk/build-resources/includes/sdk/jsdoc-toolkit-resources/jsdoc-toolkit jsdoc-brjs brjs

Note:

You should only push directly to the 'brjs' branch if these changes aren't going to be shared even further upstream. Otherwise, you should push changes to a feature branch that we can use to do a pull-request on the 'jsdoc3' project, which can then subsequently be merged into the 'brjs' branch.

To pull all outstanding sub-tree commits downstream:

git fetch jsdoc-brjs brjs
git subtree pull --prefix=brjs-sdk/build-resources/includes/sdk/jsdoc-toolkit-resources/jsdoc-toolkit --squash jsdoc-brjs brjs

Note:

As we have a fork of 'jsdoc3' we can control when new upstream changes arrive, since they must manually be merged from the original 'jsdoc3' project. This allows developers to avoid there ever being upstream changes available at the same time there are still outstanding downstream changes destined to be pushed upstream. By doing this, we avoid the need to perform sub-tree merges.