tag options: one tag per option, fixes #10430

[ThomasWaldmann]

Fixes #10430.

borg tag --set/--add/--remove and borg create --tags took multiple tags per option (nargs="*" / nargs="+"), so they swallowed the archive NAME if it came after them, e.g. borg tag --set keep aid:1ddaae55 failed with a confusing error.

Changes

• tag: --set, --add and --remove take exactly one tag and can be given multiple times, e.g. borg tag --add a --add b NAME. Also added examples to borg tag --help.
• tag: new --clear removes all normal tags, but keeps special tags like @PROT. It can be combined with --add to replace the normal tags and is mutually exclusive with --set. This replaces the previous way of clearing tags with a bare --set, which is not possible anymore.
• create: --tags is replaced by --tag, taking one tag per option, e.g. borg create --tag foo --tag bar NAME PATH.
• tag: refuse to change the tags of all archives without an explicit selection (NAME or archive filters), like borg delete does. Use -a 'sh:*' to change all archives. Just showing the tags of all archives still works without a selection.
• tag: warn (rc 1) if --set is refused because it would remove pre-existing special tags. Previously this was silent and returned rc 0.
• docs: explain that the tags: match pattern takes a comma-separated list and matches archives having all of the given tags.

Implementation note

The repeatable options use action="extend", nargs=1 rather than action="append": jsonargparse re-validates parsed values after parsing and, for nargs=None, calls the type on the whole appended list, which breaks the tag validator. With extend + nargs=1, it gets a flat list and checks each element; keeping type=tag_validator also keeps shell completion for tags working.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 94.73684% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 88.65%. Comparing base (925c55f) to head (cce5c99).
⚠️ Report is 1 commits behind head on master.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/borg/archiver/tag_cmd.py	94.73%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master   #10432      +/-   ##
==========================================
+ Coverage   88.63%   88.65%   +0.01%     
==========================================
  Files         103      103              
  Lines       19206    19217      +11     
  Branches     2990     2993       +3     
==========================================
+ Hits        17024    17036      +12     
+ Misses       1516     1513       -3     
- Partials      666      668       +2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.