Magento 2 Module in a Separate Repository

In this article I will share my personal experience on how to build a Magento 2 Module outside of Magento 2 app/code directory. Having Magento 2 module in a separate repository might be useful in case you are planning to share it later with the community or sell it from Magento Marketplace. Other than that, the benefit is vital when it comes to project history. There are only module-related commits in your module repository.

There are 3 ways to develop a module in a separate repository:

1. git submodules
2. modman (Module Manager)
3. copy and paste Module related files manually (Ctrl+C, Ctrl+V). This might be a joke, however someone is doing it this way as well.

git submodule Command

This option comes first when I think about developing some stuff using GIT. A submodule command allows you to keep another Git repository in a subdirectory of your repository.

Usage is pretty straightforward. In Magento 2 root directory you have to execute the following command:
> cd /var/www/magento2/
> git submodule add

As a result new magento-2-test-module directory is created inside /var/www/magento2/ project.
My article is about different approach which I really enjoy to use.

Modman (Module Manager)

My attention came to one of community scripts for Magento 1 called modman. This is a bash script used to clone a repository where you store Magento Module into .modman directory. Once repository is cloned into .modman directory the modman script creates symlinks inside app/code/ Magento directory. Actually, you can configure modman to symlink module’s repository to any directory. Later in this article I will show how to do it.

The modman has been created by Colin Mollenhour (Twitter: @colinmollenhour), one of well known Magento community members. The script helps me to develop my personal Magento 2 modules on day-to-day basis. Also, you can use modman to add a folder/project which is stored on your local computer to a Magento 2 project. I think this is a modman manager’s killer-feature. In addition to this, it allows to have more than 1 repository.

Ability to manage multiple Magento 2 Modules and check status of your changes for all connected repositories with simple modman status command enables developers to forget about routine repository management. The git submodule command does not allow to have such flexibility.

You can find script and detailed tutorial by navigating to the page.

Mechanics of Using Modman Manager

First Magento 2 Module Repository

Before we start let’s create new GIT repository. The magento-2-test-module repository will contain our Test Magento 2 module. In this article we are going to have Magento 2 basic module. The module can only register itself in Modules pool during Magento 2 application installation.

Prepare Magento 2 Module files

In order to prepare Magento 2 Module we have to clone newly created repository and add few files to describe Magento 2 Module. The following git command will download repository to your local environment:

git clone

Cloning into ‘magento-2-test-module’…
warning: You appear to have cloned an empty repository.

The warning message only highlights the fact that there are no files in the repository. We are going to create them to describe Magento 2 Module:

1. The registration.php file allows to notify autoloader about the location of the Module in Magento 2
2. The module.xml main configuration file. For this article module.xml has only module name equals “Pronko_Magento2TestModule” and setup_version equals “100.0.0”
3. The composer.json where project “type” should be set to “magento2-module”.
4. modman configuration file

# modman configuration file
src app/code/Pronko/Magento2TestModule

The picture shows Magento 2 Test Module Structure with our files:

The Magento 2 Test Module is also available on github:

I recommend to also check PHP Developers Guide to get more insights on how to develop and extend Magento functionality.

Few git commands to update remote repository:

$ git commit -m "Basic Magento 2 test module"
$ git push origin master

Modman Installation

The modman installation is pretty straight forward. There are 2 things to remember:

1. modman should be initialised in the Magento 2 project directory
2. modman configuration file should exist in Magento 2 Module. In our case this is inside

The following command downloads modman script:

bash < <(wget -q –no-check-certificate -O –

Let’s initialize modman in Magento 2 directory:

$ modman init
Initialized Module Manager at /Users/pronko/Sites/magento2-clean

Next we clone our Magento 2 Test Module repository by modman command:

$ modman clone

Cloning into ‘magento-2-test-module’…
remote: Counting objects: 12, done.
remote: Compressing objects: 100% (8/8), done.
remote: Total 12 (delta 0), reused 12 (delta 0), pack-reused 0
Receiving objects: 100% (12/12), done.
Checking connectivity… done.
Applied: src app/code/Pronko/Magento2TestModule
Successfully create symlink new module ‘magento-2-test-module’

All files from the magento-2-test-module repository are now have symlinks under app/code/Pronko/Magento2TestModule directory as follow:

The modman status command is an analogue to git status and shows current status of changed files in the `/.modman/magento-2-test-module directory. Execution of modman status command in the Magento 2 root directory should show the following result:

$ modman status
— magento-2-test-module —
On branch master
Your branch is up-to-date with ‘origin/master’.
nothing to commit, working directory clean

The Pronko_Magento2TestModule Magento 2 Module has been successfully added. During Magento installation the Pronko_Magento2TestModule module should be available under Step #4: Customise Your Store under Advances Modules Configurations section.


It is recommended to create new files under /.modman/magento-2-test-module directory. It will help to avoid issues when part of your module has symlinks and another part has files. I have found it easy to modify symlink files under /app/code/Pronko/Magento2TestModule directory once files are created in the /.modman/magento-2-test-module directory. You may prefer to develop directly in the /.modman/magento-2-test-module directory as well.

Updating Module Repository

Once you are happy with development of your Magento 2 module the changes have to be committed. In case we run git status command from Magento 2 root directory it will show 2 untracked directories:

$ git status
On branch 2.0
Your branch is up-to-date with ‘origin/2.0’.
Untracked files:
(use "git add <file>…" to include in what will be committed)


We can even add these 2 directories to the .gitignore file to avoid confusion.

All module changes are now under .modman directory. In order to see changed files we have to execute modman status command. As result it shows 1 new file for the magento-2-test-module repository:

$ modman status
— magento-2-test-module —
On branch master
Your branch is up-to-date with ‘origin/master’.
Changes to be committed:
(use "git reset HEAD <file>…" to unstage)

new file: src/Plugin/Customer.php

Easiest way to update repository is to navigate inside .modman/magento-2-test-module/ directory and perform git commands:

$ cd .modman/magento-2-test-module/
$ git add .
$ git commit -m "New Customer Plugin"
[master 7ac0798] New Customer Plugin
1 file changed, 9 insertions(+)
create mode 100644 src/Plugin/Customer.php

$ git push origin master
Counting objects: 5, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (4/4), done.
Writing objects: 100% (5/5), 500 bytes | 0 bytes/s, done.
Total 5 (delta 1), reused 0 (delta 0)
59a7d64..7ac0798 master -> master

Don’t be confused with Magento 2 repository. There are no changes committed. Only the magento-2-test-module repository has been updated.


In this article we have reviewed 2 ways of adding Module which is stored in a separate repository to Magento 2 project for and continue testing and developing inside Module. For this purposes there are git submodule command can be used. It is less likely something I can recommend. I use modman Module Manager created by Colin Mollenhour which is simple bash script and streight forward to use. It also allows you to manage multiple Modules at a same time.

Follow me @max_pronko on Twitter. I will post more stuff and update you once it is available.

Leave your comments and feedback.





Leave a Reply

Your email address will not be published. Required fields are marked *