docs: Clarify the meaning of flags when using borg recreate --dry-run

[goebbe]

Using borg 1.4.0 I want to delete a huge folder (miniforge) from my old archives.

I understand that borg recreate is the correct command for this task and as suggested in the docs I first did a --dry-run --verbose --list to check the consequences of borg recreate:

Simplified example: borg recreate repo --exclude home/user/miniforge3 --dry-run --verbose --list

The result is (as expected) a huge list of items - with flags (x or -):

x home/user/miniforge3
- home/user/Documents

To understand the exact meaning of these flags (in the context of borg recreate), I had a look at the docs: https://borgbackup.readthedocs.io/en/stable/usage/create.html#item-flags and found the following description:

Other flags used include: ‘-’ = dry run, item was not backed up ‘x’ = excluded, item was not backed up

From this description, it seems that all items in my /home/user/* are "not backed up" for different reasons. I believe this is confusing, since in the context of borg recreate, the files are already "backed up" in the (old) archives.

If I interpret the description correctly, then: ‘-’ = dry run, item was not backed up <- in the context of borg recreate: item will remain in the recreated archive(s) ‘x’ = excluded, item was not backed up <- in the context of borg recreate: item will be excluded (i.e. removed) from the recreated archive(s)

Would it be possible to add the following additional description to the docs?

In the context of borg recreate: ‘-’ = dry run, item will remain in the recreated archive(s) ‘x’ = excluded, item will be excluded (i.e. removed) from the recreated archive(s)

[ThomasWaldmann]

The flags description was written with borg create in mind, for borg recreate the interpretation is a bit different.

The - is just telling that it's doing nothing with the item because you used --dry-run, which is totally expected: the purpose of a dry run is not to really do anything.

The x is marking items which got matched by some exclusion pattern. So it's doing nothing with it no matter whether it is a dry run or a real run.

[ThomasWaldmann]

Yes, the docs could be improved and your suggestion sounds good. Can you make a pull request with that?

Hmm, we need to avoid misunderstandings (like that the status char could make someone think that some archive was created although --dry-run was used).

A phrasing that would work for both create and recreate:

‘-’ = dry run, item was not written to the target archive ‘x’ = excluded, item was not written to the target archive

[goebbe]

The docs for the "flags" are currently in the (docs) section "borg create". This kind of explains why the docs (1.4) describe the meaning of "flags" in the context of borg create.

Only now, I realize, that the docs for "flags" look different in the latest borg 2.0: https://borgbackup.readthedocs.io/en/**latest**/usage/create.html#item-flags Other flags used include: ‘+’ = included, item would be backed up (if not in dry-run mode) ‘-’ = excluded, item would not be / was not backed up ‘i’ = backup data was read from standard input (stdin) ‘?’ = missing status code (if you see this, please file a bug report!)

So it seems that the flag ‘x’ has been removed for bog 2.0? Instead, there are ´-´ and ´+´, in borg 2.0 now, with different description.

Does that mean, that with borg recreate, in borg 2.0: ‘+’ = included, item would be backed up (if not in dry-run mode) <- item will remain in archive ‘-’ = excluded, item would not be / was not backed up <- item will be removed from archive

I believe the new descriptions (borg 2.0) work well for both, borg createand borg recreate.

[goebbe]

Yes, the docs could be improved and your suggestion sounds good. Can you make a pull request with that? A phrasing that would work for both create and recreate:

‘-’ = dry run, item was not written to the target archive ‘x’ = excluded, item was not written to the target archive

I believe in the docs (1.4) the confusing part is the "was not written". This does not make sense in the context of borg recreate, since the command can be used to remove items that are already part of the archive(s). What about the following?

‘-’ = dry run, item was not written to the archive ‘x’ = excluded: item would not be / was not written to the archive

I'm not sure if I understand the meaning of the first flag ´-´, though. :-/ Does this flag have the same meaning as the ´+´ flag in borg 2.0?

[ThomasWaldmann]

Maybe we first solve this for borg 1.4 (1.4-maint branch) and the docs visible in that git branch or online there: https://borgbackup.readthedocs.io/en/1.4-maint/

[ThomasWaldmann]

in borg2, borg create --dry-run emits either + (included / to be backed up items) or - (excluded, not to be backed up items). hopefully that is less confusing to users.