bundler 1.11.1 → 2.2.6

data/{man → lib/bundler/man}/gemfile.5.ronn

@@ -15,7 +15,7 @@ directory as the `Rakefile`.
 A `Gemfile` is evaluated as Ruby code, in a context which makes available
 a number of methods used to describe the gem requirements.
 
-## GLOBAL SOURCES (#source)
+## GLOBAL SOURCES
 
 At the top of the `Gemfile`, add a line for the `Rubygems` source that contains
 the gems listed in the `Gemfile`.
@@ -30,19 +30,19 @@ Sources are checked for gems following the heuristics described in
 will print a warning after installing the gem indicating which source was used,
 and listing the other sources where the gem is available. A specific source can
 be selected for gems that need to use a non-standard repository, suppressing
-this warning, by using the [`:source` option](#SOURCE-source-) or a
+this warning, by using the [`:source` option](#SOURCE) or a
 [`source` block](#BLOCK-FORM-OF-SOURCE-GIT-PATH-GROUP-and-PLATFORMS).
 
-### CREDENTIALS (#credentials)
+### CREDENTIALS
 
-Some gem sources require a username and password. Use `bundle config` to set
-the username and password for any sources that need it. The command must be run
-once on each computer that will install the Gemfile, but this keeps the
+Some gem sources require a username and password. Use [bundle config(1)](bundle-config.1.html) to set
+the username and password for any of the sources that need it. The command must
+be run once on each computer that will install the Gemfile, but this keeps the
 credentials from being stored in plain text in version control.
 
     bundle config gems.example.com user:password
 
-For some sources, like a company Gemfury account, it may be easier to simply
+For some sources, like a company Gemfury account, it may be easier to
 include the credentials in the Gemfile as part of the source URL.
 
     source "https://user:password@gems.example.com"
@@ -50,7 +50,7 @@ include the credentials in the Gemfile as part of the source URL.
 Credentials in the source URL will take precedence over credentials set using
 `config`.
 
-## RUBY (#ruby)
+## RUBY
 
 If your application requires a specific Ruby version or engine, specify your
 requirements using the `ruby` method, with the following arguments.
@@ -59,17 +59,33 @@ All parameters are `OPTIONAL` unless otherwise specified.
 ### VERSION (required)
 
 The version of Ruby that your application requires. If your application
-requires an alternate Ruby engine, such as JRuby or Rubinius, this should be
-the Ruby version that the engine is compatible with.
+requires an alternate Ruby engine, such as JRuby, Rubinius or TruffleRuby, this
+should be the Ruby version that the engine is compatible with.
 
     ruby "1.9.3"
 
-### ENGINE (:engine)
+### ENGINE
 
 Each application _may_ specify a Ruby engine. If an engine is specified, an
 engine version _must_ also be specified.
 
-### ENGINE VERSION (:engine_version)
+What exactly is an Engine?
+  - A Ruby engine is an implementation of the Ruby language.
+
+  - For background: the reference or original implementation of the Ruby
+    programming language is called
+    [Matz's Ruby Interpreter](https://en.wikipedia.org/wiki/Ruby_MRI), or  MRI
+    for short. This is named after Ruby creator Yukihiro Matsumoto,
+    also known as Matz. MRI is also known as CRuby, because it is written in C.
+    MRI is the most widely used Ruby engine.
+
+  - [Other implementations](https://www.ruby-lang.org/en/about/) of Ruby exist.
+    Some of the more well-known implementations include
+    [Rubinius](https://rubinius.com/), and [JRuby](http://jruby.org/).
+    Rubinius is an alternative implementation of Ruby written in Ruby.
+    JRuby is an implementation of Ruby on the JVM, short for Java Virtual Machine.
+
+### ENGINE VERSION
 
 Each application _may_ specify a Ruby engine version. If an engine version is
 specified, an engine _must_ also be specified. If the engine is "ruby" the
@@ -77,13 +93,13 @@ engine version specified _must_ match the Ruby version.
 
     ruby "1.8.7", :engine => "jruby", :engine_version => "1.6.7"
 
-### PATCHLEVEL (:patchlevel)
+### PATCHLEVEL
 
 Each application _may_ specify a Ruby patchlevel.
 
     ruby "2.0.0", :patchlevel => "247"
 
-## GEMS (#gem)
+## GEMS
 
 Specify gem requirements using the `gem` method, with the following arguments.
 All parameters are `OPTIONAL` unless otherwise specified.
@@ -101,16 +117,16 @@ Each _gem_ `MAY` have one or more version specifiers.
     gem "nokogiri", ">= 1.4.2"
     gem "RedCloth", ">= 4.1.0", "< 4.2.0"
 
-### REQUIRE AS (:require)
+### REQUIRE AS
 
 Each _gem_ `MAY` specify files that should be used when autorequiring via
-`Bundler.require`. You may pass an array with multiple files or `true` if file
-you want `required` has same name as _gem_ or `false` to
+`Bundler.require`. You may pass an array with multiple files or `true` if the file
+you want `required` has the same name as _gem_ or `false` to
 prevent any file from being autorequired.
 
     gem "redis", :require => ["redis/connection/hiredis", "redis"]
     gem "webmock", :require => false
-    gem "debugger", :require => true
+    gem "byebug", :require => true
 
 The argument defaults to the name of the gem. For example, these are identical:
 
@@ -118,7 +134,7 @@ The argument defaults to the name of the gem. For example, these are identical:
     gem "nokogiri", :require => "nokogiri"
     gem "nokogiri", :require => true
 
-### GROUPS (:group or :groups)
+### GROUPS
 
 Each _gem_ `MAY` specify membership in one or more groups. Any _gem_ that does
 not specify membership in any group is placed in the `default` group.
@@ -137,32 +153,29 @@ The Bundler runtime allows its two main methods, `Bundler.setup` and
     Bundler.setup(:default, :test)   # set up the _default_ and _test_ groups, but no others
 
     # require requires all of the gems in the specified groups
-    Bundler.require                  # defaults to just the _default_ group
+    Bundler.require                  # defaults to the _default_ group
     Bundler.require(:default)        # identical
     Bundler.require(:default, :test) # requires the _default_ and _test_ groups
-    Bundler.require(:test)           # requires just the _test_ group
+    Bundler.require(:test)           # requires the _test_ group
 
 The Bundler CLI allows you to specify a list of groups whose gems `bundle install` should
-not install with the `--without` option. To specify multiple groups to ignore, specify a
-list of groups separated by spaces.
+not install with the `without` configuration.
 
-    bundle install --without test
-    bundle install --without development test
+To specify multiple groups to ignore, specify a list of groups separated by spaces.
 
-After running `bundle install --without test`, bundler will remember that you excluded
-the test group in the last installation. The next time you run `bundle install`,
-without any `--without option`, bundler will recall it.
+    bundle config set --local without test
+    bundle config set --local without development test
 
 Also, calling `Bundler.setup` with no parameters, or calling `require "bundler/setup"`
 will setup all groups except for the ones you excluded via `--without` (since they
-are obviously not available).
+are not available).
 
 Note that on `bundle install`, bundler downloads and evaluates all gems, in order to
 create a single canonical list of all of the required gems and their dependencies.
 This means that you cannot list different versions of the same gems in different
-groups. For more details, see [Understanding Bundler](http://bundler.io/rationale.html).
+groups. For more details, see [Understanding Bundler](https://bundler.io/rationale.html).
 
-### PLATFORMS (:platforms)
+### PLATFORMS
 
 If a gem should only be used in a particular platform or set of platforms, you can
 specify them. Platforms are essentially identical to groups, except that you do not
@@ -172,63 +185,41 @@ platforms.
 There are a number of `Gemfile` platforms:
 
   * `ruby`:
-    C Ruby (MRI) or Rubinius, but `NOT` Windows
-  * `ruby_18`:
-    _ruby_ `AND` version 1.8
-  * `ruby_19`:
-    _ruby_ `AND` version 1.9
-  * `ruby_20`:
-    _ruby_ `AND` version 2.0
-  * `ruby_21`:
-    _ruby_ `AND` version 2.1
-  * `ruby_22`:
-    _ruby_ `AND` version 2.2
-  * `ruby_23`:
-    _ruby_ `AND` version 2.3
+    C Ruby (MRI), Rubinius or TruffleRuby, but `NOT` Windows
   * `mri`:
-    Same as _ruby_, but not Rubinius
-  * `mri_18`:
-    _mri_ `AND` version 1.8
-  * `mri_19`:
-    _mri_ `AND` version 1.9
-  * `mri_20`:
-    _mri_ `AND` version 2.0
-  * `mri_21`:
-    _mri_ `AND` version 2.1
-  * `mri_22`:
-    _mri_ `AND` version 2.2
-  * `mri_23`:
-    _mri_ `AND` version 2.3
+    Same as _ruby_, but only C Ruby (MRI)
+  * `mingw`:
+    Windows 32 bit 'mingw32' platform (aka RubyInstaller)
+  * `x64_mingw`:
+    Windows 64 bit 'mingw32' platform (aka RubyInstaller x64)
   * `rbx`:
-    Same as _ruby_, but only Rubinius (not MRI)
+    Rubinius
   * `jruby`:
     JRuby
+  * `truffleruby`:
+    TruffleRuby
   * `mswin`:
     Windows
+
+You can restrict further by platform and version for all platforms *except* for
+`rbx`, `jruby`, `truffleruby` and `mswin`.
+
+To specify a version in addition to a platform, append the version number without
+the delimiter to the platform. For example, to specify that a gem should only be
+used on platforms with Ruby 2.3, use:
+
+    ruby_23
+
+The full list of platforms and supported versions includes:
+
+  * `ruby`:
+    1.8, 1.9, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6
+  * `mri`:
+    1.8, 1.9, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6
   * `mingw`:
-    Windows 32 bit 'mingw32' platform (aka RubyInstaller)
-  * `mingw_18`:
-    _mingw_ `AND` version 1.8
-  * `mingw_19`:
-    _mingw_ `AND` version 1.9
-  * `mingw_20`:
-    _mingw_ `AND` version 2.0
-  * `mingw_21`:
-    _mingw_ `AND` version 2.1
-  * `mingw_22`:
-    _mingw_ `AND` version 2.2
-  * `mingw_23`:
-    _mingw_ `AND` version 2.3
+    1.8, 1.9, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6
   * `x64_mingw`:
-    Windows 64 bit 'mingw32' platform (aka RubyInstaller x64)
-  * `x64_mingw_20`:
-    _x64_mingw_ `AND` version 2.0
-  * `x64_mingw_21`:
-    _x64_mingw_ `AND` version 2.1
-  * `x64_mingw_22`:
-    _x64_mingw_ `AND` version 2.2
-  * `x64_mingw_23`:
-    _x64_mingw_ `AND` version 2.3
+    2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6
 
 As with groups, you can specify one or more platforms:
 
@@ -236,11 +227,11 @@ As with groups, you can specify one or more platforms:
     gem "ruby-debug", :platforms => :mri_18
     gem "nokogiri",   :platforms => [:mri_18, :jruby]
 
-All operations involving groups (`bundle install`, `Bundler.setup`,
+All operations involving groups ([`bundle install`](bundle-install.1.html), `Bundler.setup`,
 `Bundler.require`) behave exactly the same as if any groups not
 matching the current platform were explicitly excluded.
 
-### SOURCE (:source)
+### SOURCE
 
 You can select an alternate Rubygems repository for a gem using the ':source'
 option.
@@ -257,9 +248,15 @@ back on global sources using the ordering described in [SOURCE PRIORITY][].
 
 Selecting a specific source repository this way also suppresses the ambiguous
 gem warning described above in
-[GLOBAL SOURCES (#source)](#GLOBAL-SOURCES-source-).
+[GLOBAL SOURCES (#source)](#GLOBAL-SOURCES).
+
+Using the `:source` option for an individual gem will also make that source
+available as a possible global source for any other gems which do not specify
+explicit sources. Thus, when adding gems with explicit sources, it is
+recommended that you also ensure all other gems in the Gemfile are using
+explicit sources.
 
-### GIT (:git)
+### GIT
 
 If necessary, you can specify that a gem is located at a particular
 git repository using the `:git` parameter. The repository can be accessed via
@@ -310,8 +307,17 @@ Git repositories support a number of additional options.
 
   * `branch`, `tag`, and `ref`:
     You `MUST` only specify at most one of these options. The default
-    is `:branch => "master"`
+    is `:branch => "master"`.  For example:
+
+      gem "rails", :git => "https://github.com/rails/rails.git", :branch => "5-0-stable"
+
+      gem "rails", :git => "https://github.com/rails/rails.git", :tag => "v5.0.0"
+
+      gem "rails", :git => "https://github.com/rails/rails.git", :ref => "4aded"
+
   * `submodules`:
+    For reference, a [git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules)
+    lets you have another git repository within a subfolder of your repository.
     Specify `:submodules => true` to cause bundler to expand any
     submodules included in the git repository
 
@@ -333,7 +339,7 @@ and then installs the resulting gem. The `gem build` command,
 which comes standard with Rubygems, evaluates the `.gemspec` in
 the context of the directory in which it is located.
 
-### GIT SOURCE (:git_source)
+### GIT SOURCE
 
 A custom git source can be defined via the `git_source` method. Provide the source's name
 as an argument, and a block which receives a single argument and interpolates it into a
@@ -346,14 +352,14 @@ In addition, if you wish to choose a specific branch:
 
     gem "rails", :stash => "forks/rails", :branch => "branch_name"
 
-### GITHUB (:github)
+### GITHUB
 
 `NOTE`: This shorthand should be avoided until Bundler 2.0, since it
 currently expands to an insecure `git://` URL. This allows a
 man-in-the-middle attacker to compromise your system.
 
 If the git repository you want to use is hosted on GitHub and is public, you can use the
-:github shorthand to specify just the github username and repository name (without the
+:github shorthand to specify the github username and repository name (without the
 trailing ".git"), separated by a slash. If both the username and repository name are the
 same, you can omit one.
 
@@ -366,10 +372,10 @@ Are both equivalent to
 
 Since the `github` method is a specialization of `git_source`, it accepts a `:branch` named argument.
 
-### GIST (:gist)
+### GIST
 
 If the git repository you want to use is hosted as a Github Gist and is public, you can use
-the :gist shorthand to specify just the gist identifier (without the trailing ".git").
+the :gist shorthand to specify the gist identifier (without the trailing ".git").
 
     gem "the_hatch", :gist => "4815162342"
 
@@ -379,10 +385,10 @@ Is equivalent to:
 
 Since the `gist` method is a specialization of `git_source`, it accepts a `:branch` named argument.
 
-### BITBUCKET (:bitbucket)
+### BITBUCKET
 
 If the git repository you want to use is hosted on Bitbucket and is public, you can use the
-:bitbucket shorthand to specify just the bitbucket username and repository name (without the
+:bitbucket shorthand to specify the bitbucket username and repository name (without the
 trailing ".git"), separated by a slash. If both the username and repository name are the
 same, you can omit one.
 
@@ -395,7 +401,7 @@ Are both equivalent to
 
 Since the `bitbucket` method is a specialization of `git_source`, it accepts a `:branch` named argument.
 
-### PATH (:path)
+### PATH
 
 You can specify that a gem is located in a particular location
 on the file system. Relative paths are resolved relative to the
@@ -451,7 +457,14 @@ In the case of the `git` block form, the `:ref`, `:branch`, `:tag`,
 and `:submodules` options may be passed to the `git` method, and
 all gems in the block will inherit those options.
 
-## INSTALL_IF (#install_if)
+The presence of a `source` block in a Gemfile also makes that source
+available as a possible global source for any other gems which do not specify
+explicit sources. Thus, when defining source blocks, it is
+recommended that you also ensure all other gems in the Gemfile are using
+explicit sources, either via source blocks or `:source` directives on
+individual gems.
+
+## INSTALL_IF
 
 The `install_if` method allows gems to be installed based on a proc or lambda.
 This is especially useful for optional gems that can only be used if certain
@@ -461,7 +474,12 @@ software is installed or some other conditions are met.
       gem "pasteboard"
     end
 
-## GEMSPEC (#gemspec)
+## GEMSPEC
+
+The [`.gemspec`](http://guides.rubygems.org/specification-reference/) file is where
+ you provide metadata about your gem to Rubygems. Some required Gemspec
+ attributes include the name, description, and homepage of your gem. This is
+ also where you specify the dependencies your gem needs to run.
 
 If you wish to use Bundler to help install dependencies for a gem while it is
 being developed, use the `gemspec` method to pull in the dependencies listed in
@@ -480,6 +498,10 @@ options, which control where bundler looks for the `.gemspec`, the glob it uses
 for the gemspec (defaults to: "{,*,*/*}.gemspec"), what named `.gemspec` it uses
 (if more than one is present), and which group development dependencies are included in.
 
+When a `gemspec` dependency encounters version conflicts during resolution, the
+local version under development will always be selected -- even if there are
+remote versions that better match other requirements for the `gemspec` gem.
+
 ## SOURCE PRIORITY
 
 When attempting to locate a gem to satisfy a gem requirement,

data/lib/bundler/man/index.txt

@@ -0,0 +1,25 @@
+Gemfile(5)            gemfile.5
+bundle(1)             bundle.1
+bundle-add(1)         bundle-add.1
+bundle-binstubs(1)    bundle-binstubs.1
+bundle-cache(1)       bundle-cache.1
+bundle-check(1)       bundle-check.1
+bundle-clean(1)       bundle-clean.1
+bundle-config(1)      bundle-config.1
+bundle-doctor(1)      bundle-doctor.1
+bundle-exec(1)        bundle-exec.1
+bundle-gem(1)         bundle-gem.1
+bundle-info(1)        bundle-info.1
+bundle-init(1)        bundle-init.1
+bundle-inject(1)      bundle-inject.1
+bundle-install(1)     bundle-install.1
+bundle-list(1)        bundle-list.1
+bundle-lock(1)        bundle-lock.1
+bundle-open(1)        bundle-open.1
+bundle-outdated(1)    bundle-outdated.1
+bundle-platform(1)    bundle-platform.1
+bundle-pristine(1)    bundle-pristine.1
+bundle-remove(1)      bundle-remove.1
+bundle-show(1)        bundle-show.1
+bundle-update(1)      bundle-update.1
+bundle-viz(1)         bundle-viz.1

data/lib/bundler/match_platform.rb

@@ -1,13 +1,24 @@
-require "bundler/gem_helpers"
+# frozen_string_literal: true
+
+require_relative "gem_helpers"
 
 module Bundler
   module MatchPlatform
     include GemHelpers
 
     def match_platform(p)
-      Gem::Platform::RUBY == platform ||
-        platform.nil? || p == platform ||
-        generic(Gem::Platform.new(platform)) === p
+      MatchPlatform.platforms_match?(platform, p)
+    end
+
+    def self.platforms_match?(gemspec_platform, local_platform)
+      return true if gemspec_platform.nil?
+      return true if Gem::Platform::RUBY == gemspec_platform
+      return true if local_platform == gemspec_platform
+      gemspec_platform = Gem::Platform.new(gemspec_platform)
+      return true if GemHelpers.generic(gemspec_platform) === local_platform
+      return true if gemspec_platform === local_platform
+
+      false
     end
   end
 end