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 be‐
47       ing 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 im‐
102           plementation 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       the file you want required has the same name as gem or false to prevent
153       any 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 --local without test
215           bundle config set --local 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 Un‐
227       derstanding 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 ex‐
256       cept 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 am‐
313       biguous 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 ex‐
342       actly 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  di‐
345       rectory containing the gem, with the extension .gemspec. This file MUST
346       contain a valid gem specification, as expected by the  gem  build  com‐
347       mand.
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 ad‐
419       dress:
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       You can also directly pass a pull request URL:
466
467
468
469           gem "rails", :github => "https://github.com/rails/rails/pull/43753"
470
471
472
473       Which is equivalent to:
474
475
476
477           gem "rails", :github => "rails/rails", branch: "refs/pull/43753/head"
478
479
480
481   GIST
482       If the git repository you want to use is hosted as a GitHub Gist and is
483       public, you can use the :gist shorthand to specify the gist  identifier
484       (without the trailing ".git").
485
486
487
488           gem "the_hatch", :gist => "4815162342"
489
490
491
492       Is equivalent to:
493
494
495
496           gem "the_hatch", :git => "https://gist.github.com/4815162342.git"
497
498
499
500       Since  the  gist method is a specialization of git_source, it accepts a
501       :branch named argument.
502
503   BITBUCKET
504       If the git repository you want to use is hosted  on  Bitbucket  and  is
505       public,  you  can use the :bitbucket shorthand to specify the bitbucket
506       username and repository name (without the trailing  ".git"),  separated
507       by  a slash. If both the username and repository name are the same, you
508       can omit one.
509
510
511
512           gem "rails", :bitbucket => "rails/rails"
513           gem "rails", :bitbucket => "rails"
514
515
516
517       Are both equivalent to
518
519
520
521           gem "rails", :git => "https://rails@bitbucket.org/rails/rails.git"
522
523
524
525       Since the bitbucket method is a specialization of  git_source,  it  ac‐
526       cepts a :branch named argument.
527
528   PATH
529       You  can  specify that a gem is located in a particular location on the
530       file system. Relative paths are resolved relative to the directory con‐
531       taining the Gemfile.
532
533       Similar  to the semantics of the :git option, the :path option requires
534       that the directory in question either contains a .gemspec for the  gem,
535       or that you specify an explicit version that bundler should use.
536
537       Unlike  :git,  bundler does not compile C extensions for gems specified
538       as paths.
539
540
541
542           gem "rails", :path => "vendor/rails"
543
544
545
546       If you would like to use multiple local gems directly from the filesys‐
547       tem,  you can set a global path option to the path containing the gem´s
548       files. This will automatically load gemspec files from subdirectories.
549
550
551
552           path ´components´ do
553             gem ´admin_ui´
554             gem ´public_ui´
555           end
556
557
558

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

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

INSTALL_IF

603       The install_if method allows gems to be installed based on  a  proc  or
604       lambda.  This  is  especially useful for optional gems that can only be
605       used if certain software is installed or some other conditions are met.
606
607
608
609           install_if -> { RUBY_PLATFORM =~ /darwin/ } do
610             gem "pasteboard"
611           end
612
613
614

GEMSPEC

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

SOURCE PRIORITY

646       When  attempting  to locate a gem to satisfy a gem requirement, bundler
647       uses the following priority order:
648
649       1.  The source explicitly attached to the gem (using :source, :path, or
650           :git)
651
652       2.  For implicit gems (dependencies of explicit gems), any source, git,
653           or path repository declared on the parent. This results in  bundler
654           prioritizing  the  ActiveSupport  gem from the Rails git repository
655           over ones from rubygems.org
656
657       3.  The sources specified  via  global  source  lines,  searching  each
658           source in your Gemfile from last added to first added.
659
660
661
662
663
664
665                                 December 2021                      GEMFILE(5)
Impressum