GNU Mailutils Manual (split by section):   Section:   Chapter:FastBack: Programs   Up: Programs   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index

3.1 Command Line

3.1.1 Basic Notions About Command Line Options

Many command line options have two forms, called short and long forms. Both forms are absolutely identical in function; they are interchangeable.

The short form is a traditional form for UNIX utilities. In this form, the option consists of a single dash, followed by a single letter, e.g. -c.

Short options which require arguments take their arguments immediately following the option letter, optionally separated by white space. For example, you might write -f name, or -fname. Here, -f is the option, and name is its argument.

Short options which allow optional arguments take their arguments immediately following the option letter, without any intervening white space characters. This is important, so that the command line parser might discern that the text following option is its argument, not the next command line parameter. For example, if option -d took an optional argument, then -dname would mean the option with its argument (name in this case), and -d name would mean the -d option without any argument, followed by command line argument name.

Short options’ letters may be clumped together, but you are not required to do this. When short options are clumped as a set, use one (single) dash for them all, e.g. -cvl is equivalent to -c -v -l. However, only options that do not take arguments may be clustered this way. If an option takes an argument, it can only be the last option in such a cluster, otherwise it would be impossible to specify the argument for it. Anyway, it is much more readable to specify such options separated.

The long option names are probably easier to memorize than their short counterparts. They consist of two dashes, followed by a multi-letter option name, which is usually selected to be a mnemonics for the operation it requests. For example, --verbose is a long option that increases the verbosity of a utility. In addition, long option names can abbreviated, provided that such an abbreviation is unique among the options understood by a given utility. For example, if a utility takes options --foreground and --forward, then the shortest possible abbreviations for these options are --fore and --forw, correspondingly. If you try to use --for, the utility will abort and inform you that the abbreviation you use is ambiguous, so it is not clear which of the options you intended to use.

Long options which require arguments take those arguments following the option name. There are two ways of specifying a mandatory argument. It can be separated from the option name either by an equal sign, or by any amount of white space characters. For example, if the --file option requires an argument, and you wish to supply name as its argument, then you can do so using any of the following notations: --file=name or --file name.

In contrast, optional arguments must always be introduced using an equal sign.

3.1.2 Options That are Common for All Utilities.

All GNU Mailutils programs understand a common subset of options.

--help
-?

Display a short summary of the command line options understood by this utilities, along with a terse description of each.

The output of this option consists of three major parts. First, a usage synopsis is displayed. For example:

Usage: sieve [OPTION...] SCRIPT
GNU sieve -- a mail filtering tool

The first line tells that the sieve utility takes any number of options (brackets indicate optional part) and a single mandatory argument (‘SCRIPT’). The second lines summarizes the purpose of the utility.

Following this header is an option summary. It consists of two columns:

  -c, --compile-only         Compile script and exit
  -d, --debug[=FLAGS]        Debug flags
  -e, --email=ADDRESS        Override user email address

The leftmost column contains a comma-separated list of option names. Short options are listed first. The options are ordered alphabetically. Arguments, if any, are specified after the last option name in the list, so that, e.g. the option ‘-e’ in the example above requires an argument: ‘-e ADDRESS’. Optional arguments are enclosed in square brackets, as in --debug option in the example above.

The rightmost column contains a short description of the option purpose.

The last part of --help output contains some additional notices and lists the email address for reporting bugs.

--usage

Display a short summary of options. In the contrast to the --help option, only option names and arguments are printed, without any textual description. For example:

Usage: sieve [-cv?V] [--compile-only] [--debug[=FLAGS]]
             [--email=ADDRESS] SCRIPT

The exact formatting of the output produced by these two options is configurable. See Usage Vars, for a detailed descriptions of it.

--version
-V

Print program version and exit.

--show-config-options

Show configuration options used when compiling the package. You can use this option to verify if support for a particular mailbox format or other functionality is compiled in the binary. The output of this option is intended to be both machine-readable and understandable by humans.

The following command line options affect parsing of configuration files. Here we provide a short summary, the next section will describe them in detail.

--config-file=file

Load this configuration file, instead of the default.

--config-help

Show configuration file summary.

--config-lint

Check configuration file syntax and exit

--config-verbose

Verbosely log parsing of the configuration files.

--no-site-config

Do not load site-wide configuration file.

--no-user-config

Do not load user configuration file.

--no-config

Don’t load site-wide and user configuration files.

--set=path=value

Set configuration variable. See the --set option.

GNU Mailutils Manual (split by section):   Section:   Chapter:FastBack: Programs   Up: command line   FastForward: Libraries   Contents: Table of ContentsIndex: Function Index