Repository: borgbackup/borg

Issue:
`-a` option of `borg prune` does not seem to accept `sh:` as pattern selector
<!--
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?

ISSUE

## System information. For client/server mode post info for both machines.



#### Your borg version (borg -V)
borg 1.2.4 installed via debian apt.
borg 1.2.6 installed via https://github.com/borgbackup/borg/releases/download/1.2.6/borg-linux64

#### Operating system (distribution) and version.
Linux phoenix 6.1.0-10-amd64 <span>#<span>1 SMP PREEMPT_DYNAMIC Debian 6.1.38-1 (2023-07-14) x86_64 GNU/Linux
KDE Plasma Version: 5.27.5

#### Hardware / network configuration, and filesystems used.
Local, but I also observed it on remote with borgbase.com.
Filesystem: ext4.

#### How much data is handled by borg?
```shell
$ du -hs rust_test/
172M    rust_test/
```

#### Full borg command-line that lead to the problem (leave away excludes and passwords)
```
$ borg prune --list -a sh:Day* --keep-last 1 ./borg-repo/
```

## Describe the problem you're observing.
The `-a` option of `borg prune` does not seem to accept `sh:` as pattern selector. From the [documentation](https://borgbackup.readthedocs.io/en/stable/usage/general.html#common-options) it is not entirely clear if this is the intended behavior or a bug.

> -a GLOB, --glob-archives GLOB | only consider archive names matching the glob. **sh: rules apply, see “borg help patterns**”.

Leaving the `sh:` off does the correct thing. Problem here is that `Vorta` produces the pattern and before we know if that needs to be changed we need to know what the intended behavior is and maybe document it better.

Something along the lines of

> -a GLOB, --glob-archives GLOB | only consider archive names matching the glob. sh: rules apply, but you need to leave of the `sh:` selector, see “borg help patterns” for the sh:rules.

See [issue in vorta repo](https://github.com/borgbase/vorta/issues/1829).

#### Can you reproduce the problem? If so, describe how. If not, describe troubleshooting steps you took before opening the issue.

I ran this with both system wide borg installed via debian apt, and also via the borg 1.2.6 binary just copied into the same directory and calling it via `./borg`

```shell
$ ls -l
total 4
drwxr-xr-x 8 <redacted> <redacted> 4096 Jul  5 15:44 rust_test
$ borg init --encryption=none ./borg-repo
$ borg create ./borg-repo::Day01 rust_test
$ borg create ./borg-repo::Day02 rust_test
$ borg list ./borg-repo
Day01                                Wed, 2023-10-11 10:14:27 [fc3f26653bc067c70e6c00ee2bc9434371796c6363b005532159fdba0f345b23]
Day02                                Wed, 2023-10-11 10:14:43 [ee79208da5f953aeb6acea55357054d157b3c95b9046c6d892e34b0a40354f97]
$ borg prune --list -a sh:Day* --keep-last 1 ./borg-repo/
$ borg list ./borg-repo
Day01                                Wed, 2023-10-11 10:51:01 [13e416e9505c1103115e5b72044d4ebf8103570d0139ad5347a535a8b5aed8d9]
Day02                                Wed, 2023-10-11 10:51:15 [f659f7c0baed878dcc22d8f6a088a7ad0c264ac7238eacf4935a6464b6a6cad6]
$ borg prune --list -a Day* --keep-last 1 ./borg-repo/
Keeping archive (rule: secondly #1):     Day02                                Wed, 2023-10-11 10:14:43 [ee79208da5f953aeb6acea55357054d157b3c95b9046c6d892e34b0a40354f97]
Pruning archive (1/1):                   Day01                                Wed, 2023-10-11 10:14:27 [fc3f26653bc067c70e6c00ee2bc9434371796c6363b005532159fdba0f345b23]
$ borg list ./borg-repo/
Day02                                Wed, 2023-10-11 10:14:43 [ee79208da5f953aeb6acea55357054d157b3c95b9046c6d892e34b0a40354f97]
```



Discussion:
Well, I now tested it with [borg 2.0.0b7](https://github.com/borgbackup/borg/releases/download/2.0.0b7/borg-linux64) and here it's exactly the other way round. The `sh:` version works and the one without it does nothing because the default pattern style is `id:` which wants an exact match.

```shell
$ ./borg -V
borg 2.0.0b7
$ ./borg -r borg-repo rcreate --encryption=none
$ ll
total 27456
-rwxr-xr-x 1 <redacted> <redacted> 28104512 Oct 11 10:53 borg
drwx------ 3 <redacted> <redacted>     4096 Oct 11 10:58 borg-repo
drwxr-xr-x 8 <redacted> <redacted>     4096 Jul  5 15:44 rust_test
$ ./borg -r borg-repo/ create Day01 rust_test/
$ ./borg -r borg-repo/ create Day02 rust_test/
$ ./borg -r borg-repo/ prune --list --keep-last 1 -a sh:Day*
Keeping archive (rule: secondly #1):     Day02                                Wed, 2023-10-11 11:00:38 +0200 [9ad85a80345b3f6227dd10fcef54b318af13c24a966021acbcbfe1810a450bb2]
Pruning archive (1/1):                   Day01                                Wed, 2023-10-11 11:00:09 +0200 [9a99cde4b14c6e2a1e4e221922c3f7e8bb5d461278392f075b59524861faf145]
$ ./borg -r borg-repo/ create Day03 rust_test/
$ ./borg -r borg-repo/ rlist
Day02                                Wed, 2023-10-11 11:00:38 +0200 [9ad85a80345b3f6227dd10fcef54b318af13c24a966021acbcbfe1810a450bb2]
Day03                                Wed, 2023-10-11 11:02:07 +0200 [a86f4b2e99120b44c8a8debedafee7a7c52f974ddff91f12c10a9704c6465517]
$ ./borg -r borg-repo/ prune --list --keep-last 1 -a Day*
$ ./borg -r borg-repo/ rlist
Day02                                Wed, 2023-10-11 11:00:38 +0200 [9ad85a80345b3f6227dd10fcef54b318af13c24a966021acbcbfe1810a450bb2]
Day03                                Wed, 2023-10-11 11:02:07 +0200 [a86f4b2e99120b44c8a8debedafee7a7c52f974ddff91f12c10a9704c6465517]
```
So the documentation should maybe even mention that this behavior changes in borg2? It has been well improved in borg2. There now all patterns work and there is a separate documentation for `borg help --match-archives`. But it's still a potential trip-up for people migrating from v1 to v2.
FYI: Vorta changed the command generation to reflect borgs behavior in v0.8.11, but I still think it would make sense to add a little something to the borg 1.* documentation.
There is no bug in borg here.

borg < 2 always required the archive name pattern to be just a glob (shell) pattern (that's why the option is called `--glob-archives` there), but it never supported giving pattern styles for this (like giving `sh:` or `re:` or ... in front of the pattern).

borg 2 makes this more flexible by supporting pattern styles (which is the reason why the option is called `--match-archives` there).

Yes, the borg 1 docs could be a bit more clear, PRs welcome!
@ThomasWaldmann Can you give me a little help. On which branch should I base my change?
@SebastianJL The 1.2.x releases are made from branch `1.2-maint`.

`master` branch is what will become borg 2 some day.
Thanks for the hint. I see that the .rst files are auto-generated. Can you tell me where they are auto-generated from?

EDIT:
I think I found it in `src/borg/archiver.py`

Resolving patch:
diff --git a/src/borg/archiver.py b/src/borg/archiver.py
--- a/src/borg/archiver.py
+++ b/src/borg/archiver.py
@@ -3025,7 +3025,7 @@ def define_archive_filters_group(subparser, *, sort_by=True, first_last=True):
             group.add_argument('-a', '--glob-archives', metavar='GLOB', dest='glob_archives',
                                type=GlobSpec, action=Highlander,
                                help='only consider archive names matching the glob. '
-                                    'sh: rules apply, see "borg help patterns".')
+                                    'sh: rules apply (without actually using the sh: prefix), see "borg help patterns".')
 
             if sort_by:
                 sort_by_default = 'timestamp'


Test patch: