borg/docs/usage/general/positional-arguments.rst.inc

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
[DOCS] #4587 – Make Sphinx warnings break docs build general.rst and man_intro.rst both included usage_general.rst.inc, which resulted in three Sphinx warning "WARNING: duplicate label". To prevent this we move all sections of usage_general into own include files and add a second usage_general file without the three labels. 2020-03-16 18:17:16 +00:00			`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`