Merge pull request #9305 from ruby/add-doc-for-local-config

Clarify local gem override docs to require git-sourced gems

(cherry picked from commit d0f6a30)

Author: hsbt

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

@@ -1,6 +1,6 @@
 .\" generated with Ronn-NG/v0.10.1
 .\" http://github.com/apjanke/ronn-ng/tree/0.10.1
-.TH "BUNDLE\-ADD" "1" "September 2025" ""
+.TH "BUNDLE\-ADD" "1" "February 2026" ""
 .SH "NAME"
 \fBbundle\-add\fR \- Add gem to the Gemfile and run bundle install
 .SH "SYNOPSIS"

bundler/lib/bundler/man/bundle-binstubs.1

@@ -1,6 +1,6 @@
 .\" generated with Ronn-NG/v0.10.1
 .\" http://github.com/apjanke/ronn-ng/tree/0.10.1
-.TH "BUNDLE\-BINSTUBS" "1" "September 2025" ""
+.TH "BUNDLE\-BINSTUBS" "1" "February 2026" ""
 .SH "NAME"
 \fBbundle\-binstubs\fR \- Install the binstubs of the listed gems
 .SH "SYNOPSIS"

bundler/lib/bundler/man/bundle-cache.1

@@ -1,6 +1,6 @@
 .\" generated with Ronn-NG/v0.10.1
 .\" http://github.com/apjanke/ronn-ng/tree/0.10.1
-.TH "BUNDLE\-CACHE" "1" "September 2025" ""
+.TH "BUNDLE\-CACHE" "1" "February 2026" ""
 .SH "NAME"
 \fBbundle\-cache\fR \- Package your needed \fB\.gem\fR files into your application
 .SH "SYNOPSIS"

bundler/lib/bundler/man/bundle-check.1

@@ -1,6 +1,6 @@
 .\" generated with Ronn-NG/v0.10.1
 .\" http://github.com/apjanke/ronn-ng/tree/0.10.1
-.TH "BUNDLE\-CHECK" "1" "September 2025" ""
+.TH "BUNDLE\-CHECK" "1" "February 2026" ""
 .SH "NAME"
 \fBbundle\-check\fR \- Verifies if dependencies are satisfied by installed gems
 .SH "SYNOPSIS"

bundler/lib/bundler/man/bundle-clean.1

@@ -1,6 +1,6 @@
 .\" generated with Ronn-NG/v0.10.1
 .\" http://github.com/apjanke/ronn-ng/tree/0.10.1
-.TH "BUNDLE\-CLEAN" "1" "September 2025" ""
+.TH "BUNDLE\-CLEAN" "1" "February 2026" ""
 .SH "NAME"
 \fBbundle\-clean\fR \- Cleans up unused gems in your bundler directory
 .SH "SYNOPSIS"

bundler/lib/bundler/man/bundle-config.1

@@ -1,6 +1,6 @@
 .\" generated with Ronn-NG/v0.10.1
 .\" http://github.com/apjanke/ronn-ng/tree/0.10.1
-.TH "BUNDLE\-CONFIG" "1" "September 2025" ""
+.TH "BUNDLE\-CONFIG" "1" "February 2026" ""
 .SH "NAME"
 \fBbundle\-config\fR \- Set bundler configuration options
 .SH "SYNOPSIS"
@@ -248,7 +248,16 @@ bundle config set \-\-local local\.GEM_NAME /path/to/local/git/repository
 .fi
 .IP "" 0
 .P
-For example, in order to use a local Rack repository, a developer could call:
+Important: This feature only works for gems that are specified with a git source in your Gemfile\. It does not work for gems installed from RubyGems or other sources\. The gem must be defined with \fBgit:\fR option pointing to a remote repository\.
+.P
+For example, if your Gemfile contains:
+.IP "" 4
+.nf
+gem "rack", git: "https://github\.com/rack/rack\.git", branch: "main"
+.fi
+.IP "" 0
+.P
+Then you can use a local Rack repository by running:
 .IP "" 4
 .nf
 bundle config set \-\-local local\.rack ~/Work/git/rack
@@ -260,6 +269,13 @@ Now instead of checking out the remote git repository, the local override will b
 Bundler does many checks to ensure a developer won't work with invalid references\. Particularly, we force a developer to specify a branch in the \fBGemfile\fR in order to use this feature\. If the branch specified in the \fBGemfile\fR and the current branch in the local git repository do not match, Bundler will abort\. This ensures that a developer is always working against the correct branches, and prevents accidental locking to a different branch\.
 .P
 Finally, Bundler also ensures that the current revision in the \fBGemfile\.lock\fR exists in the local git repository\. By doing this, Bundler forces you to fetch the latest changes in the remotes\.
+.P
+If you need to temporarily use a local version of a gem that is normally installed from RubyGems (not from git), use a path source instead:
+.IP "" 4
+.nf
+gem "rack", path: "~/Work/git/rack"
+.fi
+.IP "" 0
 .SH "MIRRORS OF GEM SOURCES"
 Bundler supports overriding gem sources with mirrors\. This allows you to configure rubygems\.org as the gem source in your Gemfile while still using your mirror to fetch gems\.
 .IP "" 4

bundler/lib/bundler/man/bundle-config.1.ronn

@@ -295,7 +295,16 @@ up a local override:
 
     bundle config set --local local.GEM_NAME /path/to/local/git/repository
 
-For example, in order to use a local Rack repository, a developer could call:
+Important: This feature only works for gems that are specified with a git
+source in your Gemfile. It does not work for gems installed from RubyGems
+or other sources. The gem must be defined with `git:` option pointing to a
+remote repository.
+
+For example, if your Gemfile contains:
+
+    gem "rack", git: "https://github.com/rack/rack.git", branch: "main"
+
+Then you can use a local Rack repository by running:
 
     bundle config set --local local.rack ~/Work/git/rack
 
@@ -321,6 +330,11 @@ Finally, Bundler also ensures that the current revision in the
 `Gemfile.lock` exists in the local git repository. By doing this, Bundler
 forces you to fetch the latest changes in the remotes.
 
+If you need to temporarily use a local version of a gem that is normally
+installed from RubyGems (not from git), use a path source instead:
+
+    gem "rack", path: "~/Work/git/rack"
+
 ## MIRRORS OF GEM SOURCES
 
 Bundler supports overriding gem sources with mirrors. This allows you to

bundler/lib/bundler/man/bundle-console.1

@@ -1,6 +1,6 @@
 .\" generated with Ronn-NG/v0.10.1
 .\" http://github.com/apjanke/ronn-ng/tree/0.10.1
-.TH "BUNDLE\-CONSOLE" "1" "September 2025" ""
+.TH "BUNDLE\-CONSOLE" "1" "February 2026" ""
 .SH "NAME"
 \fBbundle\-console\fR \- Open an IRB session with the bundle pre\-loaded
 .SH "SYNOPSIS"

bundler/lib/bundler/man/bundle-doctor.1

@@ -1,6 +1,6 @@
 .\" generated with Ronn-NG/v0.10.1
 .\" http://github.com/apjanke/ronn-ng/tree/0.10.1
-.TH "BUNDLE\-DOCTOR" "1" "September 2025" ""
+.TH "BUNDLE\-DOCTOR" "1" "February 2026" ""
 .SH "NAME"
 \fBbundle\-doctor\fR \- Checks the bundle for common problems
 .SH "SYNOPSIS"

bundler/lib/bundler/man/bundle-env.1

@@ -1,6 +1,6 @@
 .\" generated with Ronn-NG/v0.10.1
 .\" http://github.com/apjanke/ronn-ng/tree/0.10.1
-.TH "BUNDLE\-ENV" "1" "September 2025" ""
+.TH "BUNDLE\-ENV" "1" "February 2026" ""
 .SH "NAME"
 \fBbundle\-env\fR \- Print information about the environment Bundler is running under
 .SH "SYNOPSIS"