Repository is archived
No commit activity in last 3 years
No release in over 3 years
There's a lot of open issues
Giternal provides dead-simple management of external git dependencies. It only stores a small bit of metadata, letting you actively develop in any of the repos. Come deploy time, you can easily freeze freeze all the dependencies to particular versions


 Project Readme

giternal is unmaintained¶ ↑

If you want the functionality that giternal provides, but in a tool that's being maintained, you should consider:

Thanks to @jwhitley for the suggested alternatives.

Installation¶ ↑

`gem install giternal`

Why giternal¶ ↑

There are a couple tools out there that keep track of git externals for you. Git submodules are built in, and braid is a different project. They both have problems that prevent them from using those externals collaboratively.

In a nutshell, git submodules keep a reference to the head of each external project. This means that if Joe and Sarah each make non-conflicting changes to their externals, and push the external reference in the main project, one of them will get a conflict on update. Braid doesn't treat the externals as being separate from the main project, so any commits you make will go to the parent instead of the external.

In order to demonstrate these issues more concretely, I've written a script that will simulate the workflow of making changes to an external, pushing it upstream, and pulling it into another project. You'll notice in the submodule example that there's a conflict when updating the main repo, and files are missing in the local external after update. In the braid example, the changes never make it upstream. This script checks to see if a tool allows you to not only track dependencies but collaborate as well. To execute it, run

ruby test_trackers.rb giternal|submodules|braid

Using it¶ ↑

Put a file in your project named .giternal.yml or config/giternal.yml, that looks like this:

  repo: git://path/to/repo.git
  path: local/sub/dir

As an example, here's how you'd track rspec:

  repo: git://
  path: vendor/plugins

To pull the externals into your workspace, run “giternal update”. You should add vendor/plugins/rspec to .gitignore to keep the files from being added to your main repo.

Deploying externals¶ ↑

I frequently use a cap task that changes to deploy_root and runs “giternal update” to pull all the externals. The downside with this approach is that you'll get the bleeding edge of your external, and you may want to use a particular version that you've tested and know works with your app. Enter freezing.

Make sure your working dir is clean and then run “giternal freeze”. The externals are no longer separate repos - the history was zipped up so that the external can be unfrozen later. Each external is added to the git index, so all you have to do is commit. You've got a self-contained external that is frozen to a working version, suitable for deploy.

After you've tagged your release, you can unfreeze the giternal with “giternal unfreeze” and get back to development.

How I want to work with externals¶ ↑

When tracking externals, the most important thing is knowing my libraries work together, and second I can try to stay up to date. When I update an external, I would run rake. If it passes, keep that version. If not, look at what it would take to take for my code and the library code to work. If I feel like I can do it, I do, otherwise I unfreeze and stay on the older working version.


Rollcall of awesome people who have contributed to giternal:

Brian Takita & Honkster Team - ability to specify individual repos for


Copyright © 2009-2011 Pat Maddox. See LICENSE for details.