From ced084bd49fa58a239d283997fcf6b5e84054b11 Mon Sep 17 00:00:00 2001 From: Mike McQuaid Date: Thu, 6 Aug 2020 09:25:45 +0100 Subject: [PATCH] Handle casks in commands more consistently. - Ensure the usage documentation always mentions casks when appropriate - Use --formulae or --casks consistently - Provide --formulae and --casks switches to upgrade - Mark more switches as conflicting --- Library/Homebrew/cmd/--cache.rb | 12 ++++---- Library/Homebrew/cmd/list.rb | 16 ++++++---- Library/Homebrew/cmd/outdated.rb | 24 +++++++-------- Library/Homebrew/cmd/upgrade.rb | 26 +++++++++++----- docs/Manpage.md | 46 ++++++++++++++++------------ manpages/brew.1 | 52 ++++++++++++++++++++------------ 6 files changed, 104 insertions(+), 72 deletions(-) diff --git a/Library/Homebrew/cmd/--cache.rb b/Library/Homebrew/cmd/--cache.rb index bd6018efe4..e9dd35c874 100644 --- a/Library/Homebrew/cmd/--cache.rb +++ b/Library/Homebrew/cmd/--cache.rb @@ -13,7 +13,7 @@ module Homebrew def __cache_args Homebrew::CLI::Parser.new do usage_banner <<~EOS - `--cache` [] [] + `--cache` [] [] Display Homebrew's download cache. See also `HOMEBREW_CACHE`. @@ -23,12 +23,12 @@ module Homebrew description: "Show the cache file used when building from source." switch "--force-bottle", description: "Show the cache file used when pouring a bottle." - switch "--formula", + switch "--formulae", description: "Only show cache files for formulae." - switch "--cask", + switch "--casks", description: "Only show cache files for casks." conflicts "--build-from-source", "--force-bottle" - conflicts "--formula", "--cask" + conflicts "--formulae", "--casks" end end @@ -37,11 +37,11 @@ module Homebrew if args.no_named? puts HOMEBREW_CACHE - elsif args.formula? + elsif args.formulae? args.named.each do |name| print_formula_cache name, args: args end - elsif args.cask? + elsif args.casks? args.named.each do |name| print_cask_cache name end diff --git a/Library/Homebrew/cmd/list.rb b/Library/Homebrew/cmd/list.rb index 4948c173c5..4b5c48e84f 100644 --- a/Library/Homebrew/cmd/list.rb +++ b/Library/Homebrew/cmd/list.rb @@ -11,9 +11,9 @@ module Homebrew def list_args Homebrew::CLI::Parser.new do usage_banner <<~EOS - `list`, `ls` [] [] + `list`, `ls` [] [] - List all installed formulae. + List all installed formulae or casks If is provided, summarise the paths within its current keg. EOS @@ -32,8 +32,10 @@ module Homebrew switch "--pinned", description: "Show the versions of pinned formulae, or only the specified (pinned) "\ "formulae if are provided. See also `pin`, `unpin`." - switch "--cask", - description: "List casks" + switch "--formulae", + description: "List only formulae." + switch "--casks", + description: "List only casks." # passed through to ls switch "-1", description: "Force output to be one entry per line. " \ @@ -46,14 +48,16 @@ module Homebrew switch "-t", description: "Sort by time modified, listing most recently modified first." - ["--unbrewed", "--multiple", "--pinned", "-l", "-r", "-t"].each { |flag| conflicts "--cask", flag } + ["--formulae", "--unbrewed", "--multiple", "--pinned", "-l", "-r", "-t"].each do |flag| + conflicts "--casks", flag + end end end def list args = list_args.parse - return list_casks(args: args) if args.cask? + return list_casks(args: args) if args.casks? return list_unbrewed if args.unbrewed? diff --git a/Library/Homebrew/cmd/outdated.rb b/Library/Homebrew/cmd/outdated.rb index 1f6ce94cf2..a3366b7564 100644 --- a/Library/Homebrew/cmd/outdated.rb +++ b/Library/Homebrew/cmd/outdated.rb @@ -12,15 +12,19 @@ module Homebrew def outdated_args Homebrew::CLI::Parser.new do usage_banner <<~EOS - `outdated` [] [] + `outdated` [] [|] - List installed formulae that have an updated version available. By default, version + List installed casks and formulae that have an updated version available. By default, version information is displayed in interactive shells, and suppressed otherwise. EOS switch "-q", "--quiet", description: "List only the names of outdated kegs (takes precedence over `--verbose`)." switch "-v", "--verbose", description: "Include detailed version information." + switch "--formulae", + description: "Only output outdated formulae." + switch "--casks", + description: "Only output outdated casks." flag "--json", description: "Print output in JSON format. There are two versions: v1 and v2. " \ "v1 is deprecated and is currently the default if no version is specified. " \ @@ -31,13 +35,9 @@ module Homebrew "updates when a new stable or development version has been released." switch "--greedy", description: "Print outdated casks with `auto_updates` or `version :latest`." - switch "--formula", - description: "Treat all arguments as formulae." - switch "--cask", - description: "Treat all arguments as casks." conflicts "--quiet", "--verbose", "--json" - conflicts "--formula", "--cask" + conflicts "--formulae", "--casks" end end @@ -49,7 +49,7 @@ module Homebrew # TODO: enable for next major/minor release # odeprecated "brew outdated --json#{json_version == :v1 ? "=v1" : ""}", "brew outdated --json=v2" - outdated = if args.formula? || !args.cask? + outdated = if args.formulae? || !args.casks? outdated_formulae args: args else outdated_casks args: args @@ -58,9 +58,9 @@ module Homebrew puts JSON.generate(json_info(outdated, args: args)) when :v2 - formulae, casks = if args.formula? + formulae, casks = if args.formulae? [outdated_formulae(args: args), []] - elsif args.cask? + elsif args.casks? [[], outdated_casks(args: args)] else outdated_formulae_casks args: args @@ -75,9 +75,9 @@ module Homebrew outdated = formulae + casks else - outdated = if args.formula? + outdated = if args.formulae? outdated_formulae args: args - elsif args.cask? + elsif args.casks? outdated_casks args: args else outdated_formulae_casks(args: args).flatten diff --git a/Library/Homebrew/cmd/upgrade.rb b/Library/Homebrew/cmd/upgrade.rb index dc52efbdc0..623390f895 100644 --- a/Library/Homebrew/cmd/upgrade.rb +++ b/Library/Homebrew/cmd/upgrade.rb @@ -14,11 +14,11 @@ module Homebrew def upgrade_args Homebrew::CLI::Parser.new do usage_banner <<~EOS - `upgrade` [] [] + `upgrade` [] [|] - Upgrade outdated, unpinned formulae using the same options they were originally - installed with, plus any appended brew formula options. If are specified, - upgrade only the given kegs (unless they are pinned; see `pin`, `unpin`). + Upgrade outdated casks and outdated, unpinned formulae using the same options they were originally + installed with, plus any appended brew formula options. If or are specified, + upgrade only the given or kegs (unless they are pinned; see `pin`, `unpin`). Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will then be run for the upgraded formulae or, every 30 days, for all formulae. @@ -26,6 +26,10 @@ module Homebrew switch "-d", "--debug", description: "If brewing fails, open an interactive debugging session with access to IRB "\ "or a shell inside the temporary build directory." + switch "--formulae", + description: "Only upgrade outdated formulae." + switch "--casks", + description: "Only upgrade outdated casks." switch "-s", "--build-from-source", description: "Compile from source even if a bottle is available." switch "-i", "--interactive", @@ -56,6 +60,12 @@ module Homebrew switch "--greedy", description: "Upgrade casks with `auto_updates` or `version :latest`" conflicts "--build-from-source", "--force-bottle" + conflicts "--formulae", "--greedy" + ["--formulae", "-s", "--build-from-source", "-i", "--interactive", + "--force-bottle", "--fetch-HEAD", "--ignore-pinned", "--keep-tmp", + "--display-times"].each do |flag| + conflicts "--casks", flag + end formula_options end end @@ -67,11 +77,11 @@ module Homebrew # If one or more formulae are specified, but no casks were # specified, we want to make note of that so we don't # try to upgrade all outdated casks. - named_formulae_specified = !formulae.empty? && casks.empty? - named_casks_specified = !casks.empty? && formulae.empty? + upgrade_formulae = formulae.present? && casks.blank? && !args.casks? + upgrade_casks = casks.present? && formulae.blank? && !args.formulae? - upgrade_outdated_formulae(formulae, args: args) unless named_casks_specified - upgrade_outdated_casks(casks, args: args) unless named_formulae_specified + upgrade_outdated_formulae(formulae, args: args) unless upgrade_casks + upgrade_outdated_casks(casks, args: args) unless upgrade_formulae end def upgrade_outdated_formulae(formulae, args:) diff --git a/docs/Manpage.md b/docs/Manpage.md index 0cfe7f9602..010a329d4e 100644 --- a/docs/Manpage.md +++ b/docs/Manpage.md @@ -274,9 +274,9 @@ automatically when you install formulae but can be useful for DIY installations. * `-f`, `--force`: Allow keg-only formulae to be linked. -### `list`, `ls` [*`options`*] [*`formula`*] +### `list`, `ls` [*`options`*] [*`formula|cask`*] -List all installed formulae. +List all installed formulae or casks If *`formula`* is provided, summarise the paths within its current keg. @@ -290,8 +290,10 @@ If *`formula`* is provided, summarise the paths within its current keg. Only show formulae with multiple versions installed. * `--pinned`: Show the versions of pinned formulae, or only the specified (pinned) formulae if *`formula`* are provided. See also `pin`, `unpin`. -* `--cask`: - List casks +* `--formulae`: + List only formulae. +* `--casks`: + List only casks. * `-1`: Force output to be one entry per line. This is the default when output is not to a terminal. * `-l`: @@ -347,26 +349,26 @@ Show install options specific to *`formula`*. * `--command`: Show options for the specified *`command`*. -### `outdated` [*`options`*] [*`formula`*] +### `outdated` [*`options`*] [*`formula`*|*`cask`*] -List installed formulae that have an updated version available. By default, -version information is displayed in interactive shells, and suppressed +List installed casks and formulae that have an updated version available. By +default, version information is displayed in interactive shells, and suppressed otherwise. * `-q`, `--quiet`: List only the names of outdated kegs (takes precedence over `--verbose`). * `-v`, `--verbose`: Include detailed version information. +* `--formulae`: + Only output outdated formulae. +* `--casks`: + Only output outdated casks. * `--json`: Print output in JSON format. There are two versions: v1 and v2. v1 is deprecated and is currently the default if no version is specified. v2 prints outdated formulae and casks. * `--fetch-HEAD`: Fetch the upstream repository to detect if the HEAD installation of the formula is outdated. Otherwise, the repository's HEAD will only be checked for updates when a new stable or development version has been released. * `--greedy`: Print outdated casks with `auto_updates` or `version :latest`. -* `--formula`: - Treat all arguments as formulae. -* `--cask`: - Treat all arguments as casks. ### `pin` *`formula`* @@ -536,18 +538,22 @@ Fetch and reset Homebrew and all tap repositories (or any specified *`repository *Note:* this will destroy all your uncommitted or committed changes. -### `upgrade` [*`options`*] [*`formula`*] +### `upgrade` [*`options`*] [*`formula`*|*`cask`*] -Upgrade outdated, unpinned formulae using the same options they were originally -installed with, plus any appended brew formula options. If *`formula`* are -specified, upgrade only the given *`formula`* kegs (unless they are pinned; see -`pin`, `unpin`). +Upgrade outdated casks and outdated, unpinned formulae using the same options +they were originally installed with, plus any appended brew formula options. If +*`cask`* or *`formula`* are specified, upgrade only the given *`cask`* or *`formula`* +kegs (unless they are pinned; see `pin`, `unpin`). Unless `HOMEBREW_NO_INSTALL_CLEANUP` is set, `brew cleanup` will then be run for the upgraded formulae or, every 30 days, for all formulae. * `-d`, `--debug`: If brewing fails, open an interactive debugging session with access to IRB or a shell inside the temporary build directory. +* `--formulae`: + Only upgrade outdated formulae. +* `--casks`: + Only upgrade outdated casks. * `-s`, `--build-from-source`: Compile *`formula`* from source even if a bottle is available. * `-i`, `--interactive`: @@ -595,7 +601,7 @@ formulae that use *`formula`*. By default, `uses` shows all formulae that specif * `--HEAD`: Show usage of *`formula`* by HEAD builds. -### `--cache` [*`options`*] [*`formula`*] +### `--cache` [*`options`*] [*`formula|cask`*] Display Homebrew's download cache. See also `HOMEBREW_CACHE`. @@ -605,9 +611,9 @@ If *`formula`* is provided, display the file or directory used to cache *`formul Show the cache file used when building from source. * `--force-bottle`: Show the cache file used when pouring a bottle. -* `--formula`: +* `--formulae`: Only show cache files for formulae. -* `--cask`: +* `--casks`: Only show cache files for casks. ### `--caskroom` [*`cask`*] @@ -1211,7 +1217,7 @@ flags which will help find keg-only dependencies like `openssl`, `icu4c`, etc. `install` won't output a `Brewfile.lock.json`. * `--all`: `list` all dependencies. -* `--brews`: +* `--formulae`: `list` Homebrew dependencies. * `--casks`: `list` Homebrew Cask dependencies. diff --git a/manpages/brew.1 b/manpages/brew.1 index 3c878e3ef3..26a4c4c322 100644 --- a/manpages/brew.1 +++ b/manpages/brew.1 @@ -366,8 +366,8 @@ List files which would be linked or deleted by \fBbrew link \-\-overwrite\fR wit \fB\-f\fR, \fB\-\-force\fR Allow keg\-only formulae to be linked\. . -.SS "\fBlist\fR, \fBls\fR [\fIoptions\fR] [\fIformula\fR]" -List all installed formulae\. +.SS "\fBlist\fR, \fBls\fR [\fIoptions\fR] [\fIformula|cask\fR]" +List all installed formulae or casks . .P If \fIformula\fR is provided, summarise the paths within its current keg\. @@ -393,8 +393,12 @@ Only show formulae with multiple versions installed\. Show the versions of pinned formulae, or only the specified (pinned) formulae if \fIformula\fR are provided\. See also \fBpin\fR, \fBunpin\fR\. . .TP -\fB\-\-cask\fR -List casks +\fB\-\-formulae\fR +List only formulae\. +. +.TP +\fB\-\-casks\fR +List only casks\. . .TP \fB\-1\fR @@ -468,8 +472,8 @@ Show options for all available formulae\. \fB\-\-command\fR Show options for the specified \fIcommand\fR\. . -.SS "\fBoutdated\fR [\fIoptions\fR] [\fIformula\fR]" -List installed formulae that have an updated version available\. By default, version information is displayed in interactive shells, and suppressed otherwise\. +.SS "\fBoutdated\fR [\fIoptions\fR] [\fIformula\fR|\fIcask\fR]" +List installed casks and formulae that have an updated version available\. By default, version information is displayed in interactive shells, and suppressed otherwise\. . .TP \fB\-q\fR, \fB\-\-quiet\fR @@ -480,6 +484,14 @@ List only the names of outdated kegs (takes precedence over \fB\-\-verbose\fR)\. Include detailed version information\. . .TP +\fB\-\-formulae\fR +Only output outdated formulae\. +. +.TP +\fB\-\-casks\fR +Only output outdated casks\. +. +.TP \fB\-\-json\fR Print output in JSON format\. There are two versions: v1 and v2\. v1 is deprecated and is currently the default if no version is specified\. v2 prints outdated formulae and casks\. . @@ -491,14 +503,6 @@ Fetch the upstream repository to detect if the HEAD installation of the formula \fB\-\-greedy\fR Print outdated casks with \fBauto_updates\fR or \fBversion :latest\fR\. . -.TP -\fB\-\-formula\fR -Treat all arguments as formulae\. -. -.TP -\fB\-\-cask\fR -Treat all arguments as casks\. -. .SS "\fBpin\fR \fIformula\fR" Pin the specified \fIformula\fR, preventing them from being upgraded when issuing the \fBbrew upgrade\fR \fIformula\fR command\. See also \fBunpin\fR\. . @@ -696,8 +700,8 @@ Fetch and reset Homebrew and all tap repositories (or any specified \fIrepositor .P \fINote:\fR this will destroy all your uncommitted or committed changes\. . -.SS "\fBupgrade\fR [\fIoptions\fR] [\fIformula\fR]" -Upgrade outdated, unpinned formulae using the same options they were originally installed with, plus any appended brew formula options\. If \fIformula\fR are specified, upgrade only the given \fIformula\fR kegs (unless they are pinned; see \fBpin\fR, \fBunpin\fR)\. +.SS "\fBupgrade\fR [\fIoptions\fR] [\fIformula\fR|\fIcask\fR]" +Upgrade outdated casks and outdated, unpinned formulae using the same options they were originally installed with, plus any appended brew formula options\. If \fIcask\fR or \fIformula\fR are specified, upgrade only the given \fIcask\fR or \fIformula\fR kegs (unless they are pinned; see \fBpin\fR, \fBunpin\fR)\. . .P Unless \fBHOMEBREW_NO_INSTALL_CLEANUP\fR is set, \fBbrew cleanup\fR will then be run for the upgraded formulae or, every 30 days, for all formulae\. @@ -707,6 +711,14 @@ Unless \fBHOMEBREW_NO_INSTALL_CLEANUP\fR is set, \fBbrew cleanup\fR will then be If brewing fails, open an interactive debugging session with access to IRB or a shell inside the temporary build directory\. . .TP +\fB\-\-formulae\fR +Only upgrade outdated formulae\. +. +.TP +\fB\-\-casks\fR +Only upgrade outdated casks\. +. +.TP \fB\-s\fR, \fB\-\-build\-from\-source\fR Compile \fIformula\fR from source even if a bottle is available\. . @@ -785,7 +797,7 @@ Show usage of \fIformula\fR by development builds\. \fB\-\-HEAD\fR Show usage of \fIformula\fR by HEAD builds\. . -.SS "\fB\-\-cache\fR [\fIoptions\fR] [\fIformula\fR]" +.SS "\fB\-\-cache\fR [\fIoptions\fR] [\fIformula|cask\fR]" Display Homebrew\'s download cache\. See also \fBHOMEBREW_CACHE\fR\. . .P @@ -800,11 +812,11 @@ Show the cache file used when building from source\. Show the cache file used when pouring a bottle\. . .TP -\fB\-\-formula\fR +\fB\-\-formulae\fR Only show cache files for formulae\. . .TP -\fB\-\-cask\fR +\fB\-\-casks\fR Only show cache files for casks\. . .SS "\fB\-\-caskroom\fR [\fIcask\fR]" @@ -1569,7 +1581,7 @@ Read the \fBBrewfile\fR from \fB~/\.Brewfile\fR\. \fBlist\fR all dependencies\. . .TP -\fB\-\-brews\fR +\fB\-\-formulae\fR \fBlist\fR Homebrew dependencies\. . .TP