How To Use grep To Search The --help Output To Find Out What CLI Arguments That Begin With A Dash Do
Ever seen a command with a long list of cryptic, one letter arguments that begin with dash / hyphen, and wanted a quick way to find out what each command line argument does? This article explains how to do this.
Find out what a SINGLE command line argument that begins with a dash does by searching the program's --help
Using grep to search the --help output like this fails:
$ rm --help | grep -r
Usage: grep [OPTION]... PATTERNS [FILE]...
Try 'grep --help' for more information.That's because grep treats -r as an argument for itself, and not as a search pattern. So what's the correct way of using grep to search the --help output for arguments starting with a dash?
Let's start with a simple example with only one command line argument that begins with a dash / hyphen. Say we want to find out what the -r argument means from the rm -r command. Search the rm --help using grep as follows:
rm --help | grep -w -- -rWhich outputs the following:
-r, -R, --recursive remove directories and their contents recursively
By default, rm does not remove directories. Use the --recursive (-r or -R)-- is very important here. The double dash (--) signals the end of options for that particular command (the end of the command line flags), after which only positional arguments are accepted. This way, grep doesn't try to interpret what follows the double dash as an option/flag.
The grep -w argument is used to match only whole words, so for example it only matches -r, and not -rSOMETHING.
An alternative you can use instead of the double dash is -e. For example, grep -w -e -r (or grep -we -r) would have the same result as grep -w -- -r in the example above. -e allows specifying a search pattern, and it can be used to protect a pattern beginning with a dash (-). Other ways of achieving this is to escape the argument's dash using \\ (e.g. \\-r), using "\-r", etc.
This also works with command line arguments that begin with 2 dashes, but I didn't use that in an example since those arguments are usually self-explanatory (e.g. --help).
Find out what MULTIPLE one letter command line arguments do by searching the program's --help
For the second example we'll use grep to search rm --help for what the -r and -f options do, in one go:
rm --help | grep -w -- '-[rf]'Which has the following output:
-f, --force ignore nonexistent files and arguments, never prompt
-r, -R, --recursive remove directories and their contents recursively
By default, rm does not remove directories. Use the --recursive (-r or -R)-[rf] is a regex, used to look for both -r and -f arguments. You can add as many command line arguments as you want between [], and not just 2.
To make this easier to use, you could add the following simple function I just created to your ~/.bashrc or ~/.zsh:
function argshelp() {
ARGS="${@:2}"
$1 --help | grep -w -- "^ -[$ARGS]"
}And then use (after sourcing the file, e.g. source ~/.bashrc) the following to search the help of a COMMAND to see the explanation of ARGUMENTS:
argshelp COMMAND ARGUMENTSExample:
argshelp rm rfOr:
argshelp ls l aAs you can see, when using this function, the command parameters must not begin with a dash. You can specify the parameters both separated by a space or together. Also, you can rename this function to anything you like (just make sure it's not already used by a command, alias, etc.).
You might also like: How To Find Files Modified In The Last N Days Or Minutes Using find
Extras
It's worth noting that in some cases, even using the -w (match only whole words) grep argument, you may still get unwanted matches. E.g. you may only want the -l argument explanation from ls --help, and yet ls --help | grep -w -- -l outputs:
--author with -l, print the author of each file
--block-size=SIZE with -l, scale sizes by SIZE when printing them;
with -l: show ctime and sort by name;
--format=WORD across -x, commas -m, horizontal -x, long -l,
single-column -1, verbose -l, vertical -C
--full-time like -l --time-style=full-iso
-g like -l, but do not list owner
-h, --human-readable with -l and -s, print sizes like 1K 234M 2G etc.
-l use a long listing format
-n, --numeric-uid-gid like -l, but list numeric user and group IDs
-o like -l, but do not list group information
with -l, WORD determines which time to show;
--time-style=TIME_STYLE time/date format with -l; see TIME_STYLE below
with -l: show access time and sort by name;Since most --help pages have arguments starting with two spaces, you could make use of this information to only catch lines that begin with that particular command line argument, and exclude other matches (example for the same ls command):
- To search for a single command line argument (
-l):
ls --help | grep -w -- '^ -l'Which outputs:
-l use a long listing format- To search for multiple command line arguments (
-land-a):
ls --help | grep -w -- '^ -[la]'Which has the following output:
-a, --all do not ignore entries starting with .
-l use a long listing format^ indicates to only match lines starting with what follows the ^ symbol; here, ^ is followed by 2 spaces.
It's possible for the help of a command line tool to explain what an argument does on multiple lines. In that case, you can tell grep to list extra lines below the matched line, using -A (from the grep help: -A NUM "prints NUM lines of trailing context"). For example, to search the cp command help for what the -f option does, and print 2 lines of trailing context, use:
cp --help | grep -w -A2 -- -fWhich has this output:
-f, --force if an existing destination file cannot be
opened, remove it and try again (this option
is ignored when the -n option is also used)I also have to mention explainshell.com here, a website where you can write down a command to see the help text that matches each argument.
You may also like: How To Repeat A Command Every X Seconds On Linux
via @nixcraft
