toys 0.23.0 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ee5fe663d934949887ff7ce01289453e7b59efcc553331e2efb8a8ae949b626b
-  data.tar.gz: c34a38d893789bdb14fc159f211ac83b09a39b2d897601c961755876be2b6d28
+  metadata.gz: e494ced1b44b862aee77dd732210549374c571b55b4da8d503034ef3f87bba6f
+  data.tar.gz: bceadfc53e8b691951eef4ea4ef6d8b2f666590f745185322577d4bb5ccff82e
 SHA512:
-  metadata.gz: 0fd0c5c2edfe80ede91db110a513bfe176766b4d3c8a75e378721296b8fe4c7c5681e07695fa249f9efede159ffb9feff43524d3ad085f98ca7498af9433c3d1
-  data.tar.gz: 5345ecacee610f36dd439f7adf8b1118a1cc0ecb858f19a5f3c938a5e86a33fb19be94fff5173e3170d1bac6b8ed4309fc54192f5542573e15a7109ddeaba9e2
+  metadata.gz: 40b86310b2d3ad6ce6b16ba738f4d8f543943f008a41b77fdc91b8f858afe50fa2104b3adebb2719aba98e6e920ce7f86f5df00a3c9d8824b4ea85e395fa5710
+  data.tar.gz: e468cd88b4042956bf12cbead2316c592799e667d61299ae69ab66d7cf457f5cef727a3d3cbb1589c3bf3cc16d76a89f8e8c4fff036a343fc6ad5a488456c2c9

data/.yardopts

@@ -1,7 +1,6 @@
 --no-private
 --title=Toys
 --markup=markdown
---markup-provider redcarpet
 --main=README.md
 ./core-docs/toys/**/*.rb
 ./core-docs/toys-core.rb

data/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Release History
 
+### v0.25.0 / 2026-10-10
+
+This is a release candidate release toward version 1.0. It includes a variety of fixes and small features, largely around adherence to clig.dev and other common CLI guidelines.
+
+* Major updates
+    * ADDED: The `-h` flag is now a standard help flag, similar to `--help`.
+* Updates to tool lookup
+    * ADDED: Toys now loads global tools from the XDG config directories
+    * ADDED: The `TOYS_GLOBAL_SOURCES` environment variable selects which global sources are searched
+    * BREAKING CHANGE: The `TOYS_PATH` environment variable is no longer supported. Use `XDG_CONFIG_HOME`, `XDG_CONFIG_DIRS`, or `TOYS_GLOBAL_SOURCES` instead.
+    * BREAKING CHANGE: Toys no longer loads global tools from `/etc/.toys.rb` or `/etc/.toys/`. Move them into `/etc/xdg/toys` instead.
+    * BREAKING CHANGE: Removed the `Toys::StandardCLI::TOYS_PATH_ENV` constant.
+* Updates to logging and warnings
+    * ADDED: Warnings are displayed when a tool invokes a deprecated interface. They can be turned off by setting `TOYS_SUPPRESS_WARNINGS` to a nonempty value.
+    * ADDED: Logs display with a simplified severity prefix unless verbosity is positive
+    * FIXED: The `DEBUG` log prefix is no longer colored white
+    * FIXED: Logs emitted from tool initializers honor the verbosity
+* Updates to ANSI coloring control
+    * ADDED: The `FORCE_COLOR` environment variable forces styled output on, or off when set to 0 or false
+    * FIXED: An empty `NO_COLOR` environment variable no longer disables styled output, per the no-color.org spec
+    * FIXED: Styled output is disabled when the `TERM` environment variable is set to `dumb`
+    * FIXED: The highline mixin decides whether to use color from its own output stream, and honors `NO_COLOR`, `FORCE_COLOR`, and `TERM=dumb`
+    * FIXED: Help text displayed through a pager honors the styled output setting, including `NO_COLOR`, `FORCE_COLOR`, and `TERM=dumb`
+* Other fixes
+    * FIXED: Bash tab completion discards stderr from the completion command, preventing unwanted output if warnings are emitted.
+    * FIXED: Tool-not-found suggestions include namespaces
+    * FIXED: The `:push` handler creates a new array rather than appending in place, so that a frozen or non-cloneable default doesn't cause problems
+    * FIXED: Re-vendor `simple_xdg` 0.1.2 to pick up home directory fix
+    * FIXED: Re-vendor `git_cache` 0.2.0 to report an unwritable cache directory clearly and fix repo lock races
+
+### v0.24.0 / 2026-09-11
+
+* Feature: The `toys do` builtin provides an `--on-missing-gem` flag that governs how the `--gem` flag handles gems that are not installed.
+* BREAKING CHANGE: Removed deprecated `gem_version:` argument from `:rspec` and `:minitest` templates.
+
 ### v0.23.0 / 2026-09-09
 
 This is a major release, with several new features. It also includes a significant refactor of some of the underlying layers, which should be mostly invisible. It is a release candidate for the upcoming version 1.0.

data/README.md

@@ -108,9 +108,10 @@ Toys searches up the directory hierarchy for Toys files. So it will find this
 also read multiple files if it finds them, so you can "scope" your tools more
 specifically or generally by locating them in your directory hierarchy.
 
-If you want to define "global" tools that apply anywhere, write a Toys file
-either in your home directory, or in the system configuration directory
-(usually `/etc`). Toys always searches these locations.
+If you want to define "global" tools that apply anywhere, write a Toys file in
+your home directory, or put tool files in the `toys` directory under your user
+configuration directory (usually `~/.config/toys`) or the system configuration
+directory (usually `/etc/xdg/toys`). Toys searches these locations by default.
 
 ### A more sophisticated example
 

data/bin/toys

@@ -8,4 +8,11 @@ $LOAD_PATH.delete(::ENV["TOYS_LIB_PATH"])
 $LOAD_PATH.unshift(::ENV["TOYS_LIB_PATH"])
 require "toys"
 
-exit(::Toys::StandardCLI.new.run(::ARGV))
+begin
+  cli = ::Toys::StandardCLI.new
+rescue ::Toys::StandardCLI::InvalidGlobalSourcesError => e
+  # Not Kernel#warn, which -W0 would silence, hiding why toys exited.
+  $stderr.puts(e.message) # rubocop:disable Style/StderrPuts
+  exit(2)
+end
+exit(cli.run(::ARGV))

data/builtins/do.rb

@@ -17,16 +17,10 @@ long_desc \
   "The --delim flag must appear first before the tools to run. Any flags that appear later in" \
     " the command line will be passed to the tools themselves.",
   "",
-  "You may also make additional tools available to the tools you run, by passing the --gem," \
-    " --git, and --path flags. Each adds a source of tools, which takes priority over the" \
-    " tools that would otherwise be found. The three flags may be repeated and interleaved," \
-    " and the source added by the leftmost flag takes priority over the sources added by the" \
-    " flags to its right. For example:",
-  ["    toys do --gem=my-tools --git=https://github.com/dazuma/example deploy --migrate"],
-  "Here, a tool defined by both sources is taken from the gem. See the descriptions of the" \
-    " individual flags below for the syntax of their values. Note that the commas within those" \
-    " values are part of the flag value, and are unrelated to the delimiter that separates the" \
-    " tools to run."
+  "You may also load tools from additional sources, by passing the --gem, --git, and --path" \
+    " flags. Any number of these flags can be added; each adds a source of tools, with earlier" \
+    " flags taking priority over later. For example:",
+  ["    toys do --gem=my-tools --git=https://github.com/dazuma/example deploy --migrate"]
 
 flag :delim do
   flags "-d", "--delim=VALUE"
@@ -49,7 +43,9 @@ flag :sources do
   default []
   desc "Make the tools from the given gem available"
   long_desc \
-    "Adds the tools from the given gem, prompting to install the gem if it is not present.",
+    "Adds the tools from the given gem. If the specified gem is not currently installed," \
+      " follows the policy set by the --on-missing-gem flag, which is normally to prompt" \
+      " whether to install.",
     "",
     "The value is the gem name, optionally followed by any number of version requirements," \
       " all separated by commas. Whitespace surrounding each element is ignored. The version" \
@@ -67,21 +63,18 @@ flag :sources do
       " if it is not already there.",
     "",
     "The value is the git remote (i.e. the repository URL or path), optionally followed by any" \
-      " number of \"key=value\" elements, all separated by commas. Whitespace surrounding each" \
-      " element, and surrounding each equals sign, is ignored. For example:",
+      " number of \"key=value\" elements, all separated by commas. There is no way to escape" \
+      " a comma appearing within the value. Whitespace surrounding each element, and surrounding" \
+      " each equals sign, is ignored. For example:",
     ["    --git=\"https://github.com/dazuma/example, path=toys, commit=main\""],
-    "The recognized keys are:",
-    ["    path     The file or directory within the repository to load. By default, the"],
-    ["             entire repository is loaded."],
-    ["    commit   The SHA, tag, or branch to load. By default, the repository head is used."],
-    ["    update   Whether to refresh a previously cached repository. Pass \"true\" or \"false\","],
-    ["             or a number of seconds, to refresh only if the cache is at least that old."],
-    ["             The default is \"false\"."],
-    "Unlike --gem, which takes its elements positionally, the elements here are named, because" \
-      " a git source has three independent optional fields and a positional syntax could not" \
-      " express, for example, a path with no commit.",
     "",
-    "There is no way to escape a comma appearing within the value."
+    "The recognized keys are:",
+    "* \"path\" : The file or directory within the repository to load. By default, the entire" \
+      " repository is loaded.",
+    "* \"commit\" : The SHA, tag, or branch to load. By default, the repository head is used.",
+    "* \"update\" : Whether to refresh a previously cached repository. Pass \"true\" or" \
+      " \"false\", or a number of seconds, to refresh only if the cache is at least that old." \
+      " The default is \"false\"."
 end
 
 flag :sources do
@@ -96,6 +89,22 @@ flag :sources do
     ["    --path=/path/to/my-tools"]
 end
 
+flag :on_missing_gem do
+  flags "--on-missing-gem=WHAT"
+  accept [:confirm, :install, :error]
+  complete_values ["confirm", "install", "error"]
+  desc "Specify what to do if a gem is not installed"
+  long_desc \
+    "Specifies what to do if a gem referenced by the --gem flag is not installed." \
+      " Possible values are:",
+    "* \"confirm\" : Prompt for what to do.",
+    "* \"install\" : Do not prompt, but just install the needed gem.",
+    "* \"error\" : Display an error and abort.",
+    "",
+    "Defaults to the existing CLI configuration, normally \"confirm\". Note this does not affect" \
+      " any other gem references such as via the \"gem\" or \"load_gem\" directives."
+end
+
 remaining_args :commands do
   complete do |context|
     commands = context.arg_parser.data[:commands]
@@ -119,24 +128,19 @@ def run
 end
 
 # Returns the CLI used to run the requested tools. Normally this is simply the
-# current CLI, but if any sources were requested, we need a new CLI because
-# sources cannot be added to a CLI that has already started loading tools. The
-# new CLI copies the current sources and adds the requested ones on top of
-# them. The requested sources are added in reverse order so that the first flag
-# on the command line ends up with the highest priority.
+# current CLI, but if any sources were requested, we need a new CLI with those
+# sources added. Any new sources are added in reverse order so that the first
+# flag on the command line ends up with the highest priority.
 #
 # All the flag values are parsed up front, in command line order, so that a
 # malformed value is reported before any source is added, and is reported
-# against the first offending flag rather than the last.
-#
-# All added sources are then proactively resolved and failures reported.
+# against the first offending flag rather than the last. All added sources are
+# then proactively resolved and failures reported.
 def build_cli
   specs = sources.map { |kind, value| parse_source_request(kind, value) }
   return cli if specs.empty?
-  require "toys/utils/gems" if specs.any? { |spec| spec.is_a?(::Toys::SourceSpec::Gem) }
-  tool_cli = cli.child(copy_sources: true) do |child_cli|
-    specs.reverse_each { |spec| child_cli.add_source(spec, high_priority: true) }
-  end
+  tool_cli = cli.child(copy_sources: true)
+  specs.reverse_each { |spec| tool_cli.add_source(spec, high_priority: true) }
   begin
     tool_cli.loader.resolve_sources
   rescue ::Toys::ToolSourceError => e
@@ -174,7 +178,7 @@ def parse_gem_request(gem_request)
     logger.fatal("Invalid version requirement for gem #{gem_name.inspect}: #{e.message}")
     exit(1)
   end
-  ::Toys::SourceSpec.gem(gem_name, version: gem_version)
+  ::Toys::SourceSpec.gem(gem_name, version: gem_version, on_missing: on_missing_gem)
 end
 
 # Splits a --git flag value into the git remote and the options that follow it,

data/core-docs/toys/cli.rb

@@ -85,6 +85,8 @@ module Toys
     #     as an argument, and returns a `Logger` to use when running that tool.
     #     Optional. If not provided (and no global logger is set),
     #     {Toys::CLI.default_logger_factory} is called to get a basic default.
+    #     See {Toys::Runner} for how a logger can receive the verbosity of
+    #     the run.
     # @param base_level [Integer] The logger level that should correspond
     #     to zero verbosity.
     #     Optional. If not provided, defaults to the level the logger has
@@ -314,8 +316,8 @@ module Toys
     # source list. If the given search directory path does not exist or does
     # not contain either the file or directory, nothing is added.
     #
-    # The main Toys executable uses this method to load tools from directories
-    # in the `TOYS_PATH`.
+    # The main Toys executable uses this method to load tools from the
+    # directories in its upward walk and from the home directory.
     #
     # @param search_path [String,Pathname] A directory path to search for the
     #     well-known source file and directory. Must be a String or a Pathname.
@@ -349,9 +351,6 @@ module Toys
     # given directory and works up through parent directories until it reaches
     # the file system root or it encounters one of the "terminate" directories.
     #
-    # The main Toys executable uses this method to load tools from the current
-    # directory and its ancestors.
-    #
     # @param start [String,Pathname,nil] The first directory path to search.
     #     If not given, defaults to the current working directory. If provided,
     #     must be a String or a Pathname. Paths should generally be absolute.

data/core-docs/toys/core.rb

@@ -9,6 +9,6 @@ module Toys
     # Current version of Toys core.
     # @return [String]
     #
-    VERSION = "0.23.0"
+    VERSION = "0.25.0"
   end
 end

data/core-docs/toys/dsl/tool.rb

@@ -308,38 +308,6 @@ module Toys
         # Source available in the toys-core gem
       end
 
-      ##
-      # Create an alias, representing an "alternate name" for a tool.
-      #
-      # Note: This is functionally equivalent to creating a tool with the
-      # `:delegate_relative` option. As such, `alias_tool` is considered
-      # deprecated.
-      #
-      # ### Example
-      #
-      # This example defines a tool and an alias pointing to it. Both the tool
-      # name `test` and the alias `t` will then refer to the same tool.
-      #
-      #     tool "test" do
-      #       def run
-      #         puts "Running tests..."
-      #       end
-      #     end
-      #     alias_tool "t", "test"
-      #     # Note: the following is preferred over alias_tool:
-      #     # tool "t", delegate_relative: "test"
-      #
-      # @param word [String] The name of the alias
-      # @param target [String,Array<String>] Relative path to the target of the
-      #     alias. This path may be given as an array of strings, or a single
-      #     string possibly delimited by path separators.
-      # @return [self]
-      # @deprecated Use {#tool} and pass `:delegate_relative` instead
-      #
-      def alias_tool(word, target)
-        # Source available in the toys-core gem
-      end
-
       ##
       # Causes the current tool to delegate to another tool, specified by the
       # full tool name. When run, it simply invokes the target tool with the
@@ -458,6 +426,18 @@ module Toys
       #     Context directory paths should generally be absolute. Relative
       #     paths will be converted to absolute, using the current working
       #     directory at the time of loading.
+      # @param on_missing [:confirm,:error,:install] What to do if the
+      #     requested gem is not installed. Possible values:
+      #
+      #      *  `:confirm` - prompt the user on whether to install
+      #      *  `:error` - raise an exception
+      #      *  `:install` - just install the gem
+      #
+      #     Defaults to the setting in the {Toys::Utils::Gems} utility used to
+      #     activate the gem (usually `:confirm`).
+      # @param default_confirm [boolean] The default confirmation result, if
+      #     `on_missing` is set to `:confirm`. Defaults to the setting in the
+      #     {Toys::Utils::Gems} utility used to activate the gem (usually true).
       # @param as [String] Load into the given tool/namespace, relative to the
       #     current namespace. If omitted, tools will be loaded into the
       #     current namespace.
@@ -469,6 +449,8 @@ module Toys
                    path: nil,
                    toys_dir: nil,
                    context_directory: nil,
+                   on_missing: nil,
+                   default_confirm: nil,
                    as: nil)
         # Source available in the toys-core gem
       end

data/core-docs/toys/flag.rb

@@ -264,10 +264,12 @@ module Toys
     SET_HANDLER = proc { |val| val }
 
     ##
-    # The push handler pushes the given value using the `<<` operator.
+    # The push handler appends the given value, returning a new array. The
+    # previous array is not modified, so a shared or frozen default array
+    # can be used safely.
     # @return [Proc]
     #
-    PUSH_HANDLER = proc { |val, prev| prev.nil? ? [val] : prev << val }
+    PUSH_HANDLER = proc { |val, prev| prev.nil? ? [val] : prev + [val] }
 
     ##
     # The default handler is the set handler, which replaces the previous value.

data/core-docs/toys/runner.rb

@@ -34,6 +34,15 @@ module Toys
   #       end
   #     end
   #
+  # While a tool runs, the Runner sets the level of the tool's logger to reflect
+  # the verbosity, as described under the `base_level` parameter of
+  # {#initialize}. A logger can also receive the verbosity itself, by
+  # implementing a `verbosity` attribute: if the logger responds to both
+  # `verbosity` and `verbosity=`, the Runner sets it to the verbosity (an
+  # Integer) for the duration of the run, and restores the previous value
+  # afterward. This lets a logger vary its behavior, such as its formatting, by
+  # verbosity independently of its level.
+  #
   # **_Defined in the toys-core gem_**
   #
   class Runner
@@ -72,7 +81,8 @@ module Toys
     # @param logger_factory [Proc,nil] A proc that takes a
     #     {Toys::ToolDefinition} as an argument, and returns a logger to use
     #     when running that tool. If not given,
-    #     {Toys::Runner::DEFAULT_LOGGER_FACTORY} is used.
+    #     {Toys::Runner::DEFAULT_LOGGER_FACTORY} is used. See {Toys::Runner}
+    #     for how a logger can receive the verbosity of the run.
     # @param base_level [Integer,nil] The logger level that corresponds to zero
     #     verbosity. If not provided, the level the logger has before a run
     #     adjusts it is used (typically Logger::WARN). A run nested inside

data/core-docs/toys/source_spec.rb

@@ -105,10 +105,24 @@ module Toys
       # @param source_name [String,nil] The source name that will be shown in
       #     documentation for tools loaded from this source. If omitted, a
       #     default is generated at resolution time.
+      # @param on_missing [:confirm,:error,:install] What to do if the
+      #     requested gem is not installed. Possible values:
+      #
+      #      *  `:confirm` - prompt the user on whether to install
+      #      *  `:error` - raise an exception
+      #      *  `:install` - just install the gem
+      #
+      #     Defaults to the setting in the {Toys::Utils::Gems} utility used to
+      #     activate the gem (usually `:confirm`).
+      # @param default_confirm [boolean] The default confirmation result, if
+      #     `on_missing` is set to `:confirm`. Defaults to the setting in the
+      #     {Toys::Utils::Gems} utility used to activate the gem (usually true).
+      #
       # @return [Toys::SourceSpec::Gem]
       # @raise [ArgumentError] if an argument is not a legal value.
       #
-      def gem(name, version: nil, path: nil, toys_dir: nil, context_directory: nil, source_name: nil)
+      def gem(name, version: nil, path: nil, toys_dir: nil, context_directory: nil, source_name: nil,
+              on_missing: nil, default_confirm: nil)
         # Source available in the toys-core gem
       end
 
@@ -285,6 +299,24 @@ module Toys
       #
       attr_reader :toys_dir
 
+      ##
+      # What to do if the gem is not installed.
+      #
+      # @return [nil] to use the default behavior for the Gems util
+      # @return [:error] if an error should be raised
+      # @return [:confirm] if a confirmation prompt should be presented
+      # @return [:install] if the gem should be installed without confirmation
+      #
+      attr_reader :on_missing
+
+      ##
+      # The default response for a confirmation prompt
+      #
+      # @return [nil] to use the default behavior for the Gems util
+      # @return [boolean] to provide an override
+      #
+      attr_reader :default_confirm
+
       protected
     end
 

data/core-docs/toys/standard_middleware/handle_usage_errors.rb

@@ -22,8 +22,9 @@ module Toys
       #     occurs. Default is {USAGE_ERROR_EXIT_CODE}.
       # @param stream [IO] Output stream to write to. Default is stderr.
       # @param styled_output [boolean,nil] Cause the tool to display help text
-      #     with ansi styles. If `nil`, display styles if the output stream is
-      #     a tty. Default is `nil`.
+      #     with ansi styles. If `nil`, whether to display styles is inferred
+      #     from the output stream and the environment. See
+      #     {Toys::Utils::Terminal.infer_styled}. Default is `nil`.
       #
       def initialize(exit_code: nil, stream: $stderr, styled_output: nil)
         # Source available in the toys-core gem

data/core-docs/toys/standard_middleware/show_help.rb

@@ -17,7 +17,7 @@ module Toys
       # Default help flags
       # @return [Array<String>]
       #
-      DEFAULT_HELP_FLAGS = ["-?", "--help"].freeze
+      DEFAULT_HELP_FLAGS = ["-h", "-?", "--help"].freeze
 
       ##
       # Default usage flags
@@ -165,8 +165,9 @@ module Toys
       #     false) if the output stream is not a tty.
       # @param stream [IO] Output stream to write to. Default is stdout.
       # @param styled_output [boolean,nil] Cause the tool to display help text
-      #     with ansi styles. If `nil`, display styles if the output stream is
-      #     a tty. Default is `nil`.
+      #     with ansi styles. If `nil`, whether to display styles is inferred
+      #     from the output stream and the environment. See
+      #     {Toys::Utils::Terminal.infer_styled}. Default is `nil`.
       #
       def initialize(help_flags: false,
                      usage_flags: false,

data/core-docs/toys/standard_mixins/highline.rb

@@ -25,6 +25,11 @@ module Toys
     # The arguments will be passed on to the
     # [HighLine constructor](https://www.rubydoc.info/gems/highline/HighLine:initialize).
     #
+    # Whether the HighLine object uses color is inferred from its output
+    # stream and the environment, using the same rule as a terminal. See
+    # {Toys::Utils::Terminal.infer_styled}. You can override it by setting
+    # `use_color` on the HighLine object.
+    #
     # **_Defined in the toys-core gem_**
     #
     module Highline

data/core-docs/toys/utils/gems.rb

@@ -126,7 +126,6 @@ module Toys
       #      *  `:install` - just install the gem
       #
       #     The default is `:confirm`.
-      #
       # @param on_conflict [:error,:warn,:ignore] What to do if bundler has
       #     already been run with a different Gemfile. Possible values:
       #
@@ -135,21 +134,30 @@ module Toys
       #      *  `:warn` - print a warning and proceed without bundling again
       #
       #     The default is `:error`.
-      #
       # @param default_confirm [boolean] The default confirmation result, if
       #     `on_missing` is set to `:confirm`. Defaults to true.
       # @param terminal [Toys::Utils::Terminal] Terminal to use (optional)
       # @param input [IO] Input IO (optional, defaults to STDIN)
       # @param output [IO] Output IO (optional, defaults to STDOUT)
-      # @param suppress_confirm [boolean] Deprecated. Use `on_missing` instead.
       #
       def initialize(on_missing: nil,
                      on_conflict: nil,
+                     default_confirm: nil,
                      terminal: nil,
                      input: nil,
-                     output: nil,
-                     suppress_confirm: nil,
-                     default_confirm: nil)
+                     output: nil)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Return a gem activator with the same settings as this one, except for
+      # the provided overrides. See the constructor for argument docs. If no
+      # non-nil overrides are provided, self is returned.
+      #
+      # @param overrides [Hash] Overrides. See the constructor for details.
+      # @return [Toys::Utils::Gems]
+      #
+      def with(**overrides)
         # Source available in the toys-core gem
       end
 

data/core-docs/toys/utils/git_cache.rb

@@ -16,7 +16,9 @@ module Toys
       # Access a git cache.
       #
       # @param cache_dir [String] The path to the cache directory. Defaults to
-      #     a specific directory in the user's XDG cache.
+      #     a specific directory in the user's XDG cache. Cache data is stored
+      #     in a subdirectory named for the cache format version, so that clients
+      #     using incompatible formats can share a cache directory safely.
       #
       def initialize(cache_dir: nil)
         # Source available in the toys-core gem
@@ -98,8 +100,9 @@ module Toys
       # repositories are requested, they will be reloaded from the remote
       # repository from scratch.
       #
-      # Be careful not to remove repos that are currently in use by other
-      # Toys::Utils::GitCache clients.
+      # This waits for any in-progress {#get} calls for these repos to finish.
+      # However, be careful not to remove repos whose shared sources are
+      # currently in use by other Toys::Utils::GitCache clients.
       #
       # @param remotes [Array<String>,:all,nil] The remotes to remove. If set
       #     to :all or nil, removes all repos.

data/core-docs/toys/utils/pager.rb

@@ -30,14 +30,18 @@ module Toys
       #     stream. Default is `true`.
       # @param exec_service [Toys::Utils::Exec] The service to use for
       #     executing commands, or `nil` (the default) to use a default.
+      # @param output [IO,StringIO,nil] The stream to which the pager process
+      #     writes its output, and the default fallback stream. If `nil` (the
+      #     default), the pager process inherits the parent's standard output.
       # @param fallback_io [IO] An IO-like object to write to if the pager is
-      #     disabled. Defaults to `$stdout`.
+      #     disabled or could not be executed. Defaults to the `output` stream
+      #     if one is given, otherwise `$stdout`.
       # @param rescue_broken_pipes [boolean] If `true` (the default), broken
       #     pipes are silently rescued. This prevents the exception from
       #     propagating out if the pager is interrupted. Set this parameter to
       #     `false` to disable this behavior.
       #
-      def initialize(command: true, exec_service: nil, fallback_io: nil,
+      def initialize(command: true, exec_service: nil, output: nil, fallback_io: nil,
                      rescue_broken_pipes: true)
         # Source available in the toys-core gem
       end
@@ -71,12 +75,32 @@ module Toys
       #
       attr_accessor :command
 
+      ##
+      # The stream to which the pager process writes its output, or `nil` if
+      # the pager process inherits the parent's standard output.
+      #
+      # @return [IO,StringIO,nil]
+      #
+      attr_accessor :output
+
       ##
       # The IO stream used if the pager is disabled or could not be executed.
+      # If not set explicitly, this is the {#output} stream if one is set,
+      # otherwise `$stdout`.
       #
       # @return [IO]
       #
-      attr_accessor :fallback_io
+      def fallback_io
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Set the IO stream used if the pager is disabled or could not be
+      # executed. Set to `nil` to use the default.
+      #
+      # @param value [IO,nil]
+      #
+      attr_writer :fallback_io
 
       class << self
         ##
@@ -91,8 +115,12 @@ module Toys
         #     stream. Default is `true`.
         # @param exec_service [Toys::Utils::Exec] The service to use for
         #     executing commands, or `nil` (the default) to use a default.
+        # @param output [IO,StringIO,nil] The stream to which the pager process
+        #     writes its output, and the default fallback stream. If `nil` (the
+        #     default), the pager process inherits the parent's standard output.
         # @param fallback_io [IO] An IO-like object to write to if the pager is
-        #     disabled. Defaults to `$stdout`.
+        #     disabled or could not be executed. Defaults to the `output` stream
+        #     if one is given, otherwise `$stdout`.
         # @param rescue_broken_pipes [boolean] If `true` (the default), broken
         #     pipes are silently rescued. This prevents the exception from
         #     propagating out if the pager is interrupted. Set this parameter to
@@ -107,6 +135,7 @@ module Toys
         #
         def start(command: true,
                   exec_service: nil,
+                  output: nil,
                   fallback_io: nil,
                   rescue_broken_pipes: true,
                   &block)