Offensive Security Researcher & Quantum Cryptography Analyst

How to Use ‘getopts’ for Command Line Options in Bash

Abdul Wahab Junaid
How to Use 'getopts' for Command Line Options in Bash

How to Use 'getopts' for Command Line Options in Bash

For a long time, I handled command-line arguments in my scripts with a messy chain of if [ "$1" == "-x" ] statements, and it always fell apart the moment I needed to support combined flags or optional values. Once I actually sat down and learned getopts properly, my scripts became dramatically cleaner and more predictable. This article covers everything I wish someone had explained to me the first time around.

Why Use getopts Instead of Manual Parsing

Bash’s built-in getopts command exists specifically to parse command-line options in a standard, POSIX-compliant way. Compared to manually parsing $1, $2, etc., it gives you:

The Basic Syntax

while getopts "abc:" opt; do
    case "$opt" in
        a) echo "Option -a triggered" ;;
        b) echo "Option -b triggered" ;;
        c) echo "Option -c triggered with value: $OPTARG" ;;
        *) echo "Unknown option" ;;
    esac
done

Breaking Down the Option String

The string "abc:" defines which options are valid:

A Complete Practical Example

Let’s build a script that supports a filename input, a verbosity flag, and a help flag:

#!/bin/bash

set -euo pipefail

verbose=false
input_file=""

usage() {
    echo "Usage: $0 [-v] [-h] -f <input_file>"
    echo "  -f <file>   Specify input file (required)"
    echo "  -v          Enable verbose output"
    echo "  -h          Show this help message"
    exit 1
}

while getopts "f:vh" opt; do
    case "$opt" in
        f) input_file="$OPTARG" ;;
        v) verbose=true ;;
        h) usage ;;
        \?) echo "Invalid option: -$OPTARG" >&2; usage ;;
        :) echo "Option -$OPTARG requires an argument." >&2; usage ;;
    esac
done

if [ -z "$input_file" ]; then
    echo "Error: input file is required." >&2
    usage
fi

if [ "$verbose" = true ]; then
    echo "Verbose mode enabled."
    echo "Processing file: $input_file"
fi

echo "Done processing $input_file"

How This Works Internally

Silent vs. Verbose Error Handling

By default, getopts prints its own error messages when it encounters invalid options. If you prefix your option string with a colon, you switch to “silent” mode, letting you handle errors yourself:

while getopts ":f:vh" opt; do
    case "$opt" in
        f) input_file="$OPTARG" ;;
        v) verbose=true ;;
        h) usage ;;
        \?) echo "Error: invalid option -$OPTARG" >&2; exit 1 ;;
        :) echo "Error: option -$OPTARG requires an argument" >&2; exit 1 ;;
    esac
done

Notice the leading : in ":f:vh" — this small detail changes how getopts reports errors, giving you full control over the messaging instead of relying on its default (less friendly) output.

Handling Remaining Positional Arguments

After processing named options, you often want to handle whatever arguments are left over (positional arguments):

#!/bin/bash

set -euo pipefail

while getopts ":vf:" opt; do
    case "$opt" in
        v) verbose=true ;;
        f) input_file="$OPTARG" ;;
        \?) echo "Invalid option: -$OPTARG" >&2; exit 1 ;;
        :) echo "Option -$OPTARG requires an argument" >&2; exit 1 ;;
    esac
done

shift $((OPTIND - 1))

echo "Remaining positional arguments: $@"

Why shift $((OPTIND - 1)) Matters

OPTIND is a special variable that getopts updates automatically — it tracks the index of the next argument to be processed. After the loop finishes, OPTIND - 1 tells you how many arguments were consumed as options. Shifting by that amount leaves only the genuine positional arguments in $@, ready for further processing.

Supporting Long Options (GNU-Style --verbose)

getopts only supports single-character options natively — it has no built-in support for long-form flags like --verbose. To support both short and long options, many script authors write a small manual pre-processing step:

#!/bin/bash

set -euo pipefail

verbose=false
input_file=""

for arg in "$@"; do
    case "$arg" in
        --verbose) set -- "$@" "-v" ;;
        --file=*) set -- "$@" "-f" "${arg#*=}" ;;
        *) set -- "$@" "$arg" ;;
    esac
done

while getopts ":vf:" opt; do
    case "$opt" in
        v) verbose=true ;;
        f) input_file="$OPTARG" ;;
        \?) echo "Invalid option: -$OPTARG" >&2; exit 1 ;;
        :) echo "Option -$OPTARG requires an argument" >&2; exit 1 ;;
    esac
done

echo "Verbose: $verbose"
echo "Input file: $input_file"

This is a common (if slightly hacky) pattern: translate long options into their short equivalents first, then let getopts handle the rest normally. For more sophisticated long-option parsing, some scripts instead reach for the external getopt (note: no “s”) utility, which natively supports long options — but it behaves differently across systems (GNU vs. BSD versions), so it’s less portable than the built-in getopts.

A Full Real-World Script Example

Here’s a backup script that ties everything together:

#!/bin/bash

set -euo pipefail

source_dir=""
dest_dir=""
compress=false
verbose=false

usage() {
    cat <<EOF
Usage: $0 -s <source_dir> -d <dest_dir> [-c] [-v]
  -s <dir>   Source directory to back up (required)
  -d <dir>   Destination directory (required)
  -c         Compress the backup using gzip
  -v         Enable verbose output
  -h         Show this help message
EOF
    exit 1
}

while getopts ":s:d:cvh" opt; do
    case "$opt" in
        s) source_dir="$OPTARG" ;;
        d) dest_dir="$OPTARG" ;;
        c) compress=true ;;
        v) verbose=true ;;
        h) usage ;;
        \?) echo "Invalid option: -$OPTARG" >&2; usage ;;
        :) echo "Option -$OPTARG requires an argument." >&2; usage ;;
    esac
done

if [ -z "$source_dir" ] || [ -z "$dest_dir" ]; then
    echo "Error: both -s and -d are required." >&2
    usage
fi

timestamp=$(date +%Y%m%d_%H%M%S)
archive_name="backup_${timestamp}.tar"
[ "$compress" = true ] && archive_name="${archive_name}.gz"

if [ "$verbose" = true ]; then
    echo "Backing up '$source_dir' to '$dest_dir/$archive_name'"
fi

if [ "$compress" = true ]; then
    tar -czf "$dest_dir/$archive_name" -C "$source_dir" .
else
    tar -cf "$dest_dir/$archive_name" -C "$source_dir" .
fi

echo "Backup complete: $dest_dir/$archive_name"

Usage:

./backup.sh -s /home/user/data -d /backups -c -v

Real-World Use Cases

Best Practices

Security Considerations

Optimization Tips

Troubleshooting Common Issues

Problem: getopts doesn’t recognize an option that looks correct. Double-check your option string — a missing colon after an option that requires an argument is one of the most common mistakes.

Problem: Positional arguments aren’t being read correctly after option parsing. You likely forgot to run shift $((OPTIND - 1)) after the getopts loop, leaving already-processed option arguments still in $@.

Problem: Long options like --verbose aren’t recognized. This is expected — getopts only supports single-character short options natively. Add a pre-processing translation step, or use the external getopt utility for native long-option support.

Problem: Script behaves differently when called with combined flags like -vf file.txt. This is actually correct getopts behavior — combined single-character flags are supported by design, as long as the option requiring an argument (f) is placed last in the combined group.

Common Mistakes to Avoid

Frequently Asked Questions

What’s the difference between getopts (built-in) and getopt (external command)? getopts is a Bash built-in that only supports short, single-character options, but works identically across all POSIX-compliant shells. getopt is a separate external utility that supports long options too, but its behavior varies between GNU and BSD implementations, making it less portable.

Can getopts handle optional arguments (where the argument itself is optional)? Not cleanly — getopts treats an option’s argument as either always required or never present. Handling truly optional arguments requires additional manual logic after the getopts loop.

Why does my script fail silently on unknown options? Check whether your option string starts with a leading colon. Without it, getopts prints its own error message; with it, you’re responsible for handling the \? case yourself, and forgetting to do so can result in silent failures.

Can I use getopts inside a function instead of the main script body? Yes, but remember that OPTIND may need to be reset to 1 before parsing if getopts has already been used elsewhere in the same shell session.

Do I need getopts for a script that only takes one simple positional argument? No — for very simple scripts (one required filename, for example), plain positional parameter handling ($1, $2) is simpler and perfectly adequate. Reach for getopts once you have multiple flags, optional arguments, or combined short options to support.

Summary

getopts transforms sloppy, fragile $1/$2 argument parsing into structured, predictable option handling — support for combined short flags, arguments via $OPTARG, and consistent error reporting all come for free. The details that matter most: use the leading-colon silent-error mode for custom messaging, always shift $((OPTIND - 1)) before handling positional arguments, and remember its one real limitation — no native long-option support — which you can work around with a small pre-processing step if needed.

References

Exit mobile version