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

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

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

INSTALL_IF

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

GEMSPEC

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

SOURCE PRIORITY

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