Repository: borgbackup/borg

Issue:
borg recreate and --exclude-if-present flag behavior isn't very clear
## Have you checked borgbackup docs, FAQ, and open Github issues?

Yes

## Is this a BUG / ISSUE report or a QUESTION?

Documentation Bug, IMO

## System information. For client/server mode post info for both machines.
Linux home-desktop 5.3.0-53-generic #47~18.04.1-Ubuntu SMP Thu May 7 13:10:50 UTC 2020 x86_64 x86_64 x86_64 GNU/Linux
Distro - KDE Neon

#### Your borg version (borg -V).
borg 1.1.11

#### Hardware / network configuration, and filesystems used.
ext4, local disk

#### How much data is handled by borg?
12Gig repo

#### Full borg commandline that lead to the problem (leave away excludes and passwords)
borg recreate --exclude-if-present .nobackup /data/borg-backup

## Describe the problem you're observing.
So I figured that there was a lot of cruft built up and my overall backup size had grown a lot (12G),
Mounting the backup, it was clear that a lot of thing in my home folder were the problem
for instance: `/home/raghu/.arduino15` isn't a folder I need. Ditto for `/home/raghu/code/go`
For my nightly backups, I have `borg create <archive> --exclude-if-present .nobackup /home /etc` and my preference is to exclude folders with a `touch /path/to/exclude/.nobackup` 

So, before running recreate, I dropped a lot of `.nobackup`  files into folders that I needed to delete. In my mind, I figure that these folders will be excluded by virtue of me dropping `.nobackup` files into the folders. It doesn't work of course. 

Obviously (well, not obvious at all - took me more than a day), the penny finally drops and I realize that recreate ONLY looks at the files/folders already IN the archive - and won't touch the fs at all.

So now, I've reverted to using `--exclude-from-file` - but the behavior of  `--exclude-if-present` should really be highlighted in the documentation on the `recreate` page.

<!--

If this complaint relates to borg performance, please include CRUD benchmark
results and any steps you took to troubleshoot.
How to run benchmark: http://borgbackup.readthedocs.io/en/stable/usage/benchmark.html

*IMPORTANT* - Please mark logs and text output from terminal commands 
or else Github will not display them correctly. 
An example is provided below.

Example:
```
this is an example how log text should be marked (wrap it with ```)
```
-->



Discussion:

Resolving patch:
diff --git a/src/borg/archiver.py b/src/borg/archiver.py
--- a/src/borg/archiver.py
+++ b/src/borg/archiver.py
@@ -4092,9 +4092,10 @@ def define_borg_mount(parser):
 
         Important: Repository disk space is **not** freed until you run ``borg compact``.
 
-        ``--exclude``, ``--exclude-from``, ``--exclude-if-present``, ``--keep-exclude-tags``, and PATH
-        have the exact same semantics as in "borg create". If PATHs are specified the
-        resulting archive will only contain files from these PATHs.
+        ``--exclude``, ``--exclude-from``, ``--exclude-if-present``, ``--keep-exclude-tags``
+        and PATH have the exact same semantics as in "borg create", but they only check
+        for files in the archives and not in the local file system. If PATHs are specified,
+        the resulting archives will only contain files from these PATHs.
 
         Note that all paths in an archive are relative, therefore absolute patterns/paths
         will *not* match (``--exclude``, ``--exclude-from``, PATHs).


Test patch: