Skip to content

Instantly share code, notes, and snippets.

@brianjking

brianjking/example-subtree-usage.md

Forked from kvnsmth/example-subtree-usage.md
Created August 9, 2016 19:03
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save brianjking/f265699acea2945e1374c44bcbb575bf to your computer and use it in GitHub Desktop.
Save brianjking/f265699acea2945e1374c44bcbb575bf to your computer and use it in GitHub Desktop.
Download ZIP
A real world usage for git subtrees.
Raw
example-subtree-usage.md

Let's say you have an iOS project, and you want to use some external library, like AFNetworking. How do you integrate it?

With submodules

Add the project to your repo:

git submodule add git@github.com:AFNetworking/AFNetworking.git Vendor/AFNetworking

or something to that effect.

Well, what happens if you find a bug in AFNetworking that you want to fix? With submodules, I'd usually

  1. Fork AFNetworking
  2. Go through the pain of changing my project's submodules to point to my new fork
  3. Make my change and commit it to my fork
  4. Submit a pull request to AFNetworking repo
  5. Wait to see if the pull request is accepted, but keep my fork up-to-date in the meantime
  6. If it is accepted, do the whole dance to switch my submodule back to the official AFNetworking repo
  7. Continue as usual

Okay, that sucks. If you've ever done it, you know how painful it is and how finicky submodules can be.

With subtrees

Add the project to your repo:

git subtree add --prefix=Vendor/AFNetworking --squash git@github.com:AFNetworking/AFNetworking.git master

This is pretty similar so far except the other members of your team won't have to remember to run git submodule update because subtrees actually store the source in your repo. Nice.

Now, let's say we have the same bug. What do I do differently now that I'm using subtrees?

I make my change and commit it to my project's repository. Technically, I could stop now if I wanted to since the bug fixed code is in my repository. But, I want to be a good open source citizen, so what do I do?

Be a good open source citizen

  1. I'll fork AFNetworking into my account on Github.
  2. Back in my local repo:
git subtree split --prefix=Vendor/AFNetworking/ --branch AFNetworking

to set up being able to push changes to my fork. 3. I'll push my change to my fork, but on a branch to make the pull request more awesome.

git push git@github.com:kvnsmth/AFNetworking.git AFNetworking:critical-bug-fix
  1. I would issue a pull request and hope it gets accepted, but a big difference is that the acceptance of my change doesn't keep me from being able to easily stay in sync with the official AFNetworking repo.

I can still do:

git subtree pull --prefix=Vendor/AFNetworking --squash git@github.com:AFNetworking/AFNetworking.git master

to stay up-to-date with the latest in the official repository.

Now, I think that is much better than using submodules and a lot less invasive to my repo.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment