I often find myself man'ing a command just to learn about one specific option. Most of the time I can search to the option just fine, unless it's something like ffmpeg or gcc where I have to step through about 40 matches until I get to the actual description of the option...

Sometimes I can get lucky and search for the word "options" to get close and then refine it from there, but it would be nice if I could reliably jump straight to the option in question. It would be cool if there was a tool that could parse out the options and build a database on which you could do searches, but after looking at the groff markup for a few pages I've determined it would only be a best-guess effort due to the lack of meta-information in groff markup... In my ideal world woman mode in emacs would support searching for specific options... :)

Any tips for jumping straight to a specific option in a man page?


Here's my script to do it. It's called he.

$ he cp    
       cp [OPTION]... [-T] SOURCE DEST
       cp [OPTION]... -t DIRECTORY SOURCE...

$ he gcc -dD
       -dD Dump all macro definitions, at the end of preprocessing, in addition to normal output.

$ he rsync -v
        -v, --verbose               increase verbosity

$ he bash getopts
       getopts optstring name [args]
              getopts is used by shell procedures to parse positional parameters.  optstring contains the option characters to be recognized; if a character is  followed  by  a  colon,  the  option  is
              expected  to  have  an  argument, which should be separated from it by white space.  The colon and question mark characters may not be used as option characters.  Each time it is invoked,
              getopts places the next option in the shell variable name, initializing name if it does not exist, and the index of the next argument to be processed into the variable OPTIND.  OPTIND  is
              initialized  to  1 each time the shell or a shell script is invoked.  When an option requires an argument, getopts places that argument into the variable OPTARG.  The shell does not reset
              OPTIND automatically; it must be manually reset between multiple calls to getopts within the same shell invocation if a new set of parameters is to be used.

              When the end of options is encountered, getopts exits with a return value greater than zero.  OPTIND is set to the index of the first non-option argument, and name is set to ?.

              getopts normally parses the positional parameters, but if more arguments are given in args, getopts parses those instead.

              getopts can report errors in two ways.  If the first character of optstring is a colon, silent error reporting is used.  In normal operation diagnostic messages are printed  when  invalid
              options or missing option arguments are encountered.  If the variable OPTERR is set to 0, no error messages will be displayed, even if the first character of optstring is not a colon.

              If  an  invalid  option  is  seen, getopts places ? into name and, if not silent, prints an error message and unsets OPTARG.  If getopts is silent, the option character found is placed in
              OPTARG and no diagnostic message is printed.

              If a required argument is not found, and getopts is not silent, a question mark (?) is placed in name, OPTARG is unset, and a diagnostic message is printed.  If getopts is silent, then  a
              colon (:) is placed in name and OPTARG is set to the option character found.

              getopts returns true if an option, specified or unspecified, is found.  It returns false if the end of options is encountered or an error occurs.

But if you don't have access to a script like that, just run less, then type /^ *-option (note the space), for example, in the gcc man page, type /^ *-dDEnter to find the documentation for the -dD option.

This works because the option usually appears at the start of the line.

  • 1
    Imagine a big bearded bear man kissing your toes for this! – sepehr Nov 2 '14 at 5:46
  • Ha ha! Thanks! Also note that I renamed the script to he, as in "short help". The latest version is on github – Mikel Nov 2 '14 at 14:52

This is the function I use. I call it "mans" for "man search".

mans ()
    local pages string;
    if [[ -n $2 ]]; then
    man ${2:+--pager="less -p \"$string\" -G"} ${pages[@]}


$ mans ^OPTIONS grep find xargs
  • Sweet! Not exactly the "ideal" lookup-table type solution I was hoping for, but still very useful. Thanks. – mgalgs Mar 4 '11 at 7:24
  • 1
    As noted below, most of the time what you're looking for is at the start of the line after some indentation, so the pattern will usually look like mans '^ *<something>' <page>. See my answer for more details. – Mikel Mar 4 '11 at 8:32

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.