From 8db5d1ba9013835ee414d5f75953fe961690c749 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Sat, 9 Dec 2017 02:57:41 +0100 Subject: [PATCH] docs: document good and problematic option placements, see #3356 --- docs/usage.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/usage.rst b/docs/usage.rst index 0daa0aced..3877f27c7 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -12,6 +12,23 @@ command in detail. General ------- +Positional Arguments and Options: Order matters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Borg only supports taking options (``-v`` and ``--list`` in the example) +to the left or right of all positional arguments (``repo::archive`` and ``path`` +in the example), but not in between them: + +:: + + borg extract -v --list repo::archive path # good and preferred + borg extract repo::archive path -v --list # also works + borg extract -v repo::archive path --list # works, but ugly + borg extract repo::archive -v --list path # BAD + +This is due to a problem in the argparse module: http://bugs.python.org/issue15112 + + Repository URLs ~~~~~~~~~~~~~~~