I recently spent some time setting up my *nix configuration files for Bash and VIM in a repository on Github. Since I used several git repositories for handling my various VIM plugins and color schemes, I utilized git’s submodule functionality to link to the original repositories, allowing me to keep the plugins up to date. Today I want to look a little closer at Git submodules and how I’m using them.

Setting Up a Submodule

Setting up a submodule in git, is actually fairly easy, you just pass in the repository address and the folder you want it to go to. So for example, on my VIM plugins, I use the vim-rails plugin by Tim Pope. So to create a git submodule off of this repository for the plugin I use the following:

[bash]
[~/git/dotmatrix]$ git submodule add \
https://github.com/tpope/vim-rails.git \
vim/bundle/vim-rails
[/bash]

This will create a “vim-rails” folder in vim/bundle/ and then download the files from the repository. Meaning that when I commit and then push my dotmatrix repository, it will upload the information for the submodules into my repository on Github. When I set up a new computer, I simply install Git, and then run the following:

[bash]
[~/git]$ git clone \
git@github.com:mkoby/dotmatrix.git –recursive
[/bash]

You’ll note the “–recursive” argument, this is what tells git to first download the files for the repository and then recursively create the folders and download the files for the submodules. I then run my setup script that sets up the various configuration files to their appropriate locations so that I’m ready to code with just a few commands.

Updating the Submodules

Once you have the submodules, you have to update them from time to time. Maybe there’s a bug fix, or maybe a new feature in your submodules. To update them is actually quite simple, you simply run the following command:

[bash]
[~/git/dotmatrix]$ git submodule foreach \
git pull origin master
[/bash]

This goes through each submodule’s folder and runs a regular “git pull” on the folder bringing in the latest changes. The “foreach” argument is actually built into git’s submodule functionality, so there is no hidden magic here.

Conclusion

This is the primary place I’m using Git’s Submodule functionality, but this could be used to separate out various project files into separate repositories for better project organization. If anyone sees that I’m doing something wrong, just let me know as I’m always looking to improve my workflows.