Home > Magento, Programming > Module Manager – for when svn:externals just doesn’t cut it.

Module Manager – for when svn:externals just doesn’t cut it.

October 17th, 2009

Update 1/30/2010:
Added nested modules, renamed .modman file to modman, released under Apache License 2.0, and hosted on Google Code.

This project was inspired by my recent Magento development work so I’m not sure how much application it has outside of that, but if you’ve ever wanted to use svn:externals with individual files (you can’t btw) then this is the next best thing (and therefore the best thing). Perhaps some other VCS supports this functionality natively , if you know of it please clue me in. I’ve used git and bazaar but still like the simplicity of subversion for small, non-distributed projects.

Magento’s source code is split among several different groups of files: code, design, locale, skin, libs, etc (as in config), etc.. (as in etcetera)
You really cannot avoid ever having to mix a file in here or there which means svn:externals won’t cut it. Besides, svn:externals won’t let you make one commit from all of your externals so to commit your changes you have to do it once for each folder which makes your commit history nearly useless. Enter “modman”, my Magento module manager. While it could be used for deployment it is primarily geared towards developers. Here is how it works:

Create a branch and put your source code in it. Now create a “.modman” file within the root of the branch. In this file you define (much like svn:externals) a path within your repository and the path that it should map to. Here is an example (with a fictitious module named “HotDealz”:

code   app/code/local/Colin/HotDealz 
template   app/design/frontend/default/default/template/hotdealz
hotdealz.xml   app/design/frontend/default/default/layout/hotdealz.xml
images   skin/frontend/default/default/images/hotdealz
HotDealz.csv   app/locale/en_US/Colin_HotDealz.csz

As you can see, very similar to svn:externals only with individual file support which is handy for things like locale files that can’t go in subdirectories.

How It Works

Usage is similar to regular command line usage of subversion. The “modman” script provides a wrapper around svn which checks the code out in a .modman directory at the root of your project then reads the .modman file and creates symbolic links as necessary so that your source code is actually all contained within one directory and your webserver accesses the files where they are supposed to be. No svn:externals definitions are used. Obviously this requires a few things:

  1. bash
  2. a webserver that is configured to FollowSymLinks

If you do web development on Windows, you may be thinking, “What about Windows support!?”. Well, you have a few options:

  • Do your development inside a VirtualBox instance of Linux and share the drive to Windows for editing on your IDE (recommended).
  • Try to configure cygwin to work (untested, not recommended).

I chose the former long before I wrote this script since the servers for my projects are all Linux-based and doing development on WAMP when your project runs on L*MP is silly. You can actually still use TortoiseSVN by simply opening the .modman directory from explorer so really after the initial checkout you do not need to continue to use the script except for when adding new definitions to the .modman file.

Sample Usage

Here are some typical commands used with modman:

$ modman --help
$ modman init
$ modman hotdealz checkout "svn url here"
$ modman hotdealz status (can be run from any directory within the project root)
$ modman hotdealz commit
$ modman hotdealz update
$ modman hotdealz add Colin_HotDealz.xml app/etc/modules/HotDealz.xml

Most commonly used svn commands are passed through to svn for convenience but for advanced work you can just cd to the .modman directory or use TortoiseSVN or your IDE’s integrated subversion tools (I use Netbeans).


Magento Module Manager
Usage: modman <module> <action> [svn args]
Supported global actions (no module specified):
  init           initialize the current directory as the modman root (no module name)
  update-all     update all modules that are currently checked out

Supported actions: (all svn commands support additional arguments)
  checkout       checkout a new modman compatible module
  export         export a modman compatible module (does real copy instead of symlinks)
  update [...]   update module
  add <svn_path> <real_path>   add a file/dir to the .modman file and working copy
  delete <svn_path>   remove a file/dir from the .modman file and working copy
  status         show status of entire module
  diff [...]     run svn diff on module
  commit [...]   commit changes to module
  info           show the module's working copy path and run svn info on working copy
  list           list the definitions in the .modman file

The repository should contain a file called ".modman" which defines which files
go where relative to the directory where modman was initialized.

If additional arguments are given to commands such as commit, paths
should be relative to the svn root.

---- Start example .modman file ----
# Comments are supported, begin a line with a hash
code                   app/code/local/My/Module/
design                 app/design/frontend/default/default/mymodule/
locale/My_Module.xml   app/locale/en_US/My_Module.xml
My_Module.xml          app/etc/modules/My_Module.xml
---- End example .modman file ----

Colin Mollenhour
[email protected]

View Source


Leave a comment if you use it!

Magento, Programming , ,

  • melicerte

    Subversion 1.6 support svn:externals on a single file.

  • http://colin.mollenhour.com colin

    That is great, but the purpose of externals in this case is to separate your code from core code. With svn:externals you would have to mirror the Magento directory structure in your repository which would mean using more than one repository in your installation would most likely not work (can’t have two subdirectories checked out in one subdirectory), and you would either have to use svn:ignore *extremely heavily* or your svn status output would be ridiculous (not to mention, slow). The use of softlinks allows you to version only the code that is yours, organize it cleanly, edit it without wading through thousands of core files, and keep svn commands quick. Since intermediate directories are created automatically but not versioned (unlike with svn:externals with files) there is no problem when using multiple modules from different repositories.

  • http://colin.mollenhour.com/2010/01/31/module-manager-update/ Colin Mollenhour’s Technical Blog » Module Manager Update, now on Google Code!

    […] recently updated Module Manager (first post) to support nested modules and renamed the .modman definitions file to simply modman for easier […]

  • http://www.molotovbliss.com/magento-research-and-tools-links Magento Supercharged Development Tools and Links | molotov.bliss

    […] Module Manager for when svn:externals just doesn’t cut it: How Module Manager can be used instead of svn:externals. http://colin.mollenhour.com/2009/10/17/module-manager-for-when-svnexternals-just-doesnt-cut-it/ […]