Quick Start to Git Submodule

The Problem

As a developer, having loads of reusable code makes work much easier and enjoyable. I’ve got into the habit of breaking the applications I develop in CakePHP into plugins so I can reuse the plugins in other projects. It wasn’t long before I hit some issues. For example, I used plugin X in project A. Then copied plugin X to project B and added new functionality. Not so long after that I extended plugin X in project A. So now I have two “branches” of plugin X and merging them is another task altogether. That project A and project B are git repos doesn’t help either since I don’t want to merge project A and project B.

The Solution

The solution is to make plugin X a git repository and add this repository to project A and project B.  Then I can easily merge changes to plugin X from A and B. Git’s solution to this is git submodule. Git Submodule lets you add a git repo (submodule)  within another git repo (super project). It goes further to track the specific commit of the submodule that the project uses. This makes sure that clones of you super project will be exactly what as it should be. It makes sure that even if the submodule is updated, a new clone you will still get the exact versions of the submodules used in the super project.

However using git submodule is a little tricky because there are some issues you need to be aware of otherwise this solution would turn out to be another problem. Check out following sites for more info on it

Below are steps for achieving various tasks using submodule without falling into its pits.

Adding A New Submodule

# git submodule add git@<server_url>:<submodule_name>.git <your_folder>

Cloning a Project With Submodules

# git clone
# git submodule init
# git submodule update

Modifying A Submodule

# cd <submodule dir>

You have to checkout the submodule into a branch

# git checkout -b work

Apply Changes You’ll like to make

# git commit -a
# git checkout master
# git merge work
# git push
# git checkout work
# cd <super_project_dir>
# git commit -a
# git push

Upgrading A Submodule  in Cloned Project

# cd <super_project_dir>
# git pull origin master
# git submodule update


  • Create a branch when you want to work in a submodule, merge with master and push changes.
  • Always commit and push changes in a submodule before committing and pushing  a super project.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s