After chatting to Colin about his excellent modman project at Magento Imagine earlier this year I’d been meaning to swap our internal stores onto a git submodules + modman @import setup – finally got around to it only two months late!
In this post I’ll walk through importing the git submodule, and then using it in the context of a larger modman project, and lastly I’ll brain dump some useful/relevant git submodule commands while they’re fresh in my head. For a worked introduction to modman, see my earlier article and if you’re not using modman, this article summarizes some modman benefits, with pictures.
Throughout this example I’ll use my SMTP Pro Magento extension on Github as an example.
1) Add the submodule to your existing git repository
As with most things in git, understanding submodules will mess with your head. If you’re into that, you can start with an overview guide and follow it up with a quick run through the man page – you have been warned.
I’ll just skip to the good bit. Assume you have an existing modman project, with say root directories of
locale. You want to install SMTP Pro into
mkdir code/aschroder git submodule add https://github.com/aschroder/Magento-SMTP-Pro-Email-Extension.git code/aschroder/SMTPPro # check it worked, this command should show the contents of the repo ls -la code/aschroder/SMTPPro
So now you have the code in your repository, time to add it to your modman project.
2) Import the submodule in your existing modman file
The syntax is very simple as Colin has shown on the modman wiki.
#SMTP Pro @import code/aschroder/SMTPPro
Now you can test it locally by running a modman deploy like this to create the symlinks in the magento installation:
modman deploy yourmodule Applied: * app/code/community/Aschroder/SMTPPro/Block Applied: * app/code/community/Aschroder/SMTPPro/Helper ...
3) Update and deploy the project
Once you know it works in your local test environment, I actually suggest a fresh checkout in production – my attempts to update the existing clone ended in tears, YMMV.
From the root of your store, I’d suggest this sort of flow.
cd .modman # Get the new repo sudo git clone http://github.com/your/Your-Store.git yourmodule.new cd yourmodule.new git submodule init # Swap in the new one, keep the old one *just in case* mv yourmodule yourmodule.before.you.messed.with.anything mv yourmodule.new yourmodule cd .. # back to the root of your store to update modman yourmodule update
Now, isn’t that easier, cleaner and more developer friendly than Magento Connect? If you host your Magento extension on GitHub, do you have a modman file for it? Other developers will love you for it.
Appendix: Relevant Git submodule commands
Some of the commands I needed to use, and am likely to forget, here more for my own sake than yours.
Add a submodule
git submodule add https://github.com/you/your-repo.git place/where/you/put/submodule
Update a single submodule (from in the directory)
git pull origin master
Update all submodules from the parent repo
git submodule foreach git pull origin master
Fetch the code in the submodules referenced by the current submodule commit
git submodule update
Update the actual submodule commit and then push it to the origin repo – this causes the parent repo to pick up the new version of the module
git commit -am "Pulled down update version of submodule(s)" git push origin master
Note: If you don’t do this then the parent repository will record a change in the submodule directory when you run a
Change the submodule URL
Edit the file
.gitmodules in the root of the parent repository, it has formatting like this, and you can edit the URL if it changes.
[submodule "code/aschroder/SMTPPro"] path = code/aschroder/SMTPPro url = https://github.com/aschroder/Magento-SMTP-Pro-Email-Extension.git
Resync git after changing the URL
After changing the URL, you need to let git know with this command:
git submodule sync
Did I miss any, please let me know?