From 49b9b6cf3fa5d01db46b0645696aca072dfa8665 Mon Sep 17 00:00:00 2001 From: Issy Long Date: Sat, 23 Jan 2021 16:59:33 +0000 Subject: [PATCH] dev-cmd/extract: Improve the usage instructions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - A friend got an error message when trying to use `brew extract` and it wasn't immediately obvious to me why. The usage banner only mentioned the "formula" argument, which they'd provided. This improves the error message when there aren't enough arguments so that others have a chance of figuring out how to use this command without having to look at the code for `extract_args`. Before: ``` ➜ brew extract --version='1.4' libftdi Usage: brew extract [--version=] [--force] formula ... [...] Error: Invalid usage: this command requires a formula argument ``` After: ``` ➜ brew extract --version='1.4' libftdi Usage: brew extract [options] formula tap [...] Error: Invalid usage: This command requires at least 2 named arguments. ``` - I don't like the "at least 2" phrasing here but that's a dive into the arg parsing code that I don't have time for right now. An alternative was `named_args [:formula, :destination_tap]`, but that gave the error message "requires formula or destination_tap" which wasn't great either. I also tried `min: 2, max: 2` and that was the same "at least 2" message. --- Library/Homebrew/dev-cmd/extract.rb | 3 ++- completions/bash/brew | 1 - docs/Manpage.md | 2 +- manpages/brew.1 | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/Library/Homebrew/dev-cmd/extract.rb b/Library/Homebrew/dev-cmd/extract.rb index 59a9519b67..d149fd432a 100644 --- a/Library/Homebrew/dev-cmd/extract.rb +++ b/Library/Homebrew/dev-cmd/extract.rb @@ -83,6 +83,7 @@ module Homebrew sig { returns(CLI::Parser) } def extract_args Homebrew::CLI::Parser.new do + usage_banner "`extract` [<--version>`=`] [<--force>] " description <<~EOS Look through repository history to find the most recent version of and create a copy in `/Formula/``@``.rb`. If the tap is not @@ -95,7 +96,7 @@ module Homebrew switch "-f", "--force", description: "Overwrite the destination formula if it already exists." - named_args :formula, number: 2 + named_args number: 2 end end diff --git a/completions/bash/brew b/completions/bash/brew index 7941e54fee..a086378a02 100644 --- a/completions/bash/brew +++ b/completions/bash/brew @@ -898,7 +898,6 @@ _brew_extract() { return ;; esac - __brew_complete_formulae } _brew_fetch() { diff --git a/docs/Manpage.md b/docs/Manpage.md index bd1bb814fe..f04a6f661c 100644 --- a/docs/Manpage.md +++ b/docs/Manpage.md @@ -1019,7 +1019,7 @@ or open the Homebrew repository for editing if no formula is provided. * `--cask`: Treat all named arguments as casks. -### `extract` [*`--version`*`=`] [*`--force`*] *`formula`* ... +### `extract` [*`--version`*`=`] [*`--force`*] *`formula`* *`tap`* Look through repository history to find the most recent version of *`formula`* and create a copy in *`tap`*`/Formula/`*`formula`*`@`*`version`*`.rb`. If the tap is not diff --git a/manpages/brew.1 b/manpages/brew.1 index e6c0afc127..986c9ce31e 100644 --- a/manpages/brew.1 +++ b/manpages/brew.1 @@ -1417,7 +1417,7 @@ Treat all named arguments as formulae\. \fB\-\-cask\fR Treat all named arguments as casks\. . -.SS "\fBextract\fR [\fI\-\-version\fR\fB=\fR] [\fI\-\-force\fR] \fIformula\fR \.\.\." +.SS "\fBextract\fR [\fI\-\-version\fR\fB=\fR] [\fI\-\-force\fR] \fIformula\fR \fItap\fR" Look through repository history to find the most recent version of \fIformula\fR and create a copy in \fItap\fR\fB/Formula/\fR\fIformula\fR\fB@\fR\fIversion\fR\fB\.rb\fR\. If the tap is not installed yet, attempt to install/clone the tap before continuing\. To extract a formula from a tap that is not \fBhomebrew/core\fR use its fully\-qualified form of \fIuser\fR\fB/\fR\fIrepo\fR\fB/\fR\fIformula\fR\. . .TP