Skip to content

Clarify local gem override docs to require git-sourced gems #9305

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hsbt merged 2 commits into from
Feb 4, 2026
+63 −33
Merged

Clarify local gem override docs to require git-sourced gems #9305

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a4a5cdb
Clarify local gem override docs to require git-sourced gems
hsbt Feb 4, 2026
5e95eba
bin/rake man:build
hsbt Feb 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion bundler/lib/bundler/man/bundle-add.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"
Expand Down
2 changes: 1 addition & 1 deletion bundler/lib/bundler/man/bundle-binstubs.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"
Expand Down
2 changes: 1 addition & 1 deletion bundler/lib/bundler/man/bundle-cache.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"
Expand Down
2 changes: 1 addition & 1 deletion bundler/lib/bundler/man/bundle-check.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"
Expand Down
2 changes: 1 addition & 1 deletion bundler/lib/bundler/man/bundle-clean.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"
Expand Down
20 changes: 18 additions & 2 deletions bundler/lib/bundler/man/bundle-config.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down
16 changes: 15 additions & 1 deletion bundler/lib/bundler/man/bundle-config.1.ronn
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link

Copilot AI Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor grammar issue: should be "with a git: option" or "with the git: option" instead of "with git: option".

Suggested change
or other sources. The gem must be defined with `git:` option pointing to a
or other sources. The gem must be defined with the `git:` option pointing to a

Copilot uses AI. Check for mistakes.
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

Expand All @@ -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"

Comment on lines 298 to 337
Copy link

Copilot AI Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The corresponding generated man page file (bundle-config.1) should also be updated. You can regenerate it by running bin/rake bundler:man:build or similar rake task. The .1 file is the compiled roff format that gets installed and displayed when users run man bundle-config.

Copilot uses AI. Check for mistakes.
## MIRRORS OF GEM SOURCES

Bundler supports overriding gem sources with mirrors. This allows you to
Expand Down
2 changes: 1 addition & 1 deletion bundler/lib/bundler/man/bundle-console.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"
Expand Down
2 changes: 1 addition & 1 deletion bundler/lib/bundler/man/bundle-doctor.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"
Expand Down
2 changes: 1 addition & 1 deletion bundler/lib/bundler/man/bundle-env.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"
Expand Down
2 changes: 1 addition & 1 deletion bundler/lib/bundler/man/bundle-exec.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
.\" generated with Ronn-NG/v0.10.1
.\" http://github.com/apjanke/ronn-ng/tree/0.10.1
.TH "BUNDLE\-EXEC" "1" "September 2025" ""
.TH "BUNDLE\-EXEC" "1" "February 2026" ""
.SH "NAME"
\fBbundle\-exec\fR \- Execute a command in the context of the bundle
.SH "SYNOPSIS"
Expand Down
2 changes: 1 addition & 1 deletion bundler/lib/bundler/man/bundle-fund.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
.\" generated with Ronn-NG/v0.10.1
.\" http://github.com/apjanke/ronn-ng/tree/0.10.1
.TH "BUNDLE\-FUND" "1" "September 2025" ""
.TH "BUNDLE\-FUND" "1" "February 2026" ""
.SH "NAME"
\fBbundle\-fund\fR \- Lists information about gems seeking funding assistance
.SH "SYNOPSIS"
Expand Down
2 changes: 1 addition & 1 deletion bundler/lib/bundler/man/bundle-gem.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
.\" generated with Ronn-NG/v0.10.1
.\" http://github.com/apjanke/ronn-ng/tree/0.10.1
.TH "BUNDLE\-GEM" "1" "September 2025" ""
.TH "BUNDLE\-GEM" "1" "February 2026" ""
.SH "NAME"
\fBbundle\-gem\fR \- Generate a project skeleton for creating a rubygem
.SH "SYNOPSIS"
Expand Down
2 changes: 1 addition & 1 deletion bundler/lib/bundler/man/bundle-help.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
.\" generated with Ronn-NG/v0.10.1
.\" http://github.com/apjanke/ronn-ng/tree/0.10.1
.TH "BUNDLE\-HELP" "1" "September 2025" ""
.TH "BUNDLE\-HELP" "1" "February 2026" ""
.SH "NAME"
\fBbundle\-help\fR \- Displays detailed help for each subcommand
.SH "SYNOPSIS"
Expand Down
2 changes: 1 addition & 1 deletion bundler/lib/bundler/man/bundle-info.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
.\" generated with Ronn-NG/v0.10.1
.\" http://github.com/apjanke/ronn-ng/tree/0.10.1
.TH "BUNDLE\-INFO" "1" "September 2025" ""
.TH "BUNDLE\-INFO" "1" "February 2026" ""
.SH "NAME"
\fBbundle\-info\fR \- Show information for the given gem in your bundle
.SH "SYNOPSIS"
Expand Down
2 changes: 1 addition & 1 deletion bundler/lib/bundler/man/bundle-init.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
.\" generated with Ronn-NG/v0.10.1
.\" http://github.com/apjanke/ronn-ng/tree/0.10.1
.TH "BUNDLE\-INIT" "1" "September 2025" ""
.TH "BUNDLE\-INIT" "1" "February 2026" ""
.SH "NAME"
\fBbundle\-init\fR \- Generates a Gemfile into the current working directory
.SH "SYNOPSIS"
Expand Down
2 changes: 1 addition & 1 deletion bundler/lib/bundler/man/bundle-install.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
.\" generated with Ronn-NG/v0.10.1
.\" http://github.com/apjanke/ronn-ng/tree/0.10.1
.TH "BUNDLE\-INSTALL" "1" "September 2025" ""
.TH "BUNDLE\-INSTALL" "1" "February 2026" ""
.SH "NAME"
\fBbundle\-install\fR \- Install the dependencies specified in your Gemfile
.SH "SYNOPSIS"
Expand Down
2 changes: 1 addition & 1 deletion bundler/lib/bundler/man/bundle-issue.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
.\" generated with Ronn-NG/v0.10.1
.\" http://github.com/apjanke/ronn-ng/tree/0.10.1
.TH "BUNDLE\-ISSUE" "1" "September 2025" ""
.TH "BUNDLE\-ISSUE" "1" "February 2026" ""
.SH "NAME"
\fBbundle\-issue\fR \- Get help reporting Bundler issues
.SH "SYNOPSIS"
Expand Down
2 changes: 1 addition & 1 deletion bundler/lib/bundler/man/bundle-licenses.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
.\" generated with Ronn-NG/v0.10.1
.\" http://github.com/apjanke/ronn-ng/tree/0.10.1
.TH "BUNDLE\-LICENSES" "1" "September 2025" ""
.TH "BUNDLE\-LICENSES" "1" "February 2026" ""
.SH "NAME"
\fBbundle\-licenses\fR \- Print the license of all gems in the bundle
.SH "SYNOPSIS"
Expand Down
2 changes: 1 addition & 1 deletion bundler/lib/bundler/man/bundle-list.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
.\" generated with Ronn-NG/v0.10.1
.\" http://github.com/apjanke/ronn-ng/tree/0.10.1
.TH "BUNDLE\-LIST" "1" "September 2025" ""
.TH "BUNDLE\-LIST" "1" "February 2026" ""
.SH "NAME"
\fBbundle\-list\fR \- List all the gems in the bundle
.SH "SYNOPSIS"
Expand Down
2 changes: 1 addition & 1 deletion bundler/lib/bundler/man/bundle-lock.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
.\" generated with Ronn-NG/v0.10.1
.\" http://github.com/apjanke/ronn-ng/tree/0.10.1
.TH "BUNDLE\-LOCK" "1" "September 2025" ""
.TH "BUNDLE\-LOCK" "1" "February 2026" ""
.SH "NAME"
\fBbundle\-lock\fR \- Creates / Updates a lockfile without installing
.SH "SYNOPSIS"
Expand Down
2 changes: 1 addition & 1 deletion bundler/lib/bundler/man/bundle-open.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
.\" generated with Ronn-NG/v0.10.1
.\" http://github.com/apjanke/ronn-ng/tree/0.10.1
.TH "BUNDLE\-OPEN" "1" "September 2025" ""
.TH "BUNDLE\-OPEN" "1" "February 2026" ""
.SH "NAME"
\fBbundle\-open\fR \- Opens the source directory for a gem in your bundle
.SH "SYNOPSIS"
Expand Down
2 changes: 1 addition & 1 deletion bundler/lib/bundler/man/bundle-outdated.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
.\" generated with Ronn-NG/v0.10.1
.\" http://github.com/apjanke/ronn-ng/tree/0.10.1
.TH "BUNDLE\-OUTDATED" "1" "September 2025" ""
.TH "BUNDLE\-OUTDATED" "1" "February 2026" ""
.SH "NAME"
\fBbundle\-outdated\fR \- List installed gems with newer versions available
.SH "SYNOPSIS"
Expand Down
2 changes: 1 addition & 1 deletion bundler/lib/bundler/man/bundle-platform.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
.\" generated with Ronn-NG/v0.10.1
.\" http://github.com/apjanke/ronn-ng/tree/0.10.1
.TH "BUNDLE\-PLATFORM" "1" "September 2025" ""
.TH "BUNDLE\-PLATFORM" "1" "February 2026" ""
.SH "NAME"
\fBbundle\-platform\fR \- Displays platform compatibility information
.SH "SYNOPSIS"
Expand Down
2 changes: 1 addition & 1 deletion bundler/lib/bundler/man/bundle-plugin.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
.\" generated with Ronn-NG/v0.10.1
.\" http://github.com/apjanke/ronn-ng/tree/0.10.1
.TH "BUNDLE\-PLUGIN" "1" "September 2025" ""
.TH "BUNDLE\-PLUGIN" "1" "February 2026" ""
.SH "NAME"
\fBbundle\-plugin\fR \- Manage Bundler plugins
.SH "SYNOPSIS"
Expand Down
2 changes: 1 addition & 1 deletion bundler/lib/bundler/man/bundle-pristine.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
.\" generated with Ronn-NG/v0.10.1
.\" http://github.com/apjanke/ronn-ng/tree/0.10.1
.TH "BUNDLE\-PRISTINE" "1" "September 2025" ""
.TH "BUNDLE\-PRISTINE" "1" "February 2026" ""
.SH "NAME"
\fBbundle\-pristine\fR \- Restores installed gems to their pristine condition
.SH "SYNOPSIS"
Expand Down
2 changes: 1 addition & 1 deletion bundler/lib/bundler/man/bundle-remove.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
.\" generated with Ronn-NG/v0.10.1
.\" http://github.com/apjanke/ronn-ng/tree/0.10.1
.TH "BUNDLE\-REMOVE" "1" "September 2025" ""
.TH "BUNDLE\-REMOVE" "1" "February 2026" ""
.SH "NAME"
\fBbundle\-remove\fR \- Removes gems from the Gemfile
.SH "SYNOPSIS"
Expand Down
2 changes: 1 addition & 1 deletion bundler/lib/bundler/man/bundle-show.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
.\" generated with Ronn-NG/v0.10.1
.\" http://github.com/apjanke/ronn-ng/tree/0.10.1
.TH "BUNDLE\-SHOW" "1" "September 2025" ""
.TH "BUNDLE\-SHOW" "1" "February 2026" ""
.SH "NAME"
\fBbundle\-show\fR \- Shows all the gems in your bundle, or the path to a gem
.SH "SYNOPSIS"
Expand Down
2 changes: 1 addition & 1 deletion bundler/lib/bundler/man/bundle-update.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
.\" generated with Ronn-NG/v0.10.1
.\" http://github.com/apjanke/ronn-ng/tree/0.10.1
.TH "BUNDLE\-UPDATE" "1" "September 2025" ""
.TH "BUNDLE\-UPDATE" "1" "February 2026" ""
.SH "NAME"
\fBbundle\-update\fR \- Update your gems to the latest available versions
.SH "SYNOPSIS"
Expand Down
2 changes: 1 addition & 1 deletion bundler/lib/bundler/man/bundle-version.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
.\" generated with Ronn-NG/v0.10.1
.\" http://github.com/apjanke/ronn-ng/tree/0.10.1
.TH "BUNDLE\-VERSION" "1" "September 2025" ""
.TH "BUNDLE\-VERSION" "1" "February 2026" ""
.SH "NAME"
\fBbundle\-version\fR \- Prints Bundler version information
.SH "SYNOPSIS"
Expand Down
2 changes: 1 addition & 1 deletion bundler/lib/bundler/man/bundle.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
.\" generated with Ronn-NG/v0.10.1
.\" http://github.com/apjanke/ronn-ng/tree/0.10.1
.TH "BUNDLE" "1" "September 2025" ""
.TH "BUNDLE" "1" "February 2026" ""
.SH "NAME"
\fBbundle\fR \- Ruby Dependency Management
.SH "SYNOPSIS"
Expand Down
2 changes: 1 addition & 1 deletion bundler/lib/bundler/man/gemfile.5
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
.\" generated with Ronn-NG/v0.10.1
.\" http://github.com/apjanke/ronn-ng/tree/0.10.1
.TH "GEMFILE" "5" "September 2025" ""
.TH "GEMFILE" "5" "February 2026" ""
.SH "NAME"
\fBGemfile\fR \- A format for describing gem dependencies for Ruby programs
.SH "SYNOPSIS"
Expand Down