Repository: borgbackup/borg

Issue:
recreate: --list: point user to "Item Flags" in borg help create
<!--
Thank you for reporting an issue.

*IMPORTANT* -  *before* creating a new issue please look around:
 - Borgbackup documentation: http://borgbackup.readthedocs.io/en/stable/index.html
 - FAQ: https://borgbackup.readthedocs.io/en/stable/faq.html
 and
 - open issues in Github tracker: https://github.com/borgbackup/borg/issues
  
If you cannot find a similar problem, then create a new issue.

Please fill in as much of the template as possible.
-->

## Have you checked borgbackup docs, FAQ, and open Github issues?

Yes

## Is this a BUG / ISSUE report or a QUESTION?

Feature request (documentation improvement)

## System information. For client/server mode post info for both machines.

#### Your borg version (borg -V).

```
backup ~ # borg -V
borg 1.1.9
```

#### Operating system (distribution) and version.

```
backup ~ # lsb_release -a
No LSB modules are available.
Distributor ID: Debian
Description:    Debian GNU/Linux 10 (buster)
Release:        10
Codename:       buster
backup ~ # cat /etc/debian_version
10.3
```

## Describe the problem you're observing.

The `recreate` documentation (`borg help recreate` and `man borg-recreate`) recommends to use the options `--dry-run --verbose --list` to test a `recreate` before actually doing it:

```
USE WITH CAUTION.
Depending on the PATHs and patterns given, recreate can be used to permanently
delete files from archives.
When in doubt, use --dry-run --verbose --list to see how patterns/PATHS are
interpreted.
```

Unfortunately it doesn't really explain how to interpret the output. From fiddling around with it I quickly figured out that filenames seem to be prefixed with either `-` or `x`, but I had a hard time finding the documentation that explains these characters (neither `-`, `x` nor `list` are easy to google^^). Guessing is pretty much a no-go here (`-` could as much be a simple list indicator like in it works Markdown, but also very well indicate subtraction, ie. "this file is going to be removed from the archive").

I finally found it in `borg help create`, in the section `Item flags`:

```
- '-' = dry run, item was not backed up
- 'x' = excluded, item was not backed up
```

The `borg help recreate` docs should point the user there so that this is easier to figure out :)


Discussion:
These are generic flags explained somewhere else in the docs (`borg create` or `common` sections maybe).
todo: add some links to docs.
I'll have a look into it, maybe we can restructure the docs a bit and put "Item flags" in a more central section, referencing to it from the individual commands.

Resolving patch:
diff --git a/src/borg/archiver.py b/src/borg/archiver.py
--- a/src/borg/archiver.py
+++ b/src/borg/archiver.py
@@ -2672,6 +2672,7 @@ def build_parser(self):
         # It will replace the entire :ref:`foo` verbatim.
         rst_plain_text_references = {
             'a_status_oddity': '"I am seeing ‘A’ (added) status for a unchanged file!?"',
+            'list_item_flags': '"Item flags"',
         }
 
         def process_epilog(epilog):
@@ -3319,6 +3320,8 @@ def define_archive_filters_group(subparser, *, sort_by=True, first_last=True):
         and not include any other contents of the containing folder, this can be enabled
         through using the ``--keep-exclude-tags`` option.
 
+        .. _list_item_flags:
+
         Item flags
         ++++++++++
 
@@ -3949,7 +3952,7 @@ def define_archive_filters_group(subparser, *, sort_by=True, first_last=True):
         Depending on the PATHs and patterns given, recreate can be used to permanently
         delete files from archives.
         When in doubt, use ``--dry-run --verbose --list`` to see how patterns/PATHS are
-        interpreted.
+        interpreted. See :ref:`list_item_flags` in ``borg create`` for details.
 
         The archive being recreated is only removed after the operation completes. The
         archive that is built during the operation exists at the same time at


Test patch: