Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP


Change the docopt error message format #43

ghost opened this Issue · 8 comments

1 participant


Currently, docopt reports errors as follows:

-o is not recognized
--opt is not recognized
--o requires argument
--opt requires argument
--opt is not a unique prefix: --option, --optimum?
--opt must not have an argument

All followed by a listing of the usage patterns. However, a cursory sample of command-line utilities on my box use the following format:

program: invalid option -- 'o'
program: unrecognised option '--o'
program: option requires an argument -- 'o'
program: option '--option' requires an argument
program: option '--opt' is ambiguous; possibilities: '--option' '--optimum'
program: option '--option' doesn't allow an argument

All followed by Try 'program --help' for more information., which I think looks way better (although that might just be my Ubuntu bias talking.) At the very least, I think docopt should prefix program: to the error messages it outputs, though this might cause some complications if #41 ever gets implemented. Opinions?


Also, if the error message format changes significantly, it would be useful to provide a method like docopt.exit(message) as syntactic sugar for raise DocoptExit, message in order to maintain a consistent look among the error messages a docopt-using program can send; being able to specify the exit code would also be nice.


I agree, that changing error message format is required; right now the format is ad-hoc.

However a research has to be done:

  1. is there anything in POSIX standards that say how error should look like?
  2. what are the alternative conventions?

Another thing: should the argv[0] be printed as program's name or a word after "usage: "?


Another consideration with program: error message style errors is if we want to support softlink aliases with docopt programs; though this would also require a change like shabbyrobe in #41 suggested lest invocations like alias --help produce confusing output.

If we go with softlink support, the program in program: error message should absolutely be sys.argv[0]; if not, it should be the last word in a multi-word program name, since all multi-word program names are just (I think?) <interpreter name> <interpreter arguments>... <program name proper>.


@halst: Regarding point 1, the answer seems to be "not really": there's a few examples scattered here and there in the examples for getopt() and getsubopt(), but nothing really concrete. I suppose the closest comes the following extract from the getopts page:

Only a rare application program intercepts a getopts standard error message and wants to parse it. Therefore, implementations are free to choose the most usable messages they can devise. The following formats are used by many historical implementations:

"%s: illegal option -- %c\n", <program name>, <option character>
"%s: option requires an argument -- %c\n", <program name>, \
    <option character>

Which is pretty similar to what I posted, give or take a few quotes and the word invalid/illegal. However, docopt supports long options and POSIX does not, so I think we need to look farther than that for reference.


The above getopts format feels awkward because of the double dash.

I'm ready to pull whatever consistent error format you come up with.


Ok, so POSIX is not strict on error messages, so what about using : instead of --:

prog: illegal option: -o
prog: illegal option: --opt
prog: option requires an argument: -o
prog: option requires an argument: --opt
prog: not a unique prefix: --opt; did you mean: --option, --optimum?
prog: option should not have an argument: --opt

Looks good, though I prefer the GNU getopt wording for the last two:

program: option --opt is ambiguous; possibilities: --option, --optimum
program: option --option doesn't allow an argument

As seen above, let's continue this discussion in #63.

@ghost ghost closed this
This issue was closed.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.