Skip to content

Centralise Borg repo/archive arguments and fix Borg 2 drift - #2617

Merged
m3nu merged 1 commit into
masterfrom
refactor/2601-borg-repo-args
Nov 15, 2026
Merged

m3nu merged 1 commit into
masterfrom
refactor/2601-borg-repo-args

Conversation

@m3nu

@m3nu m3nu commented Nov 14, 2026

Copy link
Copy Markdown
Contributor

Description

Every Borg job built its repository/archive arguments with its own if borg_compat.check('V2') branch. This adds two helpers on BorgCompatibility and uses them at all 16 sites:

  • repo_args(url, archive=None, *, match=False): Borg 1 gives [url] or [url::archive]; Borg 2 gives ['-r', url], ['-r', url, archive], or with match=True ['-r', url, '-a', 'id:<archive>'] for commands that have no archive positional.
  • match_archive(name): the Borg 2 --match-archives value for exactly that name (id:<name>).

What stays at the call site: delete's multi-archive regex on Borg 2, the prune prefix filter (three version tiers), and the repo-info / repo-list / repo-create subcommand names.

Borg 1 argv is unchanged at every site. The helpers only append to cmd, so cmd[1] (stored as EventLogModel.subcommand and queried by the scheduler) does not move.

Borg 2 fixes:

Site Before After
break-lock break-lock ... URL (no positional exists in Borg 2) break-lock ... -r URL
check with a selected archive -r URL::NAME -r URL -a id:NAME
mount an archive -a with a mangled name (a*b[c]? became a\1b\1c\1\1) -a id:NAME
mount detection archive mounts stored as {'-a': NAME} {NAME: mount_point}, as the Borg 1 parser and the views expect
delete -a re:(a|b) from raw names -a re:(?:a|b) with each name passed through re.escape
info -a NAME -a id:NAME

Also, on Borg 1 and 2: break-lock reported "Repository lock broken" whatever the return code. It now shows a failure message with a link to the logs for a non-zero return code. This adds one translatable string; the catalogs are not regenerated here.

Other changes:

  • BorgCheckJob.prepare(profile, archive=None) takes the archive; the view no longer appends ::NAME to cmd[-1].
  • extract_mount_points_v2 parses the command line by option instead of by position. It accepts short, long and joined forms, skips the values of other value-taking options, ignores --match-archives patterns that are not a single name (sh:, re:, aid:, ...), and never raises on a truncated or foreign command line. SHELL_PATTERN_ELEMENT is gone.
  • info_repo / list_repo read the URL from params['repo_url'] instead of cmd[-1].

Related Issue

Fixes #2601

Motivation and Context

The Borg 2 branches are not exercised by CI and had drifted: one was missing, one was applied from outside the job, and the archive name was quoted three different ways. See the issue for the six bugs.

Known limitations

  • Nothing here was run against a Borg 2 binary. The Borg 2 argv was checked against the argument parsers and the match-archives code in Borg source at 2.0.0b10, b25 and master. The integration fixtures still use rcreate, so a Borg 2 CI job needs its own change.
  • From Borg 2.0.0b12 the positional NAME of extract, list, rename and diff is interpreted as a pattern, so an archive name that starts with a pattern prefix is ambiguous there. b10 takes it literally, so id: cannot simply be added at those sites.
  • With archive series (from 2.0.0b11), id:NAME and delete's re: can match more than one archive.
  • This and the change for Always finish a Borg job and unblock the UI when it raises #2600 both touch break_lock.py's finished_event; whichever is merged second needs a small rebase.

How Has This Been Tested?

  • New tests/unit/test_borg_argv.py, 127 tests. The Borg 1 pins (exact argv per job, including view-level check with a selected archive and the Borg 1 mount parser) were written first and pass against the unmodified code; they were not edited afterwards.
  • Independent of those tests, the prepare() output of all 16 job types was compared between the base commit and this branch under Borg 1.1.18, 1.2.8 and 1.4.3 with a range of archive names, prefixes and extra arguments: 825 entries, no differences.
  • Borg 2: exact argv per fixed site; the delete regex is checked against a hardcoded expectation and by matching it the way Borg does (re.match with \Z appended); the mount parser is tested on Vorta's own command shapes, long and joined forms, foreign options and patterns, and truncated lines; a round trip feeds BorgMountJob.prepare output back into the parser.
  • Break-lock: failure message for return codes 1 and 2, and the order of emitted signals for success and failure.
  • uv run pytest tests/unit --ignore=tests/unit/test_keyring_darwin.py on macOS with Borg 1.4.5 on PATH: 491 passed, 7 skipped. The 5 warnings are the existing PytestUnhandledThreadExceptionWarnings from test_archives.py and test_lock.py, which also occur on master.
  • Not run locally: the nox matrix and the integration tests.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

  • I have read the CONTRIBUTING guide.
  • My code follows the code style of this project.
  • My change requires a change to the documentation.
  • I have updated the documentation accordingly.
  • I have added tests to cover my changes.
  • All new and existing tests passed.

I provide my contribution under the terms of the license of this repository and I affirm the Developer Certificate of Origin.

Every job built its repository and archive arguments with its own
Borg 1/2 branch. The Borg 2 branches are not exercised by CI and had
drifted apart. Add BorgCompatibility.repo_args() and match_archive()
and use them at all sites; only delete's multi-archive regex, the prune
prefix filter and the repo-* subcommand names stay at their call sites.
Borg 1 argv is unchanged everywhere.

Borg 2 fixes on the way:
- break-lock passes the repo with -r instead of positionally
- check of a selected archive uses -a id:NAME instead of -r URL::NAME;
  the archive is now passed to BorgCheckJob.prepare instead of being
  appended to cmd by the view
- mounting an archive uses -a id:NAME instead of a mangled shell escape
- mount detection parses the command line by option, so archive mounts
  are recognised again and map archive name to mount point
- delete escapes regex metacharacters in archive names
- info uses -a id:NAME, so a name starting with a pattern prefix is
  matched literally

Break-lock no longer reports success when Borg failed (Borg 1 and 2).

Fixes #2601
@m3nu
m3nu merged commit 04f0062 into master Nov 15, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Centralise Borg repo/archive arguments and fix Borg 2 drift

1 participant