1GEMFILE(5)                                                          GEMFILE(5)
2
3
4

NAME

6       Gemfile - A format for describing gem dependencies for Ruby programs
7

SYNOPSIS

9       A Gemfile describes the gem dependencies required to execute associated
10       Ruby code.
11
12       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

SYNTAX

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

GLOBAL SOURCES

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
24
25
26           source "https://rubygems.org"
27
28
29
30       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
34       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
42   CREDENTIALS
43       Some gem sources require a username and password. Use bundle  config(1)
44       bundle-config.1.html  to  set  the username and password for any of the
45       sources that need it. The command must be run  once  on  each  computer
46       that  will  install  the  Gemfile,  but this keeps the credentials from
47       being stored in plain text in version control.
48
49
50
51           bundle config gems.example.com user:password
52
53
54
55       For some sources, like a company Gemfury account, it may be  easier  to
56       include the credentials in the Gemfile as part of the source URL.
57
58
59
60           source "https://user:password@gems.example.com"
61
62
63
64       Credentials in the source URL will take precedence over credentials set
65       using config.
66

RUBY

68       If your application requires a specific Ruby version or engine, specify
69       your  requirements using the ruby method, with the following arguments.
70       All parameters are OPTIONAL unless otherwise specified.
71
72   VERSION (required)
73       The version of Ruby that your application requires. If your application
74       requires  an  alternate  Ruby  engine, such as JRuby, Rubinius or Truf‐
75       fleRuby, this should be the Ruby version that the engine is  compatible
76       with.
77
78
79
80           ruby "1.9.3"
81
82
83
84   ENGINE
85       Each  application may specify a Ruby engine. If an engine is specified,
86       an engine version must also be specified.
87
88       What exactly is an Engine? - A Ruby engine is an implementation of  the
89       Ruby language.
90
91       ·   For  background:  the  reference  or original implementation of the
92           Ruby  programming  language  is  called  Matz´s  Ruby   Interpreter
93           https://en.wikipedia.org/wiki/Ruby_MRI,  or  MRI for short. This is
94           named after Ruby creator Yukihiro Matsumoto, also  known  as  Matz.
95           MRI  is also known as CRuby, because it is written in C. MRI is the
96           most widely used Ruby engine.
97
98       ·   Other implementations https://www.ruby-lang.org/en/about/  of  Ruby
99           exist. Some of the more well-known implementations include Rubinius
100           https://rubinius.com/, and JRuby http://jruby.org/. Rubinius is  an
101           alternative  implementation  of  Ruby  written in Ruby. JRuby is an
102           implementation of Ruby on the JVM, short for Java Virtual Machine.
103
104
105
106   ENGINE VERSION
107       Each application may specify a Ruby engine version. If an  engine  ver‐
108       sion  is  specified, an engine must also be specified. If the engine is
109       "ruby" the engine version specified must match the Ruby version.
110
111
112
113           ruby "1.8.7", :engine => "jruby", :engine_version => "1.6.7"
114
115
116
117   PATCHLEVEL
118       Each application may specify a Ruby patchlevel.
119
120
121
122           ruby "2.0.0", :patchlevel => "247"
123
124
125

GEMS

127       Specify gem requirements using the gem method, with the following argu‐
128       ments. All parameters are OPTIONAL unless otherwise specified.
129
130   NAME (required)
131       For each gem requirement, list a single gem line.
132
133
134
135           gem "nokogiri"
136
137
138
139   VERSION
140       Each gem MAY have one or more version specifiers.
141
142
143
144           gem "nokogiri", ">= 1.4.2"
145           gem "RedCloth", ">= 4.1.0", "< 4.2.0"
146
147
148
149   REQUIRE AS
150       Each  gem  MAY specify files that should be used when autorequiring via
151       Bundler.require. You may pass an array with multiple files or  true  if
152       file  you  want  required  has same name as gem or false to prevent any
153       file from being autorequired.
154
155
156
157           gem "redis", :require => ["redis/connection/hiredis", "redis"]
158           gem "webmock", :require => false
159           gem "debugger", :require => true
160
161
162
163       The argument defaults to the name of the gem. For  example,  these  are
164       identical:
165
166
167
168           gem "nokogiri"
169           gem "nokogiri", :require => "nokogiri"
170           gem "nokogiri", :require => true
171
172
173
174   GROUPS
175       Each  gem  MAY  specify  membership in one or more groups. Any gem that
176       does not specify membership in any  group  is  placed  in  the  default
177       group.
178
179
180
181           gem "rspec", :group => :test
182           gem "wirble", :groups => [:development, :test]
183
184
185
186       The  Bundler  runtime  allows  its  two main methods, Bundler.setup and
187       Bundler.require, to limit their impact to particular groups.
188
189
190
191           # setup adds gems to Ruby´s load path
192           Bundler.setup                    # defaults to all groups
193           require "bundler/setup"          # same as Bundler.setup
194           Bundler.setup(:default)          # only set up the _default_ group
195           Bundler.setup(:test)             # only set up the _test_ group (but `not` _default_)
196           Bundler.setup(:default, :test)   # set up the _default_ and _test_ groups, but no others
197
198           # require requires all of the gems in the specified groups
199           Bundler.require                  # defaults to the _default_ group
200           Bundler.require(:default)        # identical
201           Bundler.require(:default, :test) # requires the _default_ and _test_ groups
202           Bundler.require(:test)           # requires the _test_ group
203
204
205
206       The Bundler CLI allows you to specify a list of groups whose gems  bun‐
207       dle  install  should  not install with the --without option. To specify
208       multiple groups to ignore, specify a list of groups separated  by  spa‐
209       ces.
210
211
212
213           bundle install --without test
214           bundle install --without development test
215
216
217
218       After running bundle install --without test, bundler will remember that
219       you excluded the test group in the last installation. The next time you
220       run  bundle  install, without any --without option, bundler will recall
221       it.
222
223       Also, calling Bundler.setup with  no  parameters,  or  calling  require
224       "bundler/setup"  will setup all groups except for the ones you excluded
225       via --without (since they are not available).
226
227       Note that on bundle install, bundler downloads and evaluates all  gems,
228       in  order to create a single canonical list of all of the required gems
229       and their dependencies. This means that you cannot list different  ver‐
230       sions  of  the  same  gems  in  different groups. For more details, see
231       Understanding Bundler http://bundler.io/rationale.html.
232
233   PLATFORMS
234       If a gem should only be used in a particular platform or set  of  plat‐
235       forms,  you  can  specify  them. Platforms are essentially identical to
236       groups, except that you do not need to use the  --without  install-time
237       flag to exclude groups of gems for other platforms.
238
239       There are a number of Gemfile platforms:
240
241       ruby   C Ruby (MRI), Rubinius or TruffleRuby, but NOT Windows
242
243       mri    Same as ruby, but only C Ruby (MRI)
244
245       mingw  Windows 32 bit ´mingw32´ platform (aka RubyInstaller)
246
247       x64_mingw
248              Windows 64 bit ´mingw32´ platform (aka RubyInstaller x64)
249
250       rbx    Rubinius
251
252       jruby  JRuby
253
254       truffleruby
255              TruffleRuby
256
257       mswin  Windows
258
259       You  can  restrict  further  by  platform and version for all platforms
260       except for rbx, jruby, truffleruby and mswin.
261
262       To specify a version in addition to a platform, append the version num‐
263       ber without the delimiter to the platform. For example, to specify that
264       a gem should only be used on platforms with Ruby 2.3, use:
265
266
267
268           ruby_23
269
270
271
272       The full list of platforms and supported versions includes:
273
274       ruby   1.8, 1.9, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5
275
276       mri    1.8, 1.9, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5
277
278       mingw  1.8, 1.9, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5
279
280       x64_mingw
281              2.0, 2.1, 2.2, 2.3, 2.4, 2.5
282
283       As with groups, you can specify one or more platforms:
284
285
286
287           gem "weakling",   :platforms => :jruby
288           gem "ruby-debug", :platforms => :mri_18
289           gem "nokogiri",   :platforms => [:mri_18, :jruby]
290
291
292
293       All operations involving groups (bundle install  bundle-install.1.html,
294       Bundler.setup,  Bundler.require)  behave  exactly  the  same  as if any
295       groups not matching the current platform were explicitly excluded.
296
297   SOURCE
298       You can select an alternate Rubygems repository for  a  gem  using  the
299       ´:source´ option.
300
301
302
303           gem "some_internal_gem", :source => "https://gems.example.com"
304
305
306
307       This  forces  the  gem  to  be  loaded from this source and ignores any
308       global sources declared at the top level of the file. If the  gem  does
309       not exist in this source, it will not be installed.
310
311       Bundler will search for child dependencies of this gem by first looking
312       in the source selected for the parent, but if they are not found there,
313       it  will  fall  back  on global sources using the ordering described in
314       SOURCE PRIORITY.
315
316       Selecting a specific source repository this  way  also  suppresses  the
317       ambiguous gem warning described above in GLOBAL SOURCES (#source).
318
319       Using  the  :source  option  for  an individual gem will also make that
320       source available as a possible global source for any other  gems  which
321       do  not  specify explicit sources. Thus, when adding gems with explicit
322       sources, it is recommended that you also ensure all other gems  in  the
323       Gemfile are using explicit sources.
324
325   GIT
326       If necessary, you can specify that a gem is located at a particular git
327       repository using the :git parameter. The repository can be accessed via
328       several protocols:
329
330       HTTP(S)
331              gem "rails", :git => "https://github.com/rails/rails.git"
332
333       SSH    gem "rails", :git => "git@github.com:rails/rails.git"
334
335       git    gem "rails", :git => "git://github.com/rails/rails.git"
336
337       If using SSH, the user that you use to run bundle install MUST have the
338       appropriate keys available in their $HOME/.ssh.
339
340       NOTE: http:// and git:// URLs should be avoided  if  at  all  possible.
341       These  protocols  are  unauthenticated, so a man-in-the-middle attacker
342       can deliver malicious code and compromise your system.  HTTPS  and  SSH
343       are strongly preferred.
344
345       The  group,  platforms,  and  require  options are available and behave
346       exactly the same as they would for a normal gem.
347
348       A git repository SHOULD have at least one file,  at  the  root  of  the
349       directory  containing  the  gem, with the extension .gemspec. This file
350       MUST contain a valid gem specification, as expected by  the  gem  build
351       command.
352
353       If  a  git repository does not have a .gemspec, bundler will attempt to
354       create one, but it will not contain any dependencies, executables, or C
355       extension  compilation  instructions. As a result, it may fail to prop‐
356       erly integrate into your application.
357
358       If a git repository does have a .gemspec for the gem  you  attached  it
359       to,  a version specifier, if provided, means that the git repository is
360       only valid if the .gemspec specifies a  version  matching  the  version
361       specifier. If not, bundler will print a warning.
362
363
364
365           gem "rails", "2.3.8", :git => "https://github.com/rails/rails.git"
366           # bundle install will fail, because the .gemspec in the rails
367           # repository´s master branch specifies version 3.0.0
368
369
370
371       If  a  git repository does not have a .gemspec for the gem you attached
372       it to, a version specifier MUST be provided. Bundler will use this ver‐
373       sion in the simple .gemspec it creates.
374
375       Git repositories support a number of additional options.
376
377       branch, tag, and ref
378              You  MUST only specify at most one of these options. The default
379              is :branch => "master"
380
381       For example:
382
383              git "https://github.com/rails/rails.git", :branch  =>  "5-0-sta‐
384              ble" do
385
386              git "https://github.com/rails/rails.git", :tag => "v5.0.0" do
387
388              git "https://github.com/rails/rails.git", :ref => "4aded" do
389
390       submodules
391              For          reference,          a         git         submodule
392              https://git-scm.com/book/en/v2/Git-Tools-Submodules   lets   you
393              have  another  git repository within a subfolder of your reposi‐
394              tory. Specify :submodules => true to cause bundler to expand any
395              submodules included in the git repository
396
397       If  a  git repository contains multiple .gemspecs, each .gemspec repre‐
398       sents a gem located at the same place in the file system as  the  .gem‐
399       spec.
400
401
402
403           |~rails                   [git root]
404           | |-rails.gemspec         [rails gem located here]
405           |~actionpack
406           | |-actionpack.gemspec    [actionpack gem located here]
407           |~activesupport
408           | |-activesupport.gemspec [activesupport gem located here]
409           |...
410
411
412
413       To  install  a  gem located in a git repository, bundler changes to the
414       directory containing the gemspec, runs gem build name.gemspec and  then
415       installs the resulting gem. The gem build command, which comes standard
416       with Rubygems, evaluates the .gemspec in the context of  the  directory
417       in which it is located.
418
419   GIT SOURCE
420       A  custom  git source can be defined via the git_source method. Provide
421       the source´s name as an argument, and a block which receives  a  single
422       argument  and  interpolates  it  into  a string to return the full repo
423       address:
424
425
426
427           git_source(:stash){ |repo_name| "https://stash.corp.acme.pl/#{repo_name}.git" }
428           gem ´rails´, :stash => ´forks/rails´
429
430
431
432       In addition, if you wish to choose a specific branch:
433
434
435
436           gem "rails", :stash => "forks/rails", :branch => "branch_name"
437
438
439
440   GITHUB
441       NOTE: This shorthand should be avoided until Bundler 2.0, since it cur‐
442       rently expands to an insecure git:// URL. This allows a man-in-the-mid‐
443       dle attacker to compromise your system.
444
445       If the git repository you want to use is hosted on GitHub and  is  pub‐
446       lic,  you  can use the :github shorthand to specify the github username
447       and repository name (without  the  trailing  ".git"),  separated  by  a
448       slash.  If  both the username and repository name are the same, you can
449       omit one.
450
451
452
453           gem "rails", :github => "rails/rails"
454           gem "rails", :github => "rails"
455
456
457
458       Are both equivalent to
459
460
461
462           gem "rails", :git => "git://github.com/rails/rails.git"
463
464
465
466       Since the github method is a specialization of git_source, it accepts a
467       :branch named argument.
468
469   GIST
470       If the git repository you want to use is hosted as a Github Gist and is
471       public, you can use the :gist shorthand to specify the gist  identifier
472       (without the trailing ".git").
473
474
475
476           gem "the_hatch", :gist => "4815162342"
477
478
479
480       Is equivalent to:
481
482
483
484           gem "the_hatch", :git => "https://gist.github.com/4815162342.git"
485
486
487
488       Since  the  gist method is a specialization of git_source, it accepts a
489       :branch named argument.
490
491   BITBUCKET
492       If the git repository you want to use is hosted  on  Bitbucket  and  is
493       public,  you  can use the :bitbucket shorthand to specify the bitbucket
494       username and repository name (without the trailing  ".git"),  separated
495       by  a slash. If both the username and repository name are the same, you
496       can omit one.
497
498
499
500           gem "rails", :bitbucket => "rails/rails"
501           gem "rails", :bitbucket => "rails"
502
503
504
505       Are both equivalent to
506
507
508
509           gem "rails", :git => "https://rails@bitbucket.org/rails/rails.git"
510
511
512
513       Since the bitbucket  method  is  a  specialization  of  git_source,  it
514       accepts a :branch named argument.
515
516   PATH
517       You  can  specify that a gem is located in a particular location on the
518       file system. Relative paths are resolved relative to the directory con‐
519       taining the Gemfile.
520
521       Similar  to the semantics of the :git option, the :path option requires
522       that the directory in question either contains a .gemspec for the  gem,
523       or that you specify an explicit version that bundler should use.
524
525       Unlike  :git,  bundler does not compile C extensions for gems specified
526       as paths.
527
528
529
530           gem "rails", :path => "vendor/rails"
531
532
533
534       If you would like to use multiple local gems directly from the filesys‐
535       tem,  you can set a global path option to the path containing the gem´s
536       files. This will automatically load gemspec files from subdirectories.
537
538
539
540           path ´components´ do
541             gem ´admin_ui´
542             gem ´public_ui´
543           end
544
545
546

BLOCK FORM OF SOURCE, GIT, PATH, GROUP and PLATFORMS

548       The :source, :git, :path, :group, and :platforms options may be applied
549       to a group of gems by using block form.
550
551
552
553           source "https://gems.example.com" do
554             gem "some_internal_gem"
555             gem "another_internal_gem"
556           end
557
558           git "https://github.com/rails/rails.git" do
559             gem "activesupport"
560             gem "actionpack"
561           end
562
563           platforms :ruby do
564             gem "ruby-debug"
565             gem "sqlite3"
566           end
567
568           group :development, :optional => true do
569             gem "wirble"
570             gem "faker"
571           end
572
573
574
575       In  the  case of the group block form the :optional option can be given
576       to prevent a group from being installed unless  listed  in  the  --with
577       option given to the bundle install command.
578
579       In  the  case of the git block form, the :ref, :branch, :tag, and :sub‐
580       modules options may be passed to the git method, and all  gems  in  the
581       block will inherit those options.
582
583       The  presence  of  a  source  block in a Gemfile also makes that source
584       available as a possible global source for any other gems which  do  not
585       specify explicit sources. Thus, when defining source blocks, it is rec‐
586       ommended that you also ensure all other gems in the Gemfile  are  using
587       explicit  sources,  either  via  source blocks or :source directives on
588       individual gems.
589

INSTALL_IF

591       The install_if method allows gems to be installed based on  a  proc  or
592       lambda.  This  is  especially useful for optional gems that can only be
593       used if certain software is installed or some other conditions are met.
594
595
596
597           install_if -> { RUBY_PLATFORM =~ /darwin/ } do
598             gem "pasteboard"
599           end
600
601
602

GEMSPEC

604       The .gemspec  http://guides.rubygems.org/specification-reference/  file
605       is where you provide metadata about your gem to Rubygems. Some required
606       Gemspec attributes include the name, description, and homepage of  your
607       gem.  This is also where you specify the dependencies your gem needs to
608       run.
609
610       If you wish to use Bundler to help install dependencies for a gem while
611       it  is being developed, use the gemspec method to pull in the dependen‐
612       cies listed in the .gemspec file.
613
614       The gemspec method adds any runtime dependencies as gem requirements in
615       the  default  group.  It  also  adds  development  dependencies  as gem
616       requirements in the development group. Finally, it adds a gem  require‐
617       ment on your project (:path => ´.´). In conjunction with Bundler.setup,
618       this allows you to require project files in your test code as you would
619       if  the  project  were  installed as a gem; you need not manipulate the
620       load path manually or require project files via relative paths.
621
622       The gemspec method supports optional :path, :glob, :name, and :develop‐
623       ment_group options, which control where bundler looks for the .gemspec,
624       the glob it uses to look for the  gemspec  (defaults  to:  "{,,/*}.gem‐
625       spec"),  what named .gemspec it uses (if more than one is present), and
626       which group development dependencies are included in.
627
628       When a gemspec dependency encounters version conflicts  during  resolu‐
629       tion,  the  local  version under development will always be selected --
630       even if there are remote versions that better match other  requirements
631       for the gemspec gem.
632

SOURCE PRIORITY

634       When  attempting  to locate a gem to satisfy a gem requirement, bundler
635       uses the following priority order:
636
637       1.  The source explicitly attached to the gem (using :source, :path, or
638           :git)
639
640       2.  For implicit gems (dependencies of explicit gems), any source, git,
641           or path repository declared on the parent. This results in  bundler
642           prioritizing  the  ActiveSupport  gem from the Rails git repository
643           over ones from rubygems.org
644
645       3.  The sources specified  via  global  source  lines,  searching  each
646           source in your Gemfile from last added to first added.
647
648
649
650
651
652
653                                 November 2018                      GEMFILE(5)
Impressum