From 21afd17f2f5be051e50c5fb309ab18607834d42e Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Sat, 25 Nov 2017 19:46:48 +0100 Subject: [PATCH] docs: document good and problematic option placements, see #3356 (cherry picked from commit e3cb7c3c32620e36b792e99972167925c8bfbedf) --- docs/usage_general.rst.inc | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/usage_general.rst.inc b/docs/usage_general.rst.inc index c87a8b8b4..4c704d8f0 100644 --- a/docs/usage_general.rst.inc +++ b/docs/usage_general.rst.inc @@ -1,3 +1,20 @@ +Positional Arguments and Options: Order matters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Borg only supports taking options (``-s`` and ``--progress`` 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 create -s --progress repo::archive path # good and preferred + borg create repo::archive path -s --progress # also works + borg create -s repo::archive path --progress # works, but ugly + borg create repo::archive -s --progress path # BAD + +This is due to a problem in the argparse module: http://bugs.python.org/issue15112 + + Repository URLs ~~~~~~~~~~~~~~~