Introducing externals

With externals, git dependencies appear as frozen, version controlled code to anybody who checks out your project. Developers run externals unfreeze, and frozen git repositories magically become real git repositories. Commit changes to the external, run externals freeze, and commit the frozen changes to your parent project. The external’s .git directory is compressed and stored in /tmp when frozen, and moved back to the external when unfrozen.

Installation & Getting Started

Install the Gem

gem sources -a http://gems.github.com
sudo gem install winton-externals

Create a configuration file.

my_repo/config/externals.yml or my_repo/.externals.yml

acts_as_archive:
  repo: git://github.com/winton/acts_as_archive.git
  path: vendor/plugins
rails:
  repo: git://github.com/rails/rails.git
  path: vendor

Freeze & Unfreeze

Run freeze or unfreeze for the first time:

cd my_repo
externals freeze
externals unfreeze

Commit to the parent repository like normal:

git add .
git commit -m "Freezing Gems"
git push origin master

Freeze one of the items in the configuration file:

externals freeze acts_as_archive
externals unfreeze acts_as_archive

The external becomes its own repository again when unfrozen. Let’s pull the latest changes from the Rails repository:

externals unfreeze
cd vendor/rails
git pull origin master
cd ../../
externals freeze

Freeze and unfreeze specific externals using a regular expression match. This would also freeze rails:

externals freeze ra

Extras

Are my externals frozen?

To view the freeze state of your project’s externals, check the status:

externals status

Nifty Shortcuts

externals st # status
externals fr # freeze
externals un # unfreeze

Alternatives

This gem is a simplified version of giternal by Pat Maddox. Submodules and cached_externals are solutions that address the dependency problem without freezing.

Why?

Submodules suck.