getopts is a bash builtin for parsing options in a script or function: -v, -o file, combined -vo file. You call it in a while loop: each call extracts one option, puts its letter into a variable and the option's argument into OPTARG. getopts can't handle long options (--verbose) — for those there's the external getopt utility or manual parsing with case. Help — help getopts.
Syntax
while getopts 'optstring' name; do
case $name in
…
esac
done
shift $((OPTIND - 1)) # drop the parsed options, leaving the positional arguments
Option string
| Notation | Meaning |
|---|
vh | options -v and -h without arguments |
o: | option -o with a required argument: -o file or -ofile |
:vo: | a colon at the start — silent mode: errors aren't printed, your case handles them |
Variables
| Variable | What it holds |
|---|
name (from getopts … name) | the letter of the option found; ? — unknown option; : — missing argument (silent mode only) |
OPTARG | the option's argument; in silent mode on error — the offending letter itself |
OPTIND | index of the next argument to parse; 1 at the start of the script |
OPTERR=0 | disable error messages without enabling silent mode |
Errors: normal and silent mode
| Situation | Normal mode (vo:) | Silent mode (:vo:) |
|---|
unknown option -x | prints illegal option -- x, name=?, OPTARG unset | silent, name=?, OPTARG=x |
-o without an argument | prints option requires an argument -- o, name=? | silent, name=:, OPTARG=o |
getopts returns code 1 and the loop ends when the options run out: it hit the first argument not starting with -, a standalone --, or the end of the arguments.
Examples
#!/bin/bash
# a script with options: -v, -o file, -h
usage() { echo "usage: $0 [-v] [-o file] argument…" >&2; }
verbose=0
out=/dev/stdout
while getopts ':vo:h' opt; do
case $opt in
v) verbose=1 ;;
o) out=$OPTARG ;;
h) usage; exit 0 ;;
:) echo "option -$OPTARG requires an argument" >&2; usage; exit 2 ;;
\?) echo "unknown option -$OPTARG" >&2; usage; exit 2 ;;
esac
done
shift $((OPTIND - 1))
(( $# > 0 )) || { usage; exit 2; }
echo "verbose=$verbose out=$out arguments: $*"
# how this script parses different calls
./script.sh -v -o res.txt a b # verbose=1 out=res.txt arguments: a b
./script.sh -vores.txt a # same: options combined, argument attached
./script.sh -- -v # after -- everything is an argument: arguments: -v
./script.sh a -v # parsing stops at a: -v is a regular argument
# a repeatable option: collect the values into an array
tags=()
while getopts 't:' opt; do
[[ $opt == t ]] && tags+=("$OPTARG")
done
# getopts in a function: reset OPTIND, otherwise the second call parses nothing
f() {
local OPTIND opt
while getopts 'a' opt; do echo "option $opt"; done
}
f -a; f -a
# long options — via the external getopt (util-linux)
args=$(getopt -o vo: -l verbose,output: -- "$@") || exit 2
eval set -- "$args"
while true; do
case $1 in
-v|--verbose) verbose=1; shift ;;
-o|--output) out=$2; shift 2 ;;
--) shift; break ;;
esac
done
getopts or getopt
| getopts (builtin) | getopt (util-linux) |
|---|
long options --name | no | yes: -l name,output: |
options after arguments (file -v) | no, parsing stops | yes, moves options to the front |
| portability | any POSIX shell | Linux with util-linux only |
| how to use | a while getopts loop | eval set -- "$(getopt …)", then a loop over $1 |
Pitfalls
- Forgotten
shift $((OPTIND - 1)). Without it $1 still points to the first option, not the first positional argument.
getopts doesn't understand long options. It parses --verbose as a set of letters -, v, e, r, … and reports an error for each unknown one. Need long options — use getopt.
- The next word becomes the option's argument, even if it looks like an option.
-o -v gives OPTARG=-v, and -v as a separate option doesn't take effect.
- Parsing stops at the first positional argument. In
script.sh file -v the -v option isn't recognized. Put options before arguments.
OPTIND doesn't reset on its own. In a function called several times, declare local OPTIND, otherwise the second call won't see the options.
? in case must be escaped: \?) or '?'). Without that, ?) is the pattern "any single character" and matches every option.
- Check
getopt's exit code before eval: args=$(getopt …) || exit 2. On an unknown option getopt prints an error and returns 1.
See also
functions · conditions-loops · variables · exit-codes