Document cooldown in CLI and config man pages

Adds the `--cooldown=NUMBER` option to the install, update, add, and
outdated man pages and describes the `cooldown` / `BUNDLE_COOLDOWN`
setting in bundle-config, regenerating the rendered .1 files via
`rake man:build`.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: hsbt

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

@@ -4,7 +4,7 @@
 .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] [\-\-quiet] [\-\-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] [\-\-cooldown=NUMBER] [\-\-quiet] [\-\-skip\-install] [\-\-strict|\-\-optimistic]
 .SH "DESCRIPTION"
 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"
@@ -53,6 +53,9 @@ Adds pessimistic declaration of version\.
 .TP
 \fB\-\-strict\fR
 Adds strict declaration of version\.
+.TP
+\fB\-\-cooldown=<number>\fR
+Only consider gem versions published at least \fInumber\fR days ago when resolving\. Pass \fB0\fR to disable cooldown for this run\. See \fBcooldown\fR in bundle\-config(1) for precedence rules\.
 .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\.

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

@@ -5,7 +5,7 @@ bundle-add(1) -- Add gem to the Gemfile and run bundle install
 
 `bundle add` <GEM_NAME> [--group=GROUP] [--version=VERSION] [--source=SOURCE]
            [--path=PATH] [--git=GIT|--github=GITHUB] [--branch=BRANCH] [--ref=REF]
-           [--quiet] [--skip-install] [--strict|--optimistic]
+           [--cooldown=NUMBER] [--quiet] [--skip-install] [--strict|--optimistic]
 
 ## DESCRIPTION
 
@@ -59,6 +59,11 @@ Adds the named gem to the [`Gemfile(5)`][Gemfile(5)] and run `bundle install`.
 * `--strict`:
   Adds strict declaration of version.
 
+* `--cooldown=<number>`:
+  Only consider gem versions published at least <number> days ago when
+  resolving. Pass `0` to disable cooldown for this run. See `cooldown`
+  in bundle-config(1) for precedence rules.
+
 ## EXAMPLES
 
 1. You can add the `rails` gem to the Gemfile without any version restriction.

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

@@ -137,6 +137,36 @@ learn more about their operation in [bundle install(1)](bundle-install.1.html).
    explicitly configured.
 * `console` (`BUNDLE_CONSOLE`):
    The console that `bundle console` starts. Defaults to `irb`.
+* `cooldown` (`BUNDLE_COOLDOWN`):
+   Number of days a published gem version must age before bundler will
+   resolve to it. Defaults to unset (no cooldown). Pass `0` to disable
+   cooldown for an individual run.
+
+   The effective cooldown for any given gem is resolved from three
+   layers, highest precedence first:
+
+     1. CLI flag `--cooldown N` on `install`, `update`, `add`, and
+        `outdated`.
+     2. This setting (`bundle config set cooldown N` or
+        `BUNDLE_COOLDOWN=N`).
+     3. The per-source `cooldown:` keyword in the Gemfile, such as
+        `source "https://rubygems.org", cooldown: 7`.
+
+   The CLI flag and this setting apply uniformly to every source,
+   including ones declared with their own `cooldown:` value. To keep a
+   private registry permanently exempt while still cooling down public
+   gems, declare `source "https://internal", cooldown: 0` in the
+   Gemfile; remember that `--cooldown N` on the command line will
+   still override it for that single run.
+
+   Cooldown filtering depends on the gem server providing a per-version
+   `created_at` timestamp in the v2 compact-index format. Versions
+   without that metadata - older gem servers, historical entries that
+   predate the v2 cutover on `rubygems.org`, or private registries that
+   still emit the v1 format - are treated as outside the cooldown
+   window and remain resolvable. If you rely on cooldown for
+   supply-chain protection, confirm that the gem server emits
+   `created_at` in its `/info/<gem>` responses.
 * `default_cli_command` (`BUNDLE_DEFAULT_CLI_COMMAND`):
    The command that running `bundle` without arguments should run. Defaults to
    `cli_help` since Bundler 4, but can also be `install` which was the previous

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

@@ -4,7 +4,7 @@
 .SH "NAME"
 \fBbundle\-install\fR \- Install the dependencies specified in your Gemfile
 .SH "SYNOPSIS"
-\fBbundle install\fR [\-\-force] [\-\-full\-index] [\-\-gemfile=GEMFILE] [\-\-jobs=NUMBER] [\-\-local] [\-\-lockfile=LOCKFILE] [\-\-no\-cache] [\-\-no\-lock] [\-\-prefer\-local] [\-\-quiet] [\-\-retry=NUMBER] [\-\-standalone[=GROUP[ GROUP\|\.\|\.\|\.]]] [\-\-trust\-policy=TRUST\-POLICY] [\-\-target\-rbconfig=TARGET\-RBCONFIG]
+\fBbundle install\fR [\-\-cooldown=NUMBER] [\-\-force] [\-\-full\-index] [\-\-gemfile=GEMFILE] [\-\-jobs=NUMBER] [\-\-local] [\-\-lockfile=LOCKFILE] [\-\-no\-cache] [\-\-no\-lock] [\-\-prefer\-local] [\-\-quiet] [\-\-retry=NUMBER] [\-\-standalone[=GROUP[ GROUP\|\.\|\.\|\.]]] [\-\-trust\-policy=TRUST\-POLICY] [\-\-target\-rbconfig=TARGET\-RBCONFIG]
 .SH "DESCRIPTION"
 Install the gems specified in your Gemfile(5)\. If this is the first time you run bundle install (and a \fBGemfile\.lock\fR does not exist), Bundler will fetch all remote sources, resolve dependencies and install all needed gems\.
 .P
@@ -13,6 +13,9 @@ If a \fBGemfile\.lock\fR does exist, and you have not updated your Gemfile(5), B
 If a \fBGemfile\.lock\fR does exist, and you have updated your Gemfile(5), Bundler will use the dependencies in the \fBGemfile\.lock\fR for all gems that you did not update, but will re\-resolve the dependencies of gems that you did update\. You can find more information about this update process below under \fICONSERVATIVE UPDATING\fR\.
 .SH "OPTIONS"
 .TP
+\fB\-\-cooldown=<number>\fR
+Only consider gem versions published at least \fInumber\fR days ago when resolving\. Pass \fB0\fR to disable cooldown for this run, overriding any per\-source or global configuration\. See \fBcooldown\fR in bundle\-config(1) for details on the precedence between the CLI flag, Bundler config, and Gemfile per\-source settings\.
+.TP
 \fB\-\-force\fR, \fB\-\-redownload\fR
 Force reinstalling every gem, even if already installed\.
 .TP

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

@@ -3,7 +3,8 @@ bundle-install(1) -- Install the dependencies specified in your Gemfile
 
 ## SYNOPSIS
 
-`bundle install` [--force]
+`bundle install` [--cooldown=NUMBER]
+                 [--force]
                  [--full-index]
                  [--gemfile=GEMFILE]
                  [--jobs=NUMBER]
@@ -37,6 +38,13 @@ update process below under [CONSERVATIVE UPDATING][].
 
 ## OPTIONS
 
+* `--cooldown=<number>`:
+  Only consider gem versions published at least <number> days ago when
+  resolving. Pass `0` to disable cooldown for this run, overriding any
+  per-source or global configuration. See `cooldown` in bundle-config(1)
+  for details on the precedence between the CLI flag, Bundler config,
+  and Gemfile per-source settings.
+
 * `--force`, `--redownload`:
   Force reinstalling every gem, even if already installed.
 

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

@@ -4,7 +4,7 @@
 .SH "NAME"
 \fBbundle\-outdated\fR \- List installed gems with newer versions available
 .SH "SYNOPSIS"
-\fBbundle outdated\fR [GEM] [\-\-local] [\-\-pre] [\-\-source] [\-\-filter\-strict | \-\-strict] [\-\-update\-strict] [\-\-parseable | \-\-porcelain] [\-\-group=GROUP] [\-\-groups] [\-\-patch|\-\-minor|\-\-major] [\-\-filter\-major] [\-\-filter\-minor] [\-\-filter\-patch] [\-\-only\-explicit]
+\fBbundle outdated\fR [GEM] [\-\-local] [\-\-pre] [\-\-source] [\-\-filter\-strict | \-\-strict] [\-\-update\-strict] [\-\-parseable | \-\-porcelain] [\-\-group=GROUP] [\-\-groups] [\-\-patch|\-\-minor|\-\-major] [\-\-filter\-major] [\-\-filter\-minor] [\-\-filter\-patch] [\-\-only\-explicit] [\-\-cooldown=NUMBER]
 .SH "DESCRIPTION"
 Outdated lists the names and versions of gems that have a newer version available in the given source\. Calling outdated with [GEM [GEM]] will only check for newer versions of the given gems\. Prerelease gems are ignored by default\. If your gems are up to date, Bundler will exit with a status of 0\. Otherwise, it will exit 1\.
 .SH "OPTIONS"
@@ -53,6 +53,9 @@ Only list patch newer versions\.
 .TP
 \fB\-\-only\-explicit\fR
 Only list gems specified in your Gemfile, not their dependencies\.
+.TP
+\fB\-\-cooldown=<number>\fR
+Annotate (rather than hide) versions that are still inside the cooldown window of \fInumber\fR days\. The prose output appends "in cooldown for Nd more days" and the table form adds "(cooldown Nd)" to the Latest column\. See \fBcooldown\fR in bundle\-config(1)\.
 .SH "PATCH LEVEL OPTIONS"
 See bundle update(1) \fIbundle\-update\.1\.html\fR for details\.
 .SH "FILTERING OUTPUT"

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

@@ -16,6 +16,7 @@ bundle-outdated(1) -- List installed gems with newer versions available
                         [--filter-minor]
                         [--filter-patch]
                         [--only-explicit]
+                        [--cooldown=NUMBER]
 
 ## DESCRIPTION
 
@@ -71,6 +72,12 @@ are up to date, Bundler will exit with a status of 0. Otherwise, it will exit 1.
 * `--only-explicit`:
   Only list gems specified in your Gemfile, not their dependencies.
 
+* `--cooldown=<number>`:
+  Annotate (rather than hide) versions that are still inside the
+  cooldown window of <number> days. The prose output appends "in
+  cooldown for Nd more days" and the table form adds "(cooldown Nd)" to
+  the Latest column. See `cooldown` in bundle-config(1).
+
 ## PATCH LEVEL OPTIONS
 
 See [bundle update(1)](bundle-update.1.html) for details.

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

@@ -4,7 +4,7 @@
 .SH "NAME"
 \fBbundle\-update\fR \- Update your gems to the latest available versions
 .SH "SYNOPSIS"
-\fBbundle update\fR \fI*gems\fR [\-\-all] [\-\-group=NAME] [\-\-source=NAME] [\-\-local] [\-\-ruby] [\-\-bundler[=VERSION]] [\-\-force] [\-\-full\-index] [\-\-gemfile=GEMFILE] [\-\-jobs=NUMBER] [\-\-quiet] [\-\-patch|\-\-minor|\-\-major] [\-\-pre] [\-\-strict] [\-\-conservative]
+\fBbundle update\fR \fI*gems\fR [\-\-all] [\-\-group=NAME] [\-\-source=NAME] [\-\-local] [\-\-ruby] [\-\-bundler[=VERSION]] [\-\-cooldown=NUMBER] [\-\-force] [\-\-full\-index] [\-\-gemfile=GEMFILE] [\-\-jobs=NUMBER] [\-\-quiet] [\-\-patch|\-\-minor|\-\-major] [\-\-pre] [\-\-strict] [\-\-conservative]
 .SH "DESCRIPTION"
 Update the gems specified (all gems, if \fB\-\-all\fR flag is used), ignoring the previously installed gems specified in the \fBGemfile\.lock\fR\. In general, you should use bundle install(1) \fIbundle\-install\.1\.html\fR to install the same exact gems and versions across machines\.
 .P
@@ -64,6 +64,9 @@ Do not allow any gem to be updated past latest \fB\-\-patch\fR | \fB\-\-minor\fR
 .TP
 \fB\-\-conservative\fR
 Use bundle install conservative update behavior and do not allow indirect dependencies to be updated\.
+.TP
+\fB\-\-cooldown=<number>\fR
+Only consider gem versions published at least \fInumber\fR days ago when resolving\. Pass \fB0\fR to disable cooldown for this run, overriding any per\-source or global configuration\. Combine with \fB\-\-conservative\fR to minimize transitive churn when bypassing cooldown for an urgent update\. See \fBcooldown\fR in bundle\-config(1)\.
 .SH "UPDATING ALL GEMS"
 If you run \fBbundle update \-\-all\fR, bundler will ignore any previously installed gems and resolve all dependencies again based on the latest versions of all gems available in the sources\.
 .P

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

@@ -9,6 +9,7 @@ bundle-update(1) -- Update your gems to the latest available versions
                         [--local]
                         [--ruby]
                         [--bundler[=VERSION]]
+                        [--cooldown=NUMBER]
                         [--force]
                         [--full-index]
                         [--gemfile=GEMFILE]
@@ -91,6 +92,13 @@ gem.
 * `--conservative`:
   Use bundle install conservative update behavior and do not allow indirect dependencies to be updated.
 
+* `--cooldown=<number>`:
+  Only consider gem versions published at least <number> days ago when
+  resolving. Pass `0` to disable cooldown for this run, overriding any
+  per-source or global configuration. Combine with `--conservative` to
+  minimize transitive churn when bypassing cooldown for an urgent
+  update. See `cooldown` in bundle-config(1).
+
 ## UPDATING ALL GEMS
 
 If you run `bundle update --all`, bundler will ignore