Tutorial

#Tutorial for getting started with modman

Introduction

Modman allows you to structure your code repository in a very simple way and have the contents mapped to a different location at deployment via symlinks. This has the following benefits:

• Your project's code can appear to the application to be interspersed with other code that is not checked into your repository.
• You don't need to use svn:externals or git submodules at all (although you can). This avoids having to make multiple commits due to a split repository.
• Browsing your code in an IDE is very fast since you and the IDE will see only your project's code, not the other application code.
• You can shorten the paths considerably for easier navigation and less typing. For example app/code/local/My/Module/ can be shortened to just code/.

How to Use

Most likely you can start using modman with an existing project by simply adding one file, the modman file. This is a simple text file which tells the script how to map your repository files into the application root. It should be placed in the root of the repository or code project. The syntax rules are simple:

• Blank lines are ignored
• Lines beginning with # are ignored
• All other lines should contain one of the following directives:
  • <link target> <link location>
    • 2 white-space separated paths, can use any number of spaces and tabs
    • Like cp, glob patterns are supported for the link target
  • @import <source> [<basedir>]
    • <source> must contain a file named "modman"
    • <basedir> lets you deploy the imported module in a sub-directory of the project root
  • @shell <shell commands>
    • Line continuations are supported (end line with \ to continue script on next line)
    • Two environment variables are set: $PROJECT and $MODULE
    • The script can receive input from stdin

The most used directive is the path mapping. The first path is relative to the working copy and the second is the path it should map to when deployed relative to the project root. If --basedir <path> is used for modman init the project root will be the base directory. Additionally, if a module is imported with a <basedir> option then the deploy root will be that basedir. In general, it is best to organize your module deploy paths relative to the project root and then let the user decide if they want to use a base directory.

Example

Our example module is very simple, it just has a Block, a layout update, a template file and the typical Magento module files. Here is how I chose to structure the project in my repository (I like shallow paths):

+--code/
|  +--etc/
|  |  +--config.xml
|  +--Block/
|     |--View.php
+--frontend/
|  +--layout/
|  |  +--my.xml
|  +--template/
|     +--view.phtml
+--My_Module.xml
+--modman

In order to properly deploy my module to a Magento installation my modman file would look like this:

# My_Module, just an example
code                   app/code/local/My/Module/
frontend/layout/*      app/design/frontend/base/default/layout/
frontend/template/*    app/design/frontend/base/default/template/mymodule
My_Module.xml          app/etc/modules/My_Module.xml

Assuming the above resides at git@example.com:foo/mymodule.git, I can now deploy my module like so:

$ cd /var/www            # Magento is installed here
$ modman init            # This is only done once in the application root
$ modman clone git@example.com:foo/mymodule.git

That is all! The project will be cloned in .modman/mymodule/ and symlinks will be created throughout the application root as described in the modman file. Parent directories of the final locations are created in the application root as needed so if two modules place files in the same location there will be no conflicts.

For more productivity hints with modman see the Productivity Hints page.

Updating

Henceforth, to update your module you should avoid using the vcs commands directly since doing so would bypass the link-creation step so if changes were made to the modman file they would not get applied locally. Instead, to update a single module named mymodule module to the latest version:

$ modman update mymodule

See Handling Multiple Modules for tips on using multiple modules in modman.