Fork me on GitHub

Git External

An alternative to git submodule. More like the git version of svn:external


git external is a tool for including external repositories inside of a super repository or main repository. Is very similar to git submodule since it helps keeping some dependencies or sub-projects in different repositories and reuse them in many projects.

git external intends to mimic the behavior of svn:externals, providing an updatable reference to an external repository which the main repository doesn't need to know about.


Git has something called git submodule which allows a repository to have many modules, all of them are a git repository on their own (meaning they have a .git/ directory and everything).

The problem is each module has a commit id associated with it and every time the module is updated (by issuing a git pull inside the module) this causes a change on the supermodule therefor forcing you to make a new commit only for updating what is sometimes a dependency.

git submodule is a great tool, but it's not for everyone, neither is git external.


git external stores a file in the root of the repository called .gitexternals with a format very similar to the .gitmodules from git submodule (if not almost identical). This file keeps the information of the externals (meaning path and url).

Each external is really a clone of the repository specified to git external add so you can do pretty much everything you'd do on a normal git repository inside an external.

The path where the external's clone resides is added to the .gitignore file in order to keep it out of your way while you get your work done.

Getting Started

git external comes bundled as a ruby gem so installation is pretty straight forward.

  1. install the gem:
      ~$ gem install git-external
  2. add an external to your repository:
      ~some-repo$ git external add /path/to/other/repo.git some/directory
  3. commit the change to .gitignore and .gitexternals so other can have this external too:
      ~some-repo$ git commit .gitignore .gitexternals -m "Add new external /path/to/other/repo.git on some/directory"
  4. initialize the externals on your repository:
      ~some-repo$ git external init
  5. and, eventually, update your externals:
      ~some-repo$ git external update