Using Git submodules and @import with Modman for Magento

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 code, themes and locale. You want to install SMTP Pro into code/aschroder.

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 git status.

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?