Gems from git repositories

Bundler adds the ability to use gems directly from git repositories. Setting them up is as easy as adding a gem to your Gemfile. Using the very latest version of a gem (or even a fork) is just as easy as using an official release.

Because RubyGems lacks the ability to handle gems from git, any gems installed from a git repository will not show up in gem list. They will, however, be available after running Bundler.setup.

Specify that a gem should come from a git repository with a .gemspec at its root

gem 'nokogiri', :git => 'https://github.com/tenderlove/nokogiri.git'

If there is no .gemspec at the root of a git repository, you must specify a version that bundler should use when resolving dependencies

gem 'deep_merge', '1.0', :git => 'https://github.com/peritor/deep_merge.git'

Specify that a git repository containing multiple .gemspec files should be treated as a gem source

git 'https://github.com/rails/rails.git' do
  gem 'railties'
  gem 'action_pack'
  gem 'active_model'
end

Specify that a git repository should use a particular ref, branch, or tag

:git => 'https://github.com/rails/rails.git', :ref => '4aded'
:git => 'https://github.com/rails/rails.git', :branch => '2-3-stable'
:git => 'https://github.com/rails/rails.git', :tag => 'v2.3.5'

Specifying a ref, branch, or tag for a git repository specified inline works exactly the same way

gem 'nokogiri', :git => 'https://github.com/tenderlove/nokogiri.git', :ref => '0eec4'

Bundler can use HTTP(S), SSH, or git

gem 'nokogiri', :git => 'https://github.com/tenderlove/nokogiri.git'
gem 'nokogiri', :git => 'git@github.com:tenderlove/nokogiri.git'
gem 'nokogiri', :git => 'git://github.com/tenderlove/nokogiri.git'

Specify that the submodules from a git repository also should be expanded by bundler

gem 'rugged', :git => 'git://github.com/libgit2/rugged.git', :submodules => true

If you are getting your gems from a public GitHub repository, you can use the shorthand

gem 'nokogiri', :github => 'tenderlove/nokogiri'

If the repository name is the same as the GitHub account hosting it, you can omit it

gem 'rails', :github => 'rails'

NB: This shorthand can only be used for public repos in Bundler version 1.x. Use HTTPS for read and write:

gem 'rails', :git => 'https://github.com/rails/rails'

All of the usual :git options apply, like :branch and :ref.

gem 'rails', :github => 'rails', :ref => 'a9752dcfd15bcddfe7b6f7126f3a6e0ba5927c56'

There are analogous shortcuts for Bitbucket (:bitbucket) and GitHub Gists (:gist).

gem 'capistrano-sidekiq', :github => 'seuros/capistrano-sidekiq'
gem 'keystone', :bitbucket => 'musicone/keystone'

Custom git sources

The :github shortcut used above is one of Bundler’s built in git sources. Bundler comes with shortcuts for :github, :gist, and :bitbucket, but you can also add your own.

If you’re using Github Enterprise, Stash, or just have a custom git setup, create your own shortcuts by calling git_source before you use your custom option. Here’s an example for Stash:

git_source(:stash){ |repo_name| "https://stash.corp.acme.pl/\#{repo_name}.git" }
gem 'rails', :stash => 'forks/rails'

Security

http:// and git:// URLs are insecure. A man-in-the-middle attacker could tamper with the code as you check it out, and potentially supply you with malicious code instead of the code you meant to check out. Because the :github shortcut uses a git:// URL in Bundler 1.x versions, we recommend using HTTPS URLs or overriding the :github shortcut with your own HTTPS git source.

Local Git Repos

Bundler also allows you to work against a git repository locally instead of using the remote version. This can be achieved by setting up a local override:

bundle config local.GEM_NAME /path/to/local/git/repository

For example, in order to use a local Rack repository, a developer could call:

bundle config local.rack ~/Work/git/rack

and setup the git repo pointing to a branch:

gem 'rack', :github => 'rack/rack', :branch => 'master'

Now instead of checking out the remote git repository, the local override will be used. Similar to a path source, every time the local git repository change, changes will be automatically picked up by Bundler. This means a commit in the local git repo will update the revision in the Gemfile.lock to the local git repo revision. This requires the same attention as git submodules. Before pushing to the remote, you need to ensure the local override was pushed, otherwise you may point to a commit that only exists in your local machine.

Bundler does many checks to ensure a developer won’t work with invalid references. Particularly, we force a developer to specify a branch in the Gemfile in order to use this feature. If the branch specified in the Gemfile and the current branch in the local git repository do not match, Bundler will abort. This ensures that a developer is always working against the correct branches, and prevents accidental locking to a different branch.

Finally, Bundler also ensures that the current revision in the Gemfile.lock exists in the local git repository. By doing this, Bundler forces you to fetch the latest changes in the remotes.

If you do not want bundler to make these branch checks, you can override it by setting this option:

bundle config disable_local_branch_check true