Ross Wolin - last updated 2015.11.18
I am writing firmware for an embedded system which uses the uGFX graphics library. I use Git for source control, and wanted to use a Git submodule to embed uGFX's Bitbucket hosted repository into my source repository. Additionally, I wanted to be able to add some custom board and driver files to uGFX which are needed for my project, but are of no value to uGFX (and won't be pushed back to their repository.)
Initially, I merely added a Git submodule to my local repository, made some changes and commited them to the submodule's master branch. This worked smashingly... until I tried to make a local clone of my repository, using the recursive switch:
git clone --recursive myrepo myrepo_clone
and got an error:
fatal: reference is not a tree: ca025c09ca2b7b82ca086309eeb0696d674cb1d0 Unable to checkout 'ca025c09ca2b7b82ca086309eeb0696d674cb1d0' in submodule path 'ugfx_submodule'
the problem is that my changes to the submodule's master branch are in my local repository, but when Git tries to clone the uGFX submodule, it gets source from the Bitbucket repository, which obviously does not have my changes.
What I'm doing seems to me like a pretty common situation/workflow...
surprisingsly, when I searched, I did not find documentation/examples about how to set this up properly so that recursive clones would work, etc.
Here's my requirements in more detail:
I came up with a workable solution, involving a version of Triangular Workflow, using an upstream repository. I used a Raspberry Pi + Raspbian for the upstream repository because I had one on my network running DNS/DHCP and thought it would be cool, you could just as easily use a second local repository on your disk, Bitbucket/Github, etc, etc
Here are the specifics for my solution:
git remote add origin git@pi-b:/mnt/git_repos/myproduct.git git push
git submodule add https://bitbucket.org/Tectu/ugfx.git ugfx_submodule
git branch -m master updates
git remote rename origin bitbucket
git remote add origin git@pi-b:/mnt/git_repos/myproduct_ugfx.git git checkout -b master git push -u origin master
git config remote.origin.url git@pi-b:/mnt/git_repos/myproduct_ugfx.git
At this point, I wanted to add a few files to the uGFX tree. I add them to the master branch, commit, and push (which goes to the Pi repository.) Remember to also go up a direcotry, outside of the submodule, run git submodule sync (not sure if that's necessary), and then commit+push those changes to the main/outer repo.
Now, when there are changes on the Bitbucket repository, in the submodule I can pull them into my local updates branch, then when I've tested them and want to integrate them into the my product, I can merge updates with master, then commit and push master to the Pi repository.
Local recursive clones (like the one above that caused the initial error) will now work. If someone wants to clone the myproduct repository from the Pi, provided they have access to the Pi (see Git book for adding an ssh key) they can do it with
git clone --recursive git@pi-b:/mnt/git_repos/myproduct.git
Send comments, questions, money in large denominations, etc to eng at mysticengineering.com
If you enjoyed this article, please consider buying my products ...
ATX PS Adapter
Use an ATX PC power supply as a 5V, 3.3V, and +12V/-12V bench supply the easy way, without cutting the case or mounting external connectors, resistors, LEDs, switches, and fuses.
Provides visual indication when supply is plugged in and turned on, also fuses the power voltage outputs for safety. Run USB powered development boards via the USB connectors on the 5V line.
Ultimate Serial Port (Debug Buddy)
USB serial port with standard, 5V and 3V RS232, plus integrated null modem and gender changer. Implements TX/RX and RTS#/CTS# for optional hardware handshake.
Also includes 3.3V<->5V level shifters, debug LEDs, and 13 clock sources. Valuable tool for hands on problem solving and hacking