bundler 4.1.0.beta1 → 4.1.0.beta3

data/lib/bundler/dsl.rb

@@ -17,7 +17,7 @@ module Bundler
     VALID_PLATFORMS = Bundler::CurrentRuby::PLATFORM_MAP.keys.freeze
 
     VALID_KEYS = %w[group groups git path glob name branch ref tag require submodules
-                    platform platforms source install_if force_ruby_platform].freeze
+                    platform platforms source install_if force_ruby_platform sparse_checkout].freeze
 
     GITHUB_PULL_REQUEST_URL = %r{\Ahttps://github\.com/([A-Za-z0-9_\-\.]+/[A-Za-z0-9_\-\.]+)/pull/(\d+)\z}
     GITLAB_MERGE_REQUEST_URL = %r{\Ahttps://gitlab\.com/([A-Za-z0-9_\-\./]+)/-/merge_requests/(\d+)\z}
@@ -200,6 +200,17 @@ module Bundler
 
     def override(target, **operations)
       validate_override_target!(target)
+      source_location = caller_locations(1, 1)&.first
+
+      # 4.1.0.beta2 spelled `with:` and `in:` as `to:` and `from:`.
+      if operations.key?(:from)
+        raise ArgumentError, "`from:` and `to:` of `override` are now `in:` and `with:`; write `override #{target.inspect}, with: #{operations.fetch(:to, "<gem>").inspect}, in: #{operations[:from].inspect}`"
+      end
+
+      if operations.key?(:in) || operations.key?(:with)
+        add_dependency_override(target, operations, source_location)
+        return
+      end
 
       if target == :all && operations.key?(:version)
         raise ArgumentError, "`override :all, version:` is not allowed; version requirements are per-gem"
@@ -211,7 +222,6 @@ module Bundler
         validate_override_uniqueness!(target, field)
       end
 
-      source_location = caller_locations(1, 1)&.first
       operations.each do |field, operation|
         @overrides << Override.new(target, field, operation, source_location: source_location)
       end
@@ -219,6 +229,7 @@ module Bundler
 
     def to_definition(lockfile, unlock)
       check_primary_source_safety
+      check_dropped_dependencies
       lockfile = @lockfile unless @lockfile.nil?
       Definition.new(lockfile, @dependencies, @sources, unlock, @ruby_version, @optional_groups, @gemfiles, @overrides)
     end
@@ -286,8 +297,16 @@ module Bundler
 
     def validate_override_target!(target)
       return if target == :all
-      return if target.is_a?(String)
-      raise ArgumentError, "override target must be :all or a gem name string, got #{target.inspect}"
+      raise ArgumentError, "override target must be :all or a gem name string, got #{target.inspect}" unless target.is_a?(String)
+      validate_override_gem_name!(target)
+    end
+
+    # Override names are recorded in the lockfile's OVERRIDES section, so they
+    # must be valid gem names.
+    def validate_override_gem_name!(name)
+      validate_gem_name!(name)
+      return if Gem::Specification::VALID_NAME_PATTERN.match?(name)
+      raise GemfileError, "#{name.inspect} is not a valid gem name"
     end
 
     def validate_override_field!(field)
@@ -317,6 +336,54 @@ module Bundler
       raise ArgumentError, "duplicate override for #{target.inspect} `#{field}:`"
     end
 
+    def add_dependency_override(target, operations, source_location)
+      unless operations.key?(:in)
+        raise ArgumentError, "`override #{target.inspect}, with:` requires `in:` naming the gem whose dependency is rewritten"
+      end
+      unless operations.key?(:with)
+        raise ArgumentError, "`override #{target.inspect}, in:` requires `with:`; use `with: nil` to drop the dependency or `with: \"<gem>\"` to replace it"
+      end
+
+      from = operations[:in]
+      with = operations[:with]
+      requirement = operations[:version]
+
+      raise ArgumentError, "`override :all` does not accept `in:`" if target == :all
+      raise ArgumentError, "`in:` must be a gem name string, got #{from.inspect}" unless from.is_a?(String)
+      raise ArgumentError, "`with:` must be a gem name string or nil, got #{with.inspect}" unless with.nil? || with.is_a?(String)
+      raise ArgumentError, "`with:` must name a gem other than #{target.inspect} and #{from.inspect}" if with == target || with == from
+      validate_override_gem_name!(from)
+      validate_override_gem_name!(with) if with
+
+      unsupported = operations.keys - [:in, :with, :version]
+      if unsupported.any?
+        raise ArgumentError, "unsupported override field `#{unsupported.first}:` with `in:`; supported fields: `with:`, `version:`"
+      end
+
+      if operations.key?(:version)
+        raise ArgumentError, "`version:` with `in:` requires `with:` to name a replacement gem" if with.nil?
+        raise ArgumentError, "`version:` with `in:` must be a version requirement string, got #{requirement.inspect}" unless requirement.is_a?(String)
+        validate_override_operation!(requirement)
+      end
+
+      if @overrides.any? {|o| o.target == target && o.from == from }
+        raise ArgumentError, "duplicate override for #{target.inspect} `in: #{from.inspect}`"
+      end
+
+      @overrides << Override.new(target, :with, with, from: from, requirement: requirement, source_location: source_location)
+    end
+
+    # Dropping a gem the Gemfile requires directly would leave it installed
+    # anyway, with only the parent's requirement gone.
+    def check_dropped_dependencies
+      @overrides.each do |override|
+        next unless override.from && override.operation.nil?
+        next unless @dependencies.any? {|d| d.name == override.target }
+
+        raise GemfileError, "#{override} cannot drop #{override.target} because the Gemfile depends on it directly"
+      end
+    end
+
     def add_dependency(name, version = nil, options = {})
       options["gemfile"] = @gemfile
       options["source"] ||= @source
@@ -460,7 +527,7 @@ module Bundler
       @valid_keys ||= VALID_KEYS
     end
 
-    def normalize_options(name, version, opts)
+    def validate_gem_name!(name)
       if name.is_a?(Symbol)
         raise GemfileError, %(You need to specify gem names as Strings. Use 'gem "#{name}"' instead)
       end
@@ -468,6 +535,10 @@ module Bundler
         raise GemfileError, %('#{name}' is not a valid gem name because it contains whitespace)
       end
       raise GemfileError, %(an empty gem name is not valid) if name.empty?
+    end
+
+    def normalize_options(name, version, opts)
+      validate_gem_name!(name)
 
       normalize_hash(opts)
 

data/lib/bundler/fetcher/downloader.rb

@@ -56,12 +56,18 @@ module Bundler
           if https?(uri) && !https?(new_uri)
             raise HTTPError, "Redirecting to a non-https URI is not allowed: #{URICredentialsFilter.credential_filtered_uri(new_uri)}"
           end
-          if new_uri.host == uri.host
+          if [new_uri.scheme, new_uri.host, new_uri.port] == [uri.scheme, uri.host, uri.port]
             new_uri.user = uri.user
             new_uri.password = uri.password
+          else
+            # see Gem::RemoteFetcher#fetch_http. A nil value removes the header
+            # that ConnectionPools adds from its override_headers.
+            headers = headers.merge("X-Gemfile-Source" => nil)
           end
           fetch(new_uri, headers, counter + 1)
         when Gem::Net::HTTPRequestedRangeNotSatisfiable
+          raise bad_response(response) unless headers.key?("Range")
+
           new_headers = headers.dup
           new_headers.delete("Range")
           fetch(uri, new_headers)
@@ -77,9 +83,7 @@ module Bundler
         when Gem::Net::HTTPNotFound
           raise FallbackError, "Gem::Net::HTTPNotFound: #{filtered_uri}"
         else
-          message = "Gem::#{response.class.name.gsub(/\AGem::/, "")}"
-          message += ": #{response.body}" unless response.body.empty?
-          raise HTTPError, message
+          raise bad_response(response)
         end
       end
 
@@ -117,6 +121,12 @@ module Bundler
 
       private
 
+      def bad_response(response)
+        message = "Gem::#{response.class.name.gsub(/\AGem::/, "")}"
+        message += ": #{response.body}" unless response.body.empty?
+        HTTPError.new(message)
+      end
+
       def network_down_error(uri, filtered_uri)
         host = uri.host
         host_port = "#{host}:#{uri.port}"

data/lib/bundler/fetcher.rb

@@ -157,7 +157,10 @@ module Bundler
       elsif cached_spec_path = gemspec_cached_path(spec_file_name)
         Bundler.load_gemspec(cached_spec_path)
       else
-        Bundler.safe_load_marshal Bundler.rubygems.inflate(downloader.fetch(uri).body)
+        body = Bundler::Retry.new("fetcher", FAIL_ERRORS).attempts do
+          downloader.fetch(uri).body
+        end
+        Bundler.safe_load_marshal Bundler.rubygems.inflate(body)
       end
       raise MarshalError, "is #{spec.inspect}" unless spec.is_a?(Gem::Specification)
       spec

data/lib/bundler/gem_helper.rb

@@ -216,7 +216,7 @@ module Bundler
       Bundler.ui.debug(cmd)
       SharedHelpers.chdir(base) do
         outbuf = IO.popen(cmd, err: [:child, :out], &:read)
-        status = $?
+        status = Process.last_status
         block&.call(outbuf) if status.success?
         [outbuf, status]
       end

data/lib/bundler/installer/parallel_installer.rb

@@ -69,7 +69,8 @@ module Bundler
       @specs = all_specs.map {|s| SpecInstallation.new(s) }
       specs_by_name = @specs.to_h {|s| [s.name, s] }
       @specs.each do |spec_install|
-        spec_install.dependencies = spec_install.spec.dependencies.filter_map do |dep|
+        dependencies = Override.rewrite_dependencies(installer.definition.overrides, spec_install.name, spec_install.spec.dependencies)
+        spec_install.dependencies = dependencies.filter_map do |dep|
           specs_by_name[dep.name] unless dep.type == :development || dep.name == spec_install.name
         end
       end

data/lib/bundler/installer.rb

@@ -103,7 +103,7 @@ module Bundler
 
       if options[:binstubs_cmd] && spec.executables.empty?
         options = {}
-        spec.runtime_dependencies.each do |dep|
+        Override.rewrite_dependencies(@definition.overrides, spec.name, spec.runtime_dependencies).each do |dep|
           bins = @definition.specs[dep].first.executables
           options[dep.name] = bins unless bins.empty?
         end
@@ -127,6 +127,8 @@ module Bundler
       template_path = File.expand_path("templates/Executable", __dir__)
       template = File.read(template_path)
 
+      Bundler.mkdir_p(bin_path)
+
       exists = []
       spec.executables.each do |executable|
         binstub_path = "#{bin_path}/#{executable}"
@@ -173,6 +175,8 @@ module Bundler
       ruby_command = Thor::Util.ruby_command
       ruby_command = ruby_command
 
+      Bundler.mkdir_p(bin_path)
+
       spec.executables.each do |executable|
         next if executable == "bundle"
         executable_path = Pathname(spec.full_gem_path).join(spec.bindir, executable).relative_path_from(bin_path)

data/lib/bundler/lazy_specification.rb

@@ -286,7 +286,7 @@ module Bundler
     # which would affect `bundler/setup` performance.
     def validate_dependencies(spec)
       if !@materialization_options[:strict] && spec.is_a?(StubSpecification)
-        spec.dependencies = dependencies
+        spec.dependencies = Override.rewrite_dependencies(overrides, name, dependencies)
       else
         if !source.is_a?(Source::Path) && spec.runtime_dependencies.sort != dependencies.sort
           raise IncorrectLockfileDependencies.new(self, spec.runtime_dependencies, dependencies)

data/lib/bundler/lockfile_generator.rb

@@ -19,6 +19,7 @@ module Bundler
       add_sources
       add_platforms
       add_dependencies
+      add_overrides
       add_content_addresses
       add_checksums
       add_locked_ruby_version
@@ -67,6 +68,11 @@ module Bundler
       end
     end
 
+    def add_overrides
+      overrides = definition.overrides_to_lock
+      add_section("OVERRIDES", overrides) unless overrides.empty?
+    end
+
     def add_content_addresses
       content_addresses = definition.resolve.filter_map do |spec|
         next unless Gem::ContentAddress.content_addressed?(spec, validate_ruby_abi: false)

data/lib/bundler/lockfile_parser.rb

@@ -36,12 +36,14 @@ module Bundler
       :bundler_version,
       :ruby_version,
       :checksums,
+      :overrides,
     )
 
     BUNDLED      = "BUNDLED WITH"
     DEPENDENCIES = "DEPENDENCIES"
     CHECKSUMS    = "CHECKSUMS"
     CONTENT_ADDRESSES = "CONTENT ADDRESSES"
+    OVERRIDES    = "OVERRIDES"
     PLATFORMS    = "PLATFORMS"
     RUBY         = "RUBY VERSION"
     GIT          = "GIT"
@@ -49,7 +51,7 @@ module Bundler
     PATH         = "PATH"
     PLUGIN       = "PLUGIN SOURCE"
     SPECS        = "  specs:"
-    OPTIONS      = /^  ([a-z]+): (.*)$/i
+    OPTIONS      = /^  ([a-z_]+): (.*)$/i
     SOURCE       = [GIT, GEM, PATH, PLUGIN].freeze
 
     SECTIONS_BY_VERSION_INTRODUCED = {
@@ -61,7 +63,11 @@ module Bundler
       Gem::Version.create("4.1.0") => [CONTENT_ADDRESSES].freeze,
     }.freeze
 
-    KNOWN_SECTIONS = SECTIONS_BY_VERSION_INTRODUCED.values.flatten!.freeze
+    # OVERRIDES is deliberately not in SECTIONS_BY_VERSION_INTRODUCED. Sections
+    # listed there are ignored when comparing a lockfile bundled with an older
+    # Bundler, so a lockfile still BUNDLED WITH 4.0 would never get its
+    # overrides recorded while the resolution stays the same.
+    KNOWN_SECTIONS = (SECTIONS_BY_VERSION_INTRODUCED.values.flatten + [OVERRIDES]).freeze
 
     ENVIRONMENT_VERSION_SECTIONS = [BUNDLED, RUBY].freeze
     deprecate_constant(:ENVIRONMENT_VERSION_SECTIONS)
@@ -104,6 +110,7 @@ module Bundler
       @dependencies = {}
       @parse_method = nil
       @specs        = {}
+      @overrides    = nil
       @lockfile_path = lockfile_path || begin
         SharedHelpers.relative_lockfile_path
       rescue GemfileNotFound
@@ -144,6 +151,9 @@ module Bundler
           @parse_method = :parse_checksum
         elsif line == CONTENT_ADDRESSES
           @parse_method = :parse_content_address
+        elsif line == OVERRIDES
+          @overrides = []
+          @parse_method = :parse_override
         elsif line == PLATFORMS
           @parse_method = :parse_platform
         elsif line == RUBY
@@ -270,6 +280,12 @@ module Bundler
       @dependencies[dep.name] = dep
     end
 
+    def parse_override(line)
+      raise ArgumentError, "invalid override in lockfile: #{line.inspect}" unless line.start_with?("  ") && line[2] != " "
+
+      @overrides << Override.from_lock(line[2..])
+    end
+
     def parse_checksum(line)
       return unless line =~ NAME_VERSION
 

data/lib/bundler/man/bundle-info.1

@@ -4,7 +4,7 @@
 .SH "NAME"
 \fBbundle\-info\fR \- Show information for the given gem in your bundle
 .SH "SYNOPSIS"
-\fBbundle info\fR [GEM_NAME] [\-\-path] [\-\-version]
+\fBbundle info\fR [GEM_NAME] [\-\-path] [\-\-version] [\-\-exact\-match]
 .SH "DESCRIPTION"
 Given a gem name present in your bundle, print the basic information about it such as homepage, version, path and summary\.
 .SH "OPTIONS"
@@ -14,4 +14,7 @@ Print the path of the given gem
 .TP
 \fB\-\-version\fR
 Print gem version
+.TP
+\fB\-\-exact\-match\fR
+Only match gems whose names exactly match the given name\.
 

data/lib/bundler/man/bundle-info.1.ronn

@@ -6,6 +6,7 @@ bundle-info(1) -- Show information for the given gem in your bundle
 `bundle info` [GEM_NAME]
               [--path]
               [--version]
+              [--exact-match]
 
 ## DESCRIPTION
 
@@ -19,3 +20,6 @@ Given a gem name present in your bundle, print the basic information about it
 
 * `--version`:
   Print gem version
+
+* `--exact-match`:
+  Only match gems whose names exactly match the given name.

data/lib/bundler/man/bundle-lock.1

@@ -13,7 +13,7 @@ Lock the gems specified in Gemfile\.
 Ignores the existing lockfile\. Resolve then updates lockfile\. Taking a list of gems or updating all gems if no list is given\.
 .TP
 \fB\-\-bundler[=BUNDLER]\fR
-Update the locked version of bundler to the given version or the latest version if no version is given\.
+Update the locked version of bundler\. BUNDLER can be a version such as \fB4\.0\.20\fR, or a requirement such as \fB"> 0\.a"\fR\. With no argument, update to the latest released version, which never selects a prerelease\.
 .TP
 \fB\-\-local\fR
 Do not attempt to connect to \fBrubygems\.org\fR\. Instead, Bundler will use the gems already present in Rubygems' cache or in \fBvendor/cache\fR\. Note that if a appropriate platform\-specific gem exists on \fBrubygems\.org\fR it will not be found\.
@@ -49,7 +49,7 @@ If updating, prefer updating only to next patch version\.
 If updating, prefer updating only to next minor version\.
 .TP
 \fB\-\-major\fR
-If updating, prefer updating to next major version (default)\.
+If updating, prefer updating to latest major version (default)\.
 .TP
 \fB\-\-pre\fR
 If updating, always choose the highest allowed version, regardless of prerelease status\.

data/lib/bundler/man/bundle-lock.1.ronn

@@ -33,8 +33,9 @@ Lock the gems specified in Gemfile.
   of gems or updating all gems if no list is given.
 
 * `--bundler[=BUNDLER]`:
-  Update the locked version of bundler to the given version or the latest
-  version if no version is given.
+  Update the locked version of bundler. BUNDLER can be a version such as
+  `4.0.20`, or a requirement such as `"> 0.a"`. With no argument, update to the
+  latest released version, which never selects a prerelease.
 
 * `--local`:
   Do not attempt to connect to `rubygems.org`. Instead, Bundler will use the
@@ -74,7 +75,7 @@ Lock the gems specified in Gemfile.
   If updating, prefer updating only to next minor version.
 
 * `--major`:
-  If updating, prefer updating to next major version (default).
+  If updating, prefer updating to latest major version (default).
 
 * `--pre`:
   If updating, always choose the highest allowed version, regardless of prerelease status.

data/lib/bundler/man/bundle-open.1

@@ -4,7 +4,7 @@
 .SH "NAME"
 \fBbundle\-open\fR \- Opens the source directory for a gem in your bundle
 .SH "SYNOPSIS"
-\fBbundle open\fR [GEM] [\-\-path=PATH]
+\fBbundle open\fR [GEM] [\-\-path=PATH] [\-\-exact\-match]
 .SH "DESCRIPTION"
 Opens the source directory of the provided GEM in your editor\.
 .P
@@ -29,4 +29,7 @@ Will open the README\.md file of the 'rack' gem source in your bundle\.
 .TP
 \fB\-\-path[=PATH]\fR
 Specify GEM source relative path to open\.
+.TP
+\fB\-\-exact\-match\fR
+Only match gems whose names exactly match the given name\.
 

data/lib/bundler/man/bundle-open.1.ronn

@@ -3,7 +3,7 @@ bundle-open(1) -- Opens the source directory for a gem in your bundle
 
 ## SYNOPSIS
 
-`bundle open` [GEM] [--path=PATH]
+`bundle open` [GEM] [--path=PATH] [--exact-match]
 
 ## DESCRIPTION
 
@@ -26,3 +26,6 @@ Will open the README.md file of the 'rack' gem source in your bundle.
 
 * `--path[=PATH]`:
   Specify GEM source relative path to open.
+
+* `--exact-match`:
+  Only match gems whose names exactly match the given name.

data/lib/bundler/man/bundle-outdated.1

@@ -37,7 +37,7 @@ List gems organized by groups\.
 Prefer updating only to next minor version\.
 .TP
 \fB\-\-major\fR
-Prefer updating to next major version (default)\.
+Prefer updating to latest major version (default)\.
 .TP
 \fB\-\-patch\fR
 Prefer updating only to next patch version\.

data/lib/bundler/man/bundle-outdated.1.ronn

@@ -55,7 +55,7 @@ are up to date, Bundler will exit with a status of 0. Otherwise, it will exit 1.
   Prefer updating only to next minor version.
 
 * `--major`:
-  Prefer updating to next major version (default).
+  Prefer updating to latest major version (default).
 
 * `--patch`:
   Prefer updating only to next patch version.

data/lib/bundler/man/bundle-show.1

@@ -4,7 +4,7 @@
 .SH "NAME"
 \fBbundle\-show\fR \- Shows all the gems in your bundle, or the path to a gem
 .SH "SYNOPSIS"
-\fBbundle show\fR [GEM] [\-\-paths]
+\fBbundle show\fR [GEM] [\-\-paths] [\-\-exact\-match]
 .SH "DESCRIPTION"
 Without the [GEM] option, \fBshow\fR will print a list of the names and versions of all gems that are required by your [\fBGemfile(5)\fR][Gemfile(5)], sorted by name\.
 .P
@@ -13,4 +13,7 @@ Calling show with [GEM] will list the exact location of that gem on your machine
 .TP
 \fB\-\-paths\fR
 List the paths of all gems that are required by your [\fBGemfile(5)\fR][Gemfile(5)], sorted by gem name\.
+.TP
+\fB\-\-exact\-match\fR
+Only match gems whose names exactly match the given name\.
 

data/lib/bundler/man/bundle-show.1.ronn

@@ -5,6 +5,7 @@ bundle-show(1) -- Shows all the gems in your bundle, or the path to a gem
 
 `bundle show` [GEM]
               [--paths]
+              [--exact-match]
 
 ## DESCRIPTION
 
@@ -19,3 +20,6 @@ machine.
 * `--paths`:
   List the paths of all gems that are required by your [`Gemfile(5)`][Gemfile(5)],
   sorted by gem name.
+
+* `--exact-match`:
+  Only match gems whose names exactly match the given name.

data/lib/bundler/man/bundle-update.1

@@ -27,7 +27,7 @@ Do not attempt to fetch gems remotely and use the gem cache instead\.
 Update the locked version of Ruby to the current version of Ruby\.
 .TP
 \fB\-\-bundler[=BUNDLER]\fR
-Update the locked version of bundler to the invoked bundler version\.
+Update the locked version of bundler\. BUNDLER can be a version such as \fB4\.0\.20\fR, or a requirement such as \fB"> 0\.a"\fR\. With no argument, update to the latest released version, which never selects a prerelease\.
 .TP
 \fB\-\-force\fR, \fB\-\-redownload\fR
 Force reinstalling every gem, even if already installed\.
@@ -54,7 +54,7 @@ Prefer updating only to next patch version\.
 Prefer updating only to next minor version\.
 .TP
 \fB\-\-major\fR
-Prefer updating to next major version (default)\.
+Prefer updating to latest major version (default)\.
 .TP
 \fB\-\-pre\fR
 Always choose the highest allowed version, regardless of prerelease status\.
@@ -175,7 +175,7 @@ Prefer updating only to next patch version\.
 Prefer updating only to next minor version\.
 .TP
 \fB\-\-major\fR
-Prefer updating to next major version (default)\.
+Prefer updating to latest major version (default)\.
 .TP
 \fB\-\-strict\fR
 Do not allow any gem to be updated past latest \fB\-\-patch\fR | \fB\-\-minor\fR | \fB\-\-major\fR\.

data/lib/bundler/man/bundle-update.1.ronn

@@ -53,7 +53,9 @@ gem.
   Update the locked version of Ruby to the current version of Ruby.
 
 * `--bundler[=BUNDLER]`:
-  Update the locked version of bundler to the invoked bundler version.
+  Update the locked version of bundler. BUNDLER can be a version such as
+  `4.0.20`, or a requirement such as `"> 0.a"`. With no argument, update to the
+  latest released version, which never selects a prerelease.
 
 * `--force`, `--redownload`:
   Force reinstalling every gem, even if already installed.
@@ -81,7 +83,7 @@ gem.
   Prefer updating only to next minor version.
 
 * `--major`:
-  Prefer updating to next major version (default).
+  Prefer updating to latest major version (default).
 
 * `--pre`:
   Always choose the highest allowed version, regardless of prerelease status.
@@ -236,7 +238,7 @@ versions are resolved. One of the following options can be used: `--patch`,
   Prefer updating only to next minor version.
 
 * `--major`:
-  Prefer updating to next major version (default).
+  Prefer updating to latest major version (default).
 
 * `--strict`:
   Do not allow any gem to be updated past latest `--patch` | `--minor` | `--major`.

data/lib/bundler/man/gemfile.5

@@ -295,6 +295,13 @@ gem "rails", git: "https://github\.com/rails/rails\.git", ref: "4aded"
 .TP
 \fBsubmodules\fR
 For reference, a git submodule \fIhttps://git\-scm\.com/book/en/v2/Git\-Tools\-Submodules\fR lets you have another git repository within a subfolder of your repository\. Specify \fBsubmodules: true\fR to cause bundler to expand any submodules included in the git repository
+.TP
+\fBsparse_checkout\fR
+Specify a directory, or an array of directories, to include when checking out a git repository\. Uses git's sparse\-checkout feature (requires git 2\.25+) to only check out the specified directories, reducing disk usage for large repos\. Unless \fBglob\fR is given, the \fB\.gemspec\fR is looked up within those directories\.
+.IP
+gem "foo", git: "https://github\.com/org/monorepo\.git", sparse_checkout: "packages/foo"
+.IP
+Files at the top level of the repository are always checked out\. On git versions below 2\.25, the entire repository will be checked out with a warning\.
 .P
 If a git repository contains multiple \fB\.gemspecs\fR, each \fB\.gemspec\fR represents a gem located at the same place in the file system as the \fB\.gemspec\fR\.
 .IP "" 4
@@ -490,7 +497,7 @@ a version requirement string (e\.g\. \fB">= 8\.0"\fR), which \fBreplaces\fR the
 .P
 \fB:all\fR only applies to \fBrequired_ruby_version:\fR and \fBrequired_rubygems_version:\fR\. A per\-gem override on the same field takes precedence over an \fB:all\fR override\. \fB:all + version:\fR is rejected: version requirements only make sense per gem\.
 .P
-Multiple \fBoverride\fR calls for distinct targets are allowed; declaring the same \fBtarget\fR and \fBfield\fR twice is an error\.
+Declaring the same \fBtarget\fR and \fBfield\fR twice is an error\.
 .IP "" 4
 .nf
 source "https://rubygems\.org"
@@ -514,7 +521,41 @@ gem "rails", "~> 7\.0"
 .fi
 .IP "" 0
 .P
-The override only affects resolution and the install\-time Ruby/RubyGems compatibility checks; \fBGemfile\.lock\fR continues to reflect the resolved versions, not the rewritten requirements\. When resolution still fails, Bundler appends the active overrides (with their Gemfile location) to the error message so it is clear which override shaped the constraint set\.
+The override only affects resolution and the install\-time Ruby/RubyGems compatibility checks; the gems in \fBGemfile\.lock\fR continue to reflect the resolved versions, not the rewritten requirements\. The overrides themselves are recorded in the lockfile's \fBOVERRIDES\fR section, one line per field, sorted:
+.IP "" 4
+.nf
+OVERRIDES
+  "rails", version: ">= 8\.0"
+  :all, required_ruby_version: :ignore_upper
+.fi
+.IP "" 0
+.P
+Requirements are recorded in normalized form, so \fB">=8\.0"\fR and \fB">= 8\.0"\fR are the same override\. A frozen install fails when the Gemfile's overrides differ from the recorded ones\. Adding or removing a \fB:all\fR or metadata override rewrites the section and keeps the locked versions\. The exception is a locked gem that is not installed and whose metadata rejects the current Ruby\. Bundler re\-resolves it, as it does without the override\. Run \fBbundle update\fR to re\-resolve under the override\. When resolution still fails, Bundler appends the active overrides (with their Gemfile location) to the error message so it is clear which override shaped the constraint set\.
+.SS "DROPPING OR REPLACING A DEPENDENCY"
+\fBwith:\fR and \fBin:\fR rewrite a single dependency of a single gem:
+.IP "" 4
+.nf
+override <target>, with: nil, in: <gem>
+override <target>, with: <replacement>, in: <gem>, version: <requirement>
+.fi
+.IP "" 0
+.P
+\fBwith: nil\fR removes the dependency of \fB<gem>\fR on \fB<target>\fR, so \fB<target>\fR is not installed unless something else still requires it\. \fBwith: <replacement>\fR makes \fB<gem>\fR depend on \fB<replacement>\fR instead of \fB<target>\fR\. The requirement \fB<gem>\fR put on \fB<target>\fR is discarded, and the optional \fBversion:\fR gives the replacement its own\. Both forms apply whether \fB<gem>\fR is a direct or a transitive dependency\.
+.P
+\fBin:\fR is required, and so is \fBwith:\fR once \fBin:\fR is given\. To rewrite the same dependency of several gems, write one \fBoverride\fR per gem\. It is an error to declare the same \fB<target>\fR and \fBin:\fR twice, to drop a gem that the Gemfile requires directly, or to replace a gem that another gem still requires, since both would then be in the bundle\.
+.IP "" 4
+.nf
+# jekyll only loads em\-websocket for `jekyll serve \-\-livereload`\.
+override "em\-websocket", with: nil, in: "jekyll"
+
+# Use an API\-compatible gem that provides the same files\.
+override "foo", with: "foo\-lite", in: "bar"
+.fi
+.IP "" 0
+.P
+Bundler does not check what a gem loads at runtime\. If \fB<gem>\fR requires \fB<target>\fR unconditionally, dropping it makes that require raise \fBLoadError\fR, as with jekyll's dependency on jekyll\-sass\-converter or the adapters that faraday 1\.x requires on load\. A replacement only works when it provides the files \fB<gem>\fR requires, and it does not take over the name of \fB<target>\fR: \fBGem\.loaded_specs\fR has no entry for \fB<target>\fR, and \fBgem "<target>"\fR fails\.
+.P
+\fBGemfile\.lock\fR keeps listing \fB<target>\fR under \fB<gem>\fR as the gem publishes it, while the locked gems leave \fB<target>\fR out or include \fB<replacement>\fR, and the \fBOVERRIDES\fR section records the rewrite so tools that read the lockfile can apply it\. A frozen install accepts that lockfile as long as the Gemfile still has the override\. Removing the override makes Bundler resolve \fB<target>\fR again\.
 .SH "SOURCE PRIORITY"
 When attempting to locate a gem to satisfy a gem requirement, bundler uses the following priority order:
 .IP "1." 4