Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
193 lines (184 sloc) 7.72 KB
---
title: How to install gems from git repositories
---
.container.guide
%h2 How to install gems from git repositories
.contents
.bullet
.description
%p
Bundler has the ability to install gems directly from git repositories. Installing
a gem using git is as easy as adding a gem to your Gemfile.
%p
Note that because RubyGems lacks the ability to handle gems from git, any gems
installed from a git repository will not show up in <code>gem list</code>.
They will, however, be available after running <code>Bundler.setup</code>.
.bullet
.description
Specify that a gem should come from a git
repository with a .gemspec at its root
:code
# lang: ruby
gem 'rack', git: 'https://github.com/rack/rack'
.bullet
.description
If there is no .gemspec at the root of
a git repository, you must specify a version
that bundler should use when resolving
dependencies
:code
# lang: ruby
gem 'nokogiri', '1.7.0.1', git: 'https://github.com/sparklemotion/nokogiri'
.bullet
.description
If the gem is located within a subdirectory of
a git repository, you can use the <code>:glob</code> option
to specify the location of its .gemspec
:code
# lang: ruby
gem 'cf-copilot', git: 'https://github.com/cloudfoundry/copilot', glob: 'sdk/ruby/*.gemspec'
.bullet
.description
Specify that a git repository containing
multiple .gemspec files should be treated
as a gem source
:code
# lang: ruby
git 'https://github.com/rails/rails.git' do
gem 'railties'
gem 'actionpack'
gem 'activemodel'
end
.bullet
.description
From the previous example, you may specify a particular ref, branch or tag
:code
# lang: ruby
git 'https://github.com/rails/rails.git', ref: '4aded' do
git 'https://github.com/rails/rails.git', branch: '5-0-stable' do
git 'https://github.com/rails/rails.git', tag: 'v5.0.0' do
.bullet
.description
Specifying a ref, branch, or tag for a
git repository specified inline works
exactly the same way
:code
# lang: ruby
gem 'nokogiri', git: 'https://github.com/rack/rack.git', ref: '0bd839d'
gem 'nokogiri', git: 'https://github.com/rack/rack.git', tag: '2.0.1'
gem 'nokogiri', git: 'https://github.com/rack/rack.git', branch: 'rack-1.5'
.bullet
.description
Bundler can use HTTP(S), SSH, or git
:code
# lang: ruby
gem 'rack', git: 'https://github.com/rack/rack.git'
gem 'rack', git: 'git@github.com:rack/rack.git'
gem 'rack', git: 'git://github.com/rack/rack.git'
.bullet
.description
Specify that the submodules from a git repository
also should be expanded by bundler
:code
# lang: ruby
gem 'rugged', git: 'git://github.com/libgit2/rugged.git', submodules: true
.bullet
.description
If you are getting your gems from a public GitHub repository,
you can use the shorthand
:code
# lang: ruby
gem 'rack', github: 'rack/rack'
.description
If the repository name is the same as the GitHub account hosting it,
you can omit it
:code
# lang: ruby
gem 'rails', github: 'rails'
.description
<b>NB:</b> This shorthand can only be used for public repos in Bundler version 1.x. Use HTTPS for read and write:
:code
# lang: ruby
gem 'rails', git: 'https://github.com/rails/rails'
.description
All of the usual <code>:git</code> options apply, like <code>:branch</code> and <code>:ref</code>.
:code
# lang: ruby
gem 'rails', github: 'rails', ref: 'a9752dcfd15bcddfe7b6f7126f3a6e0ba5927c56'
.description
There are analogous shortcuts for Bitbucket (<code>:bitbucket</code>) and GitHub Gists (<code>:gist</code>).
:code
# lang: ruby
gem 'capistrano-sidekiq', github: 'seuros/capistrano-sidekiq'
gem 'keystone', bitbucket: 'musicone/keystone'
%h2 Custom git sources
.contents
.bullet
.description
The <code>:github</code> shortcut used above is one of Bundler's built in git sources. Bundler comes
with shortcuts for <code>:github</code>, <code>:gist</code>, and <code>:bitbucket</code>, but you can
also add your own.
.description
If you're using Github Enterprise, Stash, or just have a custom git setup, create your own shortcuts
by calling <code>git_source</code> before you use your custom option. Here's an example for Stash:
:code
# lang: ruby
git_source(:stash){ |repo_name| "https://stash.corp.acme.pl/\#{repo_name}.git" }
gem 'rails', stash: 'forks/rails'
%h2 Security
.contents
.bullet
.description
<code>http://</code> and <code>git://</code> 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 <code>:github</code> shortcut uses a <code>git://</code>
URL in Bundler 1.x versions, we recommend using HTTPS URLs or overriding
the <code>:github</code> shortcut with your own HTTPS git source.
%h2#local Local Git Repos
.contents
.bullet
.description
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:
:code
$ bundle config local.GEM_NAME /path/to/local/git/repository
.bullet
.description
For example, in order to use a local Rack repository, a developer could call:
:code
$ bundle config local.rack ~/Work/git/rack
.description
and setup the git repo pointing to a branch:
:code
# lang: ruby
gem 'rack', github: 'rack/rack', branch: 'master'
.bullet
.description
%p
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 <code>Gemfile.lock</code> 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.
%p
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 <code>Gemfile</code> in order to use this feature. If the branch
specified in the <code>Gemfile</code> 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.
%p
Finally, Bundler also ensures that the current revision in the
<code>Gemfile.lock</code> exists in the local git repository. By doing this, Bundler
forces you to fetch the latest changes in the remotes.
.bullet
.description
%p If you do not want bundler to make these branch checks, you can override it by setting this option:
:code
$ bundle config disable_local_branch_check true