Use Case: You are developing local extensions for a Magento project and you wish to keep them in their own repository for use in later projects without disrupting your regular workflow.

Unlike WordPress where all the code for a plugin lives in a dedicated folder within a Plugins directory and which provides a practical place to host a Git Submodule, Magento likes to keep all it’s files spread out all over the place. the only common ancestor being the root directory. This means Submodules are only really a sensible option for things like a single file JavaScript library.

We need another way to manage our custom modules within our git workflow.

In this example we are going to create a simple Magento module which will override your store Cart page (We call them Shopping Baskets in Scotland, so since it’s Easter, that’s what we will call them here) and replace it with a custom layout.

We are then going to check the module into it’s own dedicated repository, and finally add it to our main Magento store repository

If you already have a git instance in the root of your Magento folder you will need to rename it

mv .git .site_repo.git
mv .gitignore .site_repo.gitignore

Now you can create a remote repository on whichever host you use and use it for your module.

git init
git remote add origin

Since this is mainly an article about Git I have created a Bash script named to do the heavy lifting in Magento for you.

I suggest you read the follow to understand what the script is doing and then run it from your command prompt as instructed.

You will be asked for a Namespace (your company name), a Module Name (the name of your plugin), the Codepool(choose from: local or community), the Package (current theme package) and Theme Name (sub theme, usually default)

You will also be asked to choose a permissions level to set on your newly created files. I usually use 755 for module permissions in both production and development.

To get Magento to see our extension we need several files which have been created by your script.

The first of these is


which will tell Magento which Codepool to use and whether your module is currently active.

We will also need


with which we can add a customlayout.xml file to the current theme.

Our layout file


will use the


handle to conditionally include a CSS file on the checkout page, and instruct Magnetos rendering engine to look for cart.phtml in our modules file path when loading the cart page.

Our pages simplified content can be found in


and the CSS for this page



That’s basically all the files we need. The last thing the script will do is create a .gitignore file in the
current directory which is set up to include everything in


as well as the remaining xml files.

Note: For windows users there is sometimes a problem that files are created with unsuitable permissions. I know I have lost hours close reading xml documents before realizing the file simply could not be read by the server. For this reason the script also creates a

file which you can run at any time to flush the permissions in your plugins folders.

Moving quickly back on topic, we need to run the following to create our example module.


Wicked, you now have a new Magento module. Visit your stores cart page (you will need something in your basket) to confirm everything has worked.

We can now safely run

git add -A
git status
#just be sure
git commit -m "initial commit"

and now we have our new module stored in it’s very own repository. To switch back to the main website Git
instance that we hid earlier, we need to “hackstash” our module repository

mv .git .namespace_module.git
mv .namespace_module.gitignore

To instantiate our original site repo.

mv .site_repo.git .git
mv .site_repo.gitignore .gitignore

And finally switch to a new branch, add our hackstashed modules to the main .gitignore, add our new files to the main repository in their own branch and merge this branch back into the original repository

git checkout -b namespace_module
cat > .gitignore << EOF !.namespace_module.git !.namespace_module.gitignore EOF

git add .
git commit -m "added new module"
git checkout master

git merge namespace_module

you now have a new module included in your main Magento repository. You can continue working
on it alongside the rest of your site files. Anytime you wish to to either update the
plugins remote, or pull changes from the remote into your main repo simply run

mv .git .site_repo.git
mv .gitignore .site_repo.gitignore
mv .module_namespace.git .git
mv .module_namespace.gitignore .gitignore

and proceed with your normal git workflow.

Leave a Comment