Replacing Git Submodules with GitMan

Lots of languages offer dependency managers (pip, gem, npm), but in many situations, that’s not enough. Sometimes you need to:

• use a language without a dependency manager
• include code from multiple languages
• explicitly control the installation location

Git Submodules

When using Git for version control, the obvious choice is to use submodules to include the source from another repository. However, in practice, submodules can often be a pain to use, as they:

• require extra information to meaningfully identify the submodule’s SHA
• cause confusing merge conflicts (one SHA vs. another)
• show confusing status changes when switching branches

And while submodules can be used to track a branch (rather than a SHA), this will:

• show confusing status changes if the branch head moves
• require a new commit by whomever updates submodules first

An Alternative

GitMan avoids these issues and adds the ability to:

• track a specific tag in a source dependency’s repository
• checkout by rev-parse dates (e.g. 'develop@{2015-06-18 10:30:59}')

Installation

To install GitMan, first install Python 3 and it’s dependency manager, pip:

• Windows: python.org/downloads
• Mac: $ brew install python3
• Ubuntu: $ sudo apt-get install python3-pip

Then, install gitman using pip3:

$ pip3 install --upgrade gitman

Version and help information are available on the command-line

$ gitman --version
$ gitman --help

Mimicking Submodule

While GitMan, provides additional capabilities, it can also directly replace the behavior of submodules. To mimic a working tree containing a submodule:

<root>/vendor/my_dependency  # submodule at: a5fe3d...

create a gitman.yml file in the root of your working tree:

location: gitman_sources
sources:
- repo: <URL of my_dependency's repository>
  dir: my_dependency
  rev: a5fe3d
  link: vendor/my_depenendy

and run:

$ gitman install

To display the specific versions of source dependencies:

$ gitman list

See a typo? Help me edit this post.

Find a problem with gitman? Please submit an issue or contribute!