1GEMFILE(5) GEMFILE(5)
2
6 Gemfile - A format for describing gem dependencies for Ruby programs
7
9 A Gemfile describes the gem dependencies required to execute associated
10 Ruby code.
11 Place the Gemfile in the root of the directory containing the associ‐
13 ated code. For instance, in a Rails application, place the Gemfile in
14 the same directory as the Rakefile.
15
17 A Gemfile is evaluated as Ruby code, in a context which makes available
18 a number of methods used to describe the gem requirements.
19
21 At the top of the Gemfile, add a line for the Rubygems source that con‐
22 tains the gems listed in the Gemfile.
23 source "https://rubygems.org"
27 It is possible, but not recommended as of Bundler 1.7, to add multiple
31 global source lines. Each of these sources MUST be a valid Rubygems
32 repository.
33 Sources are checked for gems following the heuristics described in
35 SOURCE PRIORITY. If a gem is found in more than one global source,
36 Bundler will print a warning after installing the gem indicating which
37 source was used, and listing the other sources where the gem is avail‐
38 able. A specific source can be selected for gems that need to use a
39 non-standard repository, suppressing this warning, by using the :source
40 option or a source block.
41 CREDENTIALS (#credentials)
43 Some gem sources require a username and password. Use bundle config to
44 set the username and password for any sources that need it. The command
45 must be run once on each computer that will install the Gemfile, but
46 this keeps the credentials from being stored in plain text in version
47 control.
48 bundle config https://gems.example.com/ user:password
52 For some sources, like a company Gemfury account, it may be easier to
56 simply include the credentials in the Gemfile as part of the source
57 URL.
58 source "https://user:password@gems.example.com"
62 Credentials in the source URL will take precedence over credentials set
66 using config.
67
69 If your application requires a specific Ruby version or engine, specify
70 your requirements using the ruby method, with the following arguments.
71 All parameters are OPTIONAL unless otherwise specified.
72 VERSION (required)
74 The version of Ruby that your application requires. If your application
75 requires an alternate Ruby engine, such as JRuby or Rubinius, this
76 should be the Ruby version that the engine is compatible with.
77 ruby "1.9.3"
81 ENGINE (:engine)
85 Each application may specify a Ruby engine. If an engine is specified,
86 an engine version must also be specified.
87 ENGINE VERSION (:engine_version)
89 Each application may specify a Ruby engine version. If an engine ver‐
90 sion is specified, an engine must also be specified. If the engine is
91 "ruby" the engine version specified must match the Ruby version.
92 ruby "1.8.7", :engine => "jruby", :engine_version => "1.6.7"
96 PATCHLEVEL (:patchlevel)
100 Each application may specify a Ruby patchlevel.
101 ruby "2.0.0", :patchlevel => "247"
105
109 Specify gem requirements using the gem method, with the following argu‐
110 ments. All parameters are OPTIONAL unless otherwise specified.
111 NAME (required)
113 For each gem requirement, list a single gem line.
114 gem "nokogiri"
118 VERSION
122 Each gem MAY have one or more version specifiers.
123 gem "nokogiri", ">= 1.4.2"
127 gem "RedCloth", ">= 4.1.0", "< 4.2.0"
128 REQUIRE AS (:require)
132 Each gem MAY specify files that should be used when autorequiring via
133 Bundler.require. You may pass an array with multiple files or true if
134 file you want required has same name as gem or false to prevent any
135 file from being autorequired.
136 gem "redis", :require => ["redis/connection/hiredis", "redis"]
140 gem "webmock", :require => false
141 gem "debugger", :require => true
142 The argument defaults to the name of the gem. For example, these are
146 identical:
147 gem "nokogiri"
151 gem "nokogiri", :require => "nokogiri"
152 gem "nokogiri", :require => true
153 GROUPS (:group or :groups)
157 Each gem MAY specify membership in one or more groups. Any gem that
158 does not specify membership in any group is placed in the default
159 group.
160 gem "rspec", :group => :test
164 gem "wirble", :groups => [:development, :test]
165 The Bundler runtime allows its two main methods, Bundler.setup and
169 Bundler.require, to limit their impact to particular groups.
170 # setup adds gems to Ruby´s load path
174 Bundler.setup # defaults to all groups
175 require "bundler/setup" # same as Bundler.setup
176 Bundler.setup(:default) # only set up the _default_ group
177 Bundler.setup(:test) # only set up the _test_ group (but `not` _default_)
178 Bundler.setup(:default, :test) # set up the _default_ and _test_ groups, but no others
179 # require requires all of the gems in the specified groups
181 Bundler.require # defaults to just the _default_ group
182 Bundler.require(:default) # identical
183 Bundler.require(:default, :test) # requires the _default_ and _test_ groups
184 Bundler.require(:test) # requires just the _test_ group
185 The Bundler CLI allows you to specify a list of groups whose gems bun‐
189 dle install should not install with the --without option. To specify
190 multiple groups to ignore, specify a list of groups separated by spa‐
191 ces.
192 bundle install --without test
196 bundle install --without development test
197 After running bundle install --without test, bundler will remember that
201 you excluded the test group in the last installation. The next time you
202 run bundle install, without any --without option, bundler will recall
203 it.
204 Also, calling Bundler.setup with no parameters, or calling require
206 "bundler/setup" will setup all groups except for the ones you excluded
207 via --without (since they are obviously not available).
208 Note that on bundle install, bundler downloads and evaluates all gems,
210 in order to create a single canonical list of all of the required gems
211 and their dependencies. This means that you cannot list different ver‐
212 sions of the same gems in different groups. For more details, see
213 Understanding Bundler http://bundler.io/rationale.html.
214 PLATFORMS (:platforms)
216 If a gem should only be used in a particular platform or set of plat‐
217 forms, you can specify them. Platforms are essentially identical to
218 groups, except that you do not need to use the --without install-time
219 flag to exclude groups of gems for other platforms.
220 There are a number of Gemfile platforms:
222 ruby C Ruby (MRI) or Rubinius, but NOT Windows
224 ruby_18
226 ruby AND version 1.8
227 ruby_19
229 ruby AND version 1.9
230 ruby_20
232 ruby AND version 2.0
233 ruby_21
235 ruby AND version 2.1
236 mri Same as ruby, but not Rubinius
238 mri_18 mri AND version 1.8
240 mri_19 mri AND version 1.9
242 mri_20 mri AND version 2.0
244 mri_21 mri AND version 2.1
246 rbx Same as ruby, but only Rubinius (not MRI)
248 jruby JRuby
250 mswin Windows
252 mingw Windows 32 bit ´mingw32´ platform (aka RubyInstaller)
254 mingw_18
256 mingw AND version 1.8
257 mingw_19
259 mingw AND version 1.9
260 mingw_20
262 mingw AND version 2.0
263 mingw_21
265 mingw AND version 2.1
266 x64_mingw
268 Windows 64 bit ´mingw32´ platform (aka RubyInstaller x64)
269 x64_mingw_20
271 x64_mingw AND version 2.0
272 x64_mingw_21
274 x64_mingw AND version 2.1
275 As with groups, you can specify one or more platforms:
277 gem "weakling", :platforms => :jruby
281 gem "ruby-debug", :platforms => :mri_18
282 gem "nokogiri", :platforms => [:mri_18, :jruby]
283 All operations involving groups (bundle install, Bundler.setup,
287 Bundler.require) behave exactly the same as if any groups not matching
288 the current platform were explicitly excluded.
289 SOURCE (:source)
291 You can select an alternate Rubygems repository for a gem using the
292 ´:source´ option.
293 gem "some_internal_gem", :source => "https://gems.example.com"
297 This forces the gem to be loaded from this source and ignores any
301 global sources declared at the top level of the file. If the gem does
302 not exist in this source, it will not be installed.
303 Bundler will search for child dependencies of this gem by first looking
305 in the source selected for the parent, but if they are not found there,
306 it will fall back on global sources using the ordering described in
307 SOURCE PRIORITY.
308 Selecting a specific source repository this way also suppresses the
310 ambiguous gem warning described above in GLOBAL SOURCES (#source).
311 GIT (:git)
313 If necessary, you can specify that a gem is located at a particular git
314 repository. The repository can be public
315 (http://github.com/rails/rails.git) or private
316 (git@github.com:rails/rails.git). If the repository is private, the
317 user that you use to run bundle install MUST have the appropriate keys
318 available in their $HOME/.ssh.
319 Git repositories are specified using the :git parameter. The group,
321 platforms, and require options are available and behave exactly the
322 same as they would for a normal gem.
323 gem "rails", :git => "git://github.com/rails/rails.git"
327 A git repository SHOULD have at least one file, at the root of the
331 directory containing the gem, with the extension .gemspec. This file
332 MUST contain a valid gem specification, as expected by the gem build
333 command.
334 If a git repository does not have a .gemspec, bundler will attempt to
336 create one, but it will not contain any dependencies, executables, or C
337 extension compilation instructions. As a result, it may fail to prop‐
338 erly integrate into your application.
339 If a git repository does have a .gemspec for the gem you attached it
341 to, a version specifier, if provided, means that the git repository is
342 only valid if the .gemspec specifies a version matching the version
343 specifier. If not, bundler will print a warning.
344 gem "rails", "2.3.8", :git => "git://github.com/rails/rails.git"
348 # bundle install will fail, because the .gemspec in the rails
349 # repository´s master branch specifies version 3.0.0
350 If a git repository does not have a .gemspec for the gem you attached
354 it to, a version specifier MUST be provided. Bundler will use this ver‐
355 sion in the simple .gemspec it creates.
356 Git repositories support a number of additional options.
358 branch, tag, and ref
360 You MUST only specify at most one of these options. The default
361 is :branch => "master"
362 submodules
364 Specify :submodules => true to cause bundler to expand any sub‐
365 modules included in the git repository
366 If a git repository contains multiple .gemspecs, each .gemspec repre‐
368 sents a gem located at the same place in the file system as the .gem‐
369 spec.
370 |~rails [git root]
374 | |-rails.gemspec [rails gem located here]
375 |~actionpack
376 | |-actionpack.gemspec [actionpack gem located here]
377 |~activesupport
378 | |-activesupport.gemspec [activesupport gem located here]
379 |...
380 To install a gem located in a git repository, bundler changes to the
384 directory containing the gemspec, runs gem build name.gemspec and then
385 installs the resulting gem. The gem build command, which comes standard
386 with Rubygems, evaluates the .gemspec in the context of the directory
387 in which it is located.
388 GITHUB (:github)
390 If the git repository you want to use is hosted on GitHub and is pub‐
391 lic, you can use the :github shorthand to specify just the github user‐
392 name and repository name (without the trailing ".git"), separated by a
393 slash. If both the username and repository name are the same, you can
394 omit one.
395 gem "rails", :github => "rails/rails"
399 gem "rails", :github => "rails"
400 Are both equivalent to
404 gem "rails", :git => "git://github.com/rails/rails.git"
408 In addition, if you wish to choose a specific branch:
412 gem "rails", :github => "rails/rails", :branch => "branch_name"
416 PATH (:path)
420 You can specify that a gem is located in a particular location on the
421 file system. Relative paths are resolved relative to the directory con‐
422 taining the Gemfile.
423 Similar to the semantics of the :git option, the :path option requires
425 that the directory in question either contains a .gemspec for the gem,
426 or that you specify an explicit version that bundler should use.
427 Unlike :git, bundler does not compile C extensions for gems specified
429 as paths.
430 gem "rails", :path => "vendor/rails"
434
438 The :source, :git, :path, :group, and :platforms options may be applied
439 to a group of gems by using block form.
440 source "https://gems.example.com" do
444 gem "some_internal_gem"
445 gem "another_internal_gem"
446 end
447 git "git://github.com/rails/rails.git" do
449 gem "activesupport"
450 gem "actionpack"
451 end
452 platforms :ruby do
454 gem "ruby-debug"
455 gem "sqlite3"
456 end
457 group :development do
459 gem "wirble"
460 gem "faker"
461 end
462 In the case of the git block form, the :ref, :branch, :tag, and :sub‐
466 modules options may be passed to the git method, and all gems in the
467 block will inherit those options.
468
470 If you wish to use Bundler to help install dependencies for a gem while
471 it is being developed, use the gemspec method to pull in the dependen‐
472 cies listed in the .gemspec file.
473 The gemspec method adds any runtime dependencies as gem requirements in
475 the default group. It also adds development dependencies as gem
476 requirements in the development group. Finally, it adds a gem require‐
477 ment on your project (:path => ´.´). In conjunction with Bundler.setup,
478 this allows you to require project files in your test code as you would
479 if the project were installed as a gem; you need not manipulate the
480 load path manually or require project files via relative paths.
481 The gemspec method supports optional :path, :name, and :develop‐
483 ment_group options, which control where bundler looks for the .gemspec,
484 what named .gemspec it uses (if more than one is present), and which
485 group development dependencies are included in.
486
488 When attempting to locate a gem to satisfy a gem requirement, bundler
489 uses the following priority order:
490 1. The source explicitly attached to the gem (using :source, :path, or
492 :git)
493 2. For implicit gems (dependencies of explicit gems), any source, git,
495 or path repository declared on the parent. This results in bundler
496 prioritizing the ActiveSupport gem from the Rails git repository
497 over ones from rubygems.org
498 3. The sources specified via global source lines, searching each
500 source in your Gemfile from last added to first added.
501 December 2014 GEMFILE(5)