bundler 2.5.17 → 2.5.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 60cb5ee8526a6f8eb3c413e7d3d2ae8c9b32315685862943fc2a956f2fdcd5a1
-  data.tar.gz: 52aa4c3a435ed97c8dbc2adcfa51dc6d2113fefcb5020df0a5b0be3b605cc49f
+  metadata.gz: cf59bff2285c5f99b1db1fbb57d3c372624ccc17fd68d8267d00d95739edbfda
+  data.tar.gz: 5bd1a4207b31f2437da59356cdae6f2c2999842af730d866ec8799f6b6c8f589
 SHA512:
-  metadata.gz: afafe4e932d1840de3938e609f45555b1fbdf3fea481ee6d395a1f1458d579606d2f5ac64edc90d74799d9b117aae3fd1028b6d3a660df97e087bb9f6475d583
-  data.tar.gz: fd8907298e40c98124857ea7bf2594953d962946b66da695ce929db2623e67dacbee7dec6500a3dfb89cb6308377a26c305a25cd28a7083432ec10baf0d59810
+  metadata.gz: e6d98b6893658ee4fca7b7bc633d73e48d88c736c55eb6bf807f9d37c1fce3975d965aa08d5b9b03f5b1b8ce1a84028b78a6510620c8936e7bcd86655ed983da
+  data.tar.gz: f1edc568d88a5f2dcc82f5c6d74fe418e3ee186ef592b56df315b1678a0f60788bebd1c10f2bc2c463d85c5a050d0a959c956bacf8fffa62c55e73f9b8ee789c

data/CHANGELOG.md

@@ -1,3 +1,49 @@
+# 2.5.19 (September 18, 2024)
+
+## Enhancements:
+
+  - Raise original errors when unexpected errors happen during Gemfile evaluation [#8003](https://github.com/rubygems/rubygems/pull/8003)
+  - Make an exe file executable when generating new gems [#8020](https://github.com/rubygems/rubygems/pull/8020)
+  - Gracefully handle gem activation conflicts in inline mode [#5535](https://github.com/rubygems/rubygems/pull/5535)
+  - Don't include hook templates in cached git source [#8013](https://github.com/rubygems/rubygems/pull/8013)
+  - Fix some errors about a previous installation folder that's unsafe to remove, when there's no need to remove it [#7985](https://github.com/rubygems/rubygems/pull/7985)
+  - Emit progress to stderr during `bundle outdated --parseable` [#7966](https://github.com/rubygems/rubygems/pull/7966)
+  - Reject unknown platforms when running `bundle lock --add-platform` [#7967](https://github.com/rubygems/rubygems/pull/7967)
+  - Emit progress to stderr when `--print` is passed to `bundle lock` [#7957](https://github.com/rubygems/rubygems/pull/7957)
+
+## Bug fixes:
+
+  - Fix `bundle install --local` hitting the network when default gems are included [#8027](https://github.com/rubygems/rubygems/pull/8027)
+  - Remove temporary `.lock` files unintentionally left around by gem installer [#8022](https://github.com/rubygems/rubygems/pull/8022)
+  - Fix `bundle exec rake install` failing when local gem has extensions [#7977](https://github.com/rubygems/rubygems/pull/7977)
+  - Load gemspecs in the context of its parent also when using local overrides [#7993](https://github.com/rubygems/rubygems/pull/7993)
+  - Fix `bundler/inline` failing in Ruby 3.2 due to conflicting `securerandom` versions [#7984](https://github.com/rubygems/rubygems/pull/7984)
+  - Don't blow up when explicit version is removed from some git sources [#7973](https://github.com/rubygems/rubygems/pull/7973)
+  - Fix `gem exec rails new project` failing on Ruby 3.2 [#7960](https://github.com/rubygems/rubygems/pull/7960)
+
+## Documentation:
+
+  - Improve `bundle add` man page [#5903](https://github.com/rubygems/rubygems/pull/5903)
+  - Add some documentation about backwards compatibility [#7964](https://github.com/rubygems/rubygems/pull/7964)
+
+# 2.5.18 (August 26, 2024)
+
+## Enhancements:
+
+  - Don't remove existing platform gems when PLATFORMS section is badly indented [#7916](https://github.com/rubygems/rubygems/pull/7916)
+
+## Bug fixes:
+
+  - Fix error message when Bundler refuses to install due to frozen being set without a lockfile [#7955](https://github.com/rubygems/rubygems/pull/7955)
+  - Fix several issues with the `--prefer-local` flag [#7951](https://github.com/rubygems/rubygems/pull/7951)
+  - Restore support for passing relative paths to `git:` sources [#7950](https://github.com/rubygems/rubygems/pull/7950)
+  - Regenerate previous git application caches that didn't include bare repos [#7926](https://github.com/rubygems/rubygems/pull/7926)
+  - Fix `bundle update <indirect_dep>` failing to upgrade when versions present in two different sources [#7915](https://github.com/rubygems/rubygems/pull/7915)
+
+## Documentation:
+
+  - Change new gem README template to have copyable code blocks [#7935](https://github.com/rubygems/rubygems/pull/7935)
+
 # 2.5.17 (August 1, 2024)
 
 ## Enhancements:

data/lib/bundler/build_metadata.rb

@@ -4,8 +4,8 @@ module Bundler
   # Represents metadata from when the Bundler gem was built.
   module BuildMetadata
     # begin ivars
-    @built_at = "2024-08-01".freeze
-    @git_commit_sha = "74d92b2502".freeze
+    @built_at = "2024-09-18".freeze
+    @git_commit_sha = "d569990361".freeze
     @release = true
     # end ivars
 

data/lib/bundler/cli/add.rb

@@ -34,7 +34,7 @@ module Bundler
     end
 
     def validate_options!
-      raise InvalidOption, "You can not specify `--strict` and `--optimistic` at the same time." if options[:strict] && options[:optimistic]
+      raise InvalidOption, "You cannot specify `--strict` and `--optimistic` at the same time." if options[:strict] && options[:optimistic]
 
       # raise error when no gems are specified
       raise InvalidOption, "Please specify gems to add." if gems.empty?

data/lib/bundler/cli/gem.rb

@@ -191,7 +191,10 @@ module Bundler
         templates.merge!("standard.yml.tt" => ".standard.yml")
       end
 
-      templates.merge!("exe/newgem.tt" => "exe/#{name}") if config[:exe]
+      if config[:exe]
+        templates.merge!("exe/newgem.tt" => "exe/#{name}")
+        executables.push("exe/#{name}")
+      end
 
       if extension == "c"
         templates.merge!(

data/lib/bundler/cli/install.rb

@@ -25,9 +25,10 @@ module Bundler
 
       if options[:deployment] || options[:frozen] || Bundler.frozen_bundle?
         unless Bundler.default_lockfile.exist?
-          flag   = "--deployment flag" if options[:deployment]
-          flag ||= "--frozen flag"     if options[:frozen]
-          flag ||= "deployment setting"
+          flag = "--deployment flag" if options[:deployment]
+          flag ||= "--frozen flag" if options[:frozen]
+          flag ||= "deployment setting" if Bundler.settings[:deployment]
+          flag ||= "frozen setting" if Bundler.settings[:frozen]
           raise ProductionError, "The #{flag} requires a lockfile. Please make " \
                                  "sure you have checked your #{SharedHelpers.relative_lockfile_path} into version control " \
                                  "before deploying."

data/lib/bundler/cli/lock.rb

@@ -15,8 +15,8 @@ module Bundler
       end
 
       print = options[:print]
-      previous_ui_level = Bundler.ui.level
-      Bundler.ui.level = "silent" if print
+      previous_output_stream = Bundler.ui.output_stream
+      Bundler.ui.output_stream = :stderr if print
 
       Bundler::Fetcher.disable_endpoint = options["full-index"]
 
@@ -48,8 +48,8 @@ module Bundler
         options["add-platform"].each do |platform_string|
           platform = Gem::Platform.new(platform_string)
           if platform.to_s == "unknown"
-            Bundler.ui.warn "The platform `#{platform_string}` is unknown to RubyGems " \
-              "and adding it will likely lead to resolution errors"
+            Bundler.ui.error "The platform `#{platform_string}` is unknown to RubyGems and can't be added to the lockfile."
+            exit 1
           end
           definition.add_platform(platform)
         end
@@ -68,7 +68,7 @@ module Bundler
         end
       end
 
-      Bundler.ui.level = previous_ui_level
+      Bundler.ui.output_stream = previous_output_stream
     end
   end
 end

data/lib/bundler/cli/outdated.rb

@@ -54,7 +54,7 @@ module Bundler
       end
 
       if options[:parseable]
-        Bundler.ui.silence(&definition_resolution)
+        Bundler.ui.progress(&definition_resolution)
       else
         definition_resolution.call
       end

data/lib/bundler/definition.rb

@@ -214,6 +214,7 @@ module Bundler
       @resolve = nil
       @resolver = nil
       @resolution_packages = nil
+      @source_requirements = nil
       @specs = nil
 
       Bundler.ui.debug "The definition is missing dependencies, failed to resolve & materialize locally (#{e})"
@@ -476,9 +477,6 @@ module Bundler
       end
     end
 
-    attr_reader :sources
-    private :sources
-
     def nothing_changed?
       return false unless lockfile_exists?
 
@@ -502,22 +500,22 @@ module Bundler
       @unlocking
     end
 
+    attr_writer :source_requirements
+
     private
 
+    attr_reader :sources
+
     def should_add_extra_platforms?
       !lockfile_exists? && generic_local_platform_is_ruby? && !Bundler.settings[:force_ruby_platform]
     end
 
     def lockfile_exists?
-      file_exists?(lockfile)
-    end
-
-    def file_exists?(file)
-      file && File.exist?(file)
+      lockfile && File.exist?(lockfile)
     end
 
     def write_lock(file, preserve_unknown_sections)
-      return if Definition.no_lock
+      return if Definition.no_lock || file.nil?
 
       contents = to_lock
 
@@ -534,7 +532,7 @@ module Bundler
 
       preserve_unknown_sections ||= !updating_major && (Bundler.frozen_bundle? || !(unlocking? || @unlocking_bundler))
 
-      if file_exists?(file) && lockfiles_equal?(@lockfile_contents, contents, preserve_unknown_sections)
+      if File.exist?(file) && lockfiles_equal?(@lockfile_contents, contents, preserve_unknown_sections)
         return if Bundler.frozen_bundle?
         SharedHelpers.filesystem_access(file) { FileUtils.touch(file) }
         return
@@ -569,7 +567,7 @@ module Bundler
       @resolution_packages ||= begin
         last_resolve = converge_locked_specs
         remove_invalid_platforms!
-        packages = Resolver::Base.new(source_requirements, expanded_dependencies, last_resolve, @platforms, locked_specs: @originally_locked_specs, unlock: @gems_to_unlock, prerelease: gem_version_promoter.pre?)
+        packages = Resolver::Base.new(source_requirements, expanded_dependencies, last_resolve, @platforms, locked_specs: @originally_locked_specs, unlock: @gems_to_unlock, prerelease: gem_version_promoter.pre?, prefer_local: @prefer_local)
         packages = additional_base_requirements_to_prevent_downgrades(packages, last_resolve)
         packages = additional_base_requirements_to_force_updates(packages)
         packages
@@ -653,19 +651,6 @@ module Bundler
       sources.non_global_rubygems_sources.all?(&:dependency_api_available?) && !sources.aggregate_global_source?
     end
 
-    def pin_locally_available_names(source_requirements)
-      source_requirements.each_with_object({}) do |(name, original_source), new_source_requirements|
-        local_source = original_source.dup
-        local_source.local_only!
-
-        new_source_requirements[name] = if local_source.specs.search(name).any?
-          local_source
-        else
-          original_source
-        end
-      end
-    end
-
     def current_platform_locked?
       @platforms.any? do |bundle_platform|
         MatchPlatform.platforms_match?(bundle_platform, local_platform)
@@ -972,12 +957,15 @@ module Bundler
     end
 
     def source_requirements
+      @source_requirements ||= find_source_requirements
+    end
+
+    def find_source_requirements
       # Record the specs available in each gem's source, so that those
       # specs will be available later when the resolver knows where to
       # look for that gemspec (or its dependencies)
       source_requirements = if precompute_source_requirements_for_indirect_dependencies?
         all_requirements = source_map.all_requirements
-        all_requirements = pin_locally_available_names(all_requirements) if @prefer_local
         { default: default_source }.merge(all_requirements)
       else
         { default: Source::RubygemsAggregate.new(sources, source_map) }.merge(source_map.direct_requirements)
@@ -1053,6 +1041,7 @@ module Bundler
 
     def dup_for_full_unlock
       unlocked_definition = self.class.new(@lockfile, @dependencies, @sources, true, @ruby_version, @optional_groups, @gemfiles)
+      unlocked_definition.source_requirements = source_requirements
       unlocked_definition.gem_version_promoter.tap do |gvp|
         gvp.level = gem_version_promoter.level
         gvp.strict = gem_version_promoter.strict

data/lib/bundler/dsl.rb

@@ -42,20 +42,20 @@ module Bundler
     end
 
     def eval_gemfile(gemfile, contents = nil)
-      expanded_gemfile_path = Pathname.new(gemfile).expand_path(@gemfile&.parent)
-      original_gemfile = @gemfile
-      @gemfile = expanded_gemfile_path
-      @gemfiles << expanded_gemfile_path
-      contents ||= Bundler.read_file(@gemfile.to_s)
-      instance_eval(contents, @gemfile.to_s, 1)
-    rescue Exception => e # rubocop:disable Lint/RescueException
-      message = "There was an error " \
-        "#{e.is_a?(GemfileEvalError) ? "evaluating" : "parsing"} " \
-        "`#{File.basename gemfile.to_s}`: #{e.message}"
-
-      raise DSLError.new(message, gemfile, e.backtrace, contents)
-    ensure
-      @gemfile = original_gemfile
+      with_gemfile(gemfile) do |current_gemfile|
+        contents ||= Bundler.read_file(current_gemfile)
+        instance_eval(contents, current_gemfile, 1)
+      rescue GemfileEvalError => e
+        message = "There was an error evaluating `#{File.basename current_gemfile}`: #{e.message}"
+        raise DSLError.new(message, current_gemfile, e.backtrace, contents)
+      rescue GemfileError, InvalidArgumentError, InvalidOption, DeprecatedError, ScriptError => e
+        message = "There was an error parsing `#{File.basename current_gemfile}`: #{e.message}"
+        raise DSLError.new(message, current_gemfile, e.backtrace, contents)
+      rescue StandardError => e
+        raise unless e.backtrace_locations.first.path == current_gemfile
+        message = "There was an error parsing `#{File.basename current_gemfile}`: #{e.message}"
+        raise DSLError.new(message, current_gemfile, e.backtrace, contents)
+      end
     end
 
     def gemspec(opts = nil)
@@ -219,7 +219,7 @@ module Bundler
     end
 
     def github(repo, options = {})
-      raise ArgumentError, "GitHub sources require a block" unless block_given?
+      raise InvalidArgumentError, "GitHub sources require a block" unless block_given?
       github_uri  = @git_sources["github"].call(repo)
       git_options = normalize_hash(options).merge("uri" => github_uri)
       git_source  = @sources.add_git_source(git_options)
@@ -285,6 +285,16 @@ module Bundler
 
     private
 
+    def with_gemfile(gemfile)
+      expanded_gemfile_path = Pathname.new(gemfile).expand_path(@gemfile&.parent)
+      original_gemfile = @gemfile
+      @gemfile = expanded_gemfile_path
+      @gemfiles << expanded_gemfile_path
+      yield @gemfile.to_s
+    ensure
+      @gemfile = original_gemfile
+    end
+
     def add_git_sources
       git_source(:github) do |repo_name|
         if repo_name =~ GITHUB_PULL_REQUEST_URL
@@ -577,7 +587,7 @@ module Bundler
 
           return m unless backtrace && dsl_path && contents
 
-          trace_line = backtrace.find {|l| l.include?(dsl_path.to_s) } || trace_line
+          trace_line = backtrace.find {|l| l.include?(dsl_path) } || trace_line
           return m unless trace_line
           line_numer = trace_line.split(":")[1].to_i - 1
           return m unless line_numer
@@ -603,7 +613,7 @@ module Bundler
 
       def parse_line_number_from_description
         description = self.description
-        if dsl_path && description =~ /((#{Regexp.quote File.expand_path(dsl_path)}|#{Regexp.quote dsl_path.to_s}):\d+)/
+        if dsl_path && description =~ /((#{Regexp.quote File.expand_path(dsl_path)}|#{Regexp.quote dsl_path}):\d+)/
           trace_line = Regexp.last_match[1]
           description = description.sub(/\n.*\n(\.\.\.)? *\^~+$/, "").sub(/#{Regexp.quote trace_line}:\s*/, "").sub("\n", " - ")
         end

data/lib/bundler/errors.rb

@@ -217,15 +217,15 @@ module Bundler
   end
 
   class InsecureInstallPathError < BundlerError
-    def initialize(path)
+    def initialize(name, path)
+      @name = name
       @path = path
     end
 
     def message
-      "The installation path is insecure. Bundler cannot continue.\n" \
-      "#{@path} is world-writable (without sticky bit).\n" \
-      "Bundler cannot safely replace gems in world-writeable directories due to potential vulnerabilities.\n" \
-      "Please change the permissions of this directory or choose a different install path."
+      "Bundler cannot reinstall #{@name} because there's a previous installation of it at #{@path} that is unsafe to remove.\n" \
+      "The parent of #{@path} is world-writable and does not have the sticky bit set, making it insecure to remove due to potential vulnerabilities.\n" \
+      "Please change the permissions of #{File.dirname(@path)} or choose a different install path."
     end
 
     status_code(38)
@@ -244,4 +244,6 @@ module Bundler
 
     status_code(39)
   end
+
+  class InvalidArgumentError < BundlerError; status_code(40); end
 end

data/lib/bundler/fetcher.rb

@@ -3,7 +3,7 @@
 require_relative "vendored_persistent"
 require_relative "vendored_timeout"
 require "cgi"
-require "securerandom"
+require_relative "vendored_securerandom"
 require "zlib"
 
 module Bundler
@@ -182,7 +182,7 @@ module Bundler
         agent << " ci/#{cis.join(",")}" if cis.any?
 
         # add a random ID so we can consolidate runs server-side
-        agent << " " << SecureRandom.hex(8)
+        agent << " " << Gem::SecureRandom.hex(8)
 
         # add any user agent strings set in the config
         extra_ua = Bundler.settings[:user_agent]

data/lib/bundler/inline.rb

@@ -46,11 +46,9 @@ def gemfile(install = false, options = {}, &gemfile)
     Bundler::Plugin.gemfile_install(&gemfile) if Bundler.feature_flag.plugins?
     builder = Bundler::Dsl.new
     builder.instance_eval(&gemfile)
-    builder.check_primary_source_safety
 
     Bundler.settings.temporary(deployment: false, frozen: false) do
       definition = builder.to_definition(nil, true)
-      def definition.lock(*); end
       definition.validate_runtime!
 
       if install || definition.missing_specs?
@@ -62,8 +60,25 @@ def gemfile(install = false, options = {}, &gemfile)
         end
       end
 
-      runtime = Bundler::Runtime.new(nil, definition)
-      runtime.setup.require
+      begin
+        runtime = Bundler::Runtime.new(nil, definition).setup
+      rescue Gem::LoadError => e
+        name = e.name
+        version = e.requirement.requirements.first[1]
+        activated_version = Gem.loaded_specs[name].version
+
+        Bundler.ui.info \
+          "The #{name} gem was resolved to #{version}, but #{activated_version} was activated by Bundler while installing it, causing a conflict. " \
+          "Bundler will now retry resolving with #{activated_version} instead."
+
+        builder.dependencies.delete_if {|d| d.name == name }
+        builder.instance_eval { gem name, activated_version }
+        definition = builder.to_definition(nil, true)
+
+        retry
+      end
+
+      runtime.require
     end
   end
 

data/lib/bundler/installer/gem_installer.rb

@@ -2,14 +2,15 @@
 
 module Bundler
   class GemInstaller
-    attr_reader :spec, :standalone, :worker, :force, :installer
+    attr_reader :spec, :standalone, :worker, :force, :local, :installer
 
-    def initialize(spec, installer, standalone = false, worker = 0, force = false)
+    def initialize(spec, installer, standalone = false, worker = 0, force = false, local = false)
       @spec = spec
       @installer = installer
       @standalone = standalone
       @worker = worker
       @force = force
+      @local = local
     end
 
     def install_from_spec
@@ -54,6 +55,7 @@ module Bundler
       spec.source.install(
         spec,
         force: force,
+        local: local,
         build_args: Array(spec_settings),
         previous_spec: previous_spec,
       )

data/lib/bundler/installer/parallel_installer.rb

@@ -68,11 +68,12 @@ module Bundler
 
     attr_reader :size
 
-    def initialize(installer, all_specs, size, standalone, force, skip: nil)
+    def initialize(installer, all_specs, size, standalone, force, local: false, skip: nil)
       @installer = installer
       @size = size
       @standalone = standalone
       @force = force
+      @local = local
       @specs = all_specs.map {|s| SpecInstallation.new(s) }
       @specs.each do |spec_install|
         spec_install.state = :installed if skip.include?(spec_install.name)
@@ -127,7 +128,7 @@ module Bundler
     def do_install(spec_install, worker_num)
       Plugin.hook(Plugin::Events::GEM_BEFORE_INSTALL, spec_install)
       gem_installer = Bundler::GemInstaller.new(
-        spec_install.spec, @installer, @standalone, worker_num, @force
+        spec_install.spec, @installer, @standalone, worker_num, @force, @local
       )
       success, message = gem_installer.install_from_spec
       if success

data/lib/bundler/installer.rb

@@ -194,9 +194,14 @@ module Bundler
     # that said, it's a rare situation (other than rake), and parallel
     # installation is SO MUCH FASTER. so we let people opt in.
     def install(options)
-      force = options["force"]
+      standalone = options[:standalone]
+      force = options[:force]
+      local = options[:local]
       jobs = installation_parallelization(options)
-      install_in_parallel jobs, options[:standalone], force
+      spec_installations = ParallelInstaller.call(self, @definition.specs, jobs, standalone, force, local: local)
+      spec_installations.each do |installation|
+        post_install_messages[installation.name] = installation.post_install_message if installation.has_post_install_message?
+      end
     end
 
     def installation_parallelization(options)
@@ -238,18 +243,11 @@ module Bundler
       end
     end
 
-    def install_in_parallel(size, standalone, force = false)
-      spec_installations = ParallelInstaller.call(self, @definition.specs, size, standalone, force)
-      spec_installations.each do |installation|
-        post_install_messages[installation.name] = installation.post_install_message if installation.has_post_install_message?
-      end
-    end
-
     # returns whether or not a re-resolve was needed
     def resolve_if_needed(options)
-      @definition.prefer_local! if options["prefer-local"]
+      @definition.prefer_local! if options[:"prefer-local"]
 
-      if options["local"] || (@definition.no_resolve_needed? && !@definition.missing_specs?)
+      if options[:local] || (@definition.no_resolve_needed? && !@definition.missing_specs?)
         @definition.resolve_with_cache!
         false
       else

data/lib/bundler/lockfile_parser.rb

@@ -272,7 +272,7 @@ module Bundler
     end
 
     def parse_platform(line)
-      @platforms << Gem::Platform.new($1) if line =~ /^  (.*)$/
+      @platforms << Gem::Platform.new($1.strip) if line =~ /^  (.*)$/
     end
 
     def parse_bundled_with(line)

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

@@ -1,24 +1,12 @@
 .\" generated with nRonn/v0.11.1
 .\" https://github.com/n-ronn/nronn/tree/0.11.1
-.TH "BUNDLE\-ADD" "1" "June 2024" ""
+.TH "BUNDLE\-ADD" "1" "September 2024" ""
 .SH "NAME"
 \fBbundle\-add\fR \- Add gem to the Gemfile and run bundle install
 .SH "SYNOPSIS"
-\fBbundle add\fR \fIGEM_NAME\fR [\-\-group=GROUP] [\-\-version=VERSION] [\-\-source=SOURCE] [\-\-path=PATH] [\-\-git=GIT] [\-\-github=GITHUB] [\-\-branch=BRANCH] [\-\-ref=REF] [\-\-skip\-install] [\-\-strict] [\-\-optimistic]
+\fBbundle add\fR \fIGEM_NAME\fR [\-\-group=GROUP] [\-\-version=VERSION] [\-\-source=SOURCE] [\-\-path=PATH] [\-\-git=GIT|\-\-github=GITHUB] [\-\-branch=BRANCH] [\-\-ref=REF] [\-\-skip\-install] [\-\-strict|\-\-optimistic]
 .SH "DESCRIPTION"
-Adds the named gem to the Gemfile and run \fBbundle install\fR\. \fBbundle install\fR can be avoided by using the flag \fB\-\-skip\-install\fR\.
-.P
-Example:
-.P
-bundle add rails
-.P
-bundle add rails \-\-version "< 3\.0, > 1\.1"
-.P
-bundle add rails \-\-version "~> 5\.0\.0" \-\-source "https://gems\.example\.com" \-\-group "development"
-.P
-bundle add rails \-\-skip\-install
-.P
-bundle add rails \-\-group "development, test"
+Adds the named gem to the [\fBGemfile(5)\fR][Gemfile(5)] and run \fBbundle install\fR\. \fBbundle install\fR can be avoided by using the flag \fB\-\-skip\-install\fR\.
 .SH "OPTIONS"
 .TP
 \fB\-\-version\fR, \fB\-v\fR
@@ -56,4 +44,27 @@ Adds optimistic declaration of version\.
 .TP
 \fB\-\-strict\fR
 Adds strict declaration of version\.
-
+.SH "EXAMPLES"
+.IP "1." 4
+You can add the \fBrails\fR gem to the Gemfile without any version restriction\. The source of the gem will be the global source\.
+.IP
+\fBbundle add rails\fR
+.IP "2." 4
+You can add the \fBrails\fR gem with version greater than 1\.1 (not including 1\.1) and less than 3\.0\.
+.IP
+\fBbundle add rails \-\-version "> 1\.1, < 3\.0"\fR
+.IP "3." 4
+You can use the \fBhttps://gems\.example\.com\fR custom source and assign the gem to a group\.
+.IP
+\fBbundle add rails \-\-version "~> 5\.0\.0" \-\-source "https://gems\.example\.com" \-\-group "development"\fR
+.IP "4." 4
+The following adds the \fBgem\fR entry to the Gemfile without installing the gem\. You can install gems later via \fBbundle install\fR\.
+.IP
+\fBbundle add rails \-\-skip\-install\fR
+.IP "5." 4
+You can assign the gem to more than one group\.
+.IP
+\fBbundle add rails \-\-group "development, test"\fR
+.IP "" 0
+.SH "SEE ALSO"
+Gemfile(5) \fIhttps://bundler\.io/man/gemfile\.5\.html\fR, bundle\-remove(1) \fIbundle\-remove\.1\.html\fR

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

@@ -1,26 +1,19 @@
 bundle-add(1) -- Add gem to the Gemfile and run bundle install
-================================================================
+==============================================================
 
 ## SYNOPSIS
 
-`bundle add` <GEM_NAME> [--group=GROUP] [--version=VERSION] [--source=SOURCE] [--path=PATH] [--git=GIT] [--github=GITHUB] [--branch=BRANCH] [--ref=REF] [--skip-install] [--strict] [--optimistic]
+`bundle add` <GEM_NAME> [--group=GROUP] [--version=VERSION] [--source=SOURCE]
+           [--path=PATH] [--git=GIT|--github=GITHUB] [--branch=BRANCH] [--ref=REF]
+           [--skip-install] [--strict|--optimistic]
 
 ## DESCRIPTION
-Adds the named gem to the Gemfile and run `bundle install`. `bundle install` can be avoided by using the flag `--skip-install`.
 
-Example:
-
-bundle add rails
-
-bundle add rails --version "< 3.0, > 1.1"
-
-bundle add rails --version "~> 5.0.0" --source "https://gems.example.com" --group "development"
-
-bundle add rails --skip-install
-
-bundle add rails --group "development, test"
+Adds the named gem to the [`Gemfile(5)`][Gemfile(5)] and run `bundle install`.
+`bundle install` can be avoided by using the flag `--skip-install`.
 
 ## OPTIONS
+
 * `--version`, `-v`:
   Specify version requirements(s) for the added gem.
 
@@ -56,3 +49,33 @@ bundle add rails --group "development, test"
 
 * `--strict`:
   Adds strict declaration of version.
+
+## EXAMPLES
+
+1. You can add the `rails` gem to the Gemfile without any version restriction.
+   The source of the gem will be the global source.
+
+   `bundle add rails`
+
+2. You can add the `rails` gem with version greater than 1.1 (not including 1.1) and less than 3.0.
+
+   `bundle add rails --version "> 1.1, < 3.0"`
+
+3. You can use the `https://gems.example.com` custom source and assign the gem
+   to a group.
+
+   `bundle add rails --version "~> 5.0.0" --source "https://gems.example.com" --group "development"`
+
+4. The following adds the `gem` entry to the Gemfile without installing the
+   gem. You can install gems later via `bundle install`.
+
+   `bundle add rails --skip-install`
+
+5. You can assign the gem to more than one group.
+
+   `bundle add rails --group "development, test"`
+
+## SEE ALSO
+
+[Gemfile(5)](https://bundler.io/man/gemfile.5.html),
+[bundle-remove(1)](bundle-remove.1.html)