feat: pass custom options to restic backup #101

elmotec · 2026-01-24T22:41:56Z

add stack-back.restic.backup.options label to the stack-back container (not the backed up containers because all volumes are backed up with one restic command) to take restic backup options. Defaults to --verbose for backward compatibility.

Also:

add LABEL_RESTIC_BACKUP_OPTIONS as enum.
feature works for both volumes and database backup.
change backup(), backup_from_stdin() signature to take restic_backup_options as argument.
add --tag test-tag to test compose file and integration_test.
enhance integration_test parsing of snapshots (could use json, but less readable).
improve visibility of logs when integration tests run showing output of restic command in pytest log (with --log-cli-level=DEBUG).
documentation.

add stack-back.restic.backup.options label to the stack-back container to take `restic backup` options. Defaults to `--verbose` for backward compatibility. Also: - add LABEL_RESTIC_BACKUP_OPTIONS as enum. - feature works for both volumes and database backup. - change backup(), backup_from_stdin() signature to take restic_backup_options as argument. - add --tag test-tag to test compose file and integration_test. - enhance integration_test parsing of snapshots (could use json, but less readable). - improve visibility of logs when integration tests run showing output of restic command in pytest log (with --log-cli-level=DEBUG). - documentation.

Copilot

Pull request overview

This PR adds support for passing custom restic backup options through a Docker label stack-back.restic.backup.options. The feature aims to allow users to customize restic backup behavior (e.g., adding tags) while maintaining backward compatibility with the default --verbose flag.

Changes:

Added LABEL_RESTIC_BACKUP_OPTIONS constant to enums
Modified backup function signatures to accept restic_backup_options parameter
Enhanced integration tests with snapshot parsing and tag verification
Added documentation for the new feature

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
src/restic_compose_backup/enums.py	Added new label constant for restic backup options
src/restic_compose_backup/restic.py	Updated backup functions to accept and pass custom options
src/restic_compose_backup/containers.py	Updated base container backup method signature
src/restic_compose_backup/containers_db.py	Updated database container backup methods to accept options
src/restic_compose_backup/cli.py	Added label parsing logic and option passing
src/tests/integration/test_volume_backups.py	Added snapshot parsing helper and tag verification
src/tests/integration/conftest.py	Added debug logging for test diagnostics
docker-compose.test.yaml	Added test label with --tag option
docs/guide/configuration.rst	Documented the new feature
README.md	Added note about pytest debug options

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

docs/guide/configuration.rst

src/tests/integration/test_volume_backups.py

src/restic_compose_backup/cli.py

Copilot · 2026-01-24T22:48:35Z

src/restic_compose_backup/cli.py

+    restic_backup_options = ["--verbose"]
+    backup_args_label = containers.this_container.get_label(enums.LABEL_RESTIC_BACKUP_OPTIONS)
+    if backup_args_label:
+        restic_backup_options.extend(backup_args_label.split())


Using .split() without arguments to parse the backup options may not handle quoted strings correctly. For example, if a user wants to pass an option with a space in it like --tag "my backup tag", the .split() method will incorrectly split it into three separate arguments: ["--tag", '"my', 'backup', 'tag"'].

Consider using shlex.split() instead, which properly handles quoted strings and follows shell parsing rules. This would allow users to pass more complex option values safely.

Not sure about this one.

src/tests/integration/test_volume_backups.py

Copilot · 2026-01-24T22:48:36Z

src/restic_compose_backup/restic.py

+def backup_files(repository: str, restic_backup_options: List[str], source="/volumes"):
    return commands.run(
        restic(
            repository,
            [
-                "--verbose",
                "backup",
                source,
-            ],
+            ] + restic_backup_options,


The order of arguments being passed to restic may cause issues. The backup options are appended after the source path (source is added first at line 34, then restic_backup_options is appended). However, some restic options must come before the command arguments. For example, global flags like --verbose should come before backup, while backup-specific flags come after.

The current implementation puts all custom options after the source path, which means they're treated as backup-specific options. This works for --verbose and --tag, but users might expect to be able to pass global restic options as well. Consider documenting this limitation, or restructure to separate global options from backup-specific options.

I feel the name of the label says it back-stack.restic.backup.options. Those are the options passed to restic backup. Let me know if you'd like to make a change.

I'm worried that Copilot might be right here about the order of options being important. We may not be able to simply append all restic_backup_options to the end of the command. I'll do some testing and report back.

Ok, let me know how to do it differently.

In my mind, back-stack.restic.backup.options are options that are listed in the output for restic backup --help. Maybe I should make that clear in the documentation.

If anyone wants options before backup those probably could be listed as back-stack.restic.options but I don't have a use case for anything before backup.

Per lawndoc#101 (comment). It does feel less surprising. Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

lawndoc

Hi @elmotec thanks for the PR! In addition to your use cases from the discussion, I know this will be handy for people who want to use glacier s3 class and need to pass through additional args for that to work.

Just a few comments for you to review.

lawndoc · 2026-02-07T03:34:10Z

src/restic_compose_backup/restic.py

+def backup_files(repository: str, restic_backup_options: List[str], source="/volumes"):
    return commands.run(
        restic(
            repository,
            [
-                "--verbose",
                "backup",
                source,
-            ],
+            ] + restic_backup_options,


I'm worried that Copilot might be right here about the order of options being important. We may not be able to simply append all restic_backup_options to the end of the command. I'll do some testing and report back.

lawndoc · 2026-02-07T03:35:07Z

src/restic_compose_backup/restic.py

            "--stdin-filename",
            filename,
-        ],
+        ] + restic_backup_options,


Same comment here, we need to make sure that all potential options can be appended to the end of the restic command and can come after the backup argument.

we can follow up on this conversation.

src/tests/integration/conftest.py

src/tests/integration/test_volume_backups.py

lawndoc · 2026-02-07T03:40:25Z

docker-compose.test.yaml

  backup:
    build: ./src
+    labels:
+      stack-back.restic.backup.options: "--tag test-tag"


Since these options override the default --verbose flag, it might be a good idea to add --verbose to these arguments since this is a test and the verbose output may be useful to us.

good point, I was initially adding to the existing options and later the LLM convinced me to switch to a complete override. I did not update the compose test though but it is fixed in 57fdbdd.

See lawndoc#101 (comment)

elmotec · 2026-02-08T20:36:41Z

Hi @elmotec thanks for the PR! In addition to your use cases from the discussion, I know this will be handy for people who want to use glacier s3 class and need to pass through additional args for that to work.

Just a few comments for you to review.

Thanks @lawndoc, I addressed your comments. Re-requested review.

elmotec · 2026-02-09T11:38:49Z

Also I am wondering if we should support a back-stack.restic.backup.db.options for the database restic backup call. I am not sure, it could lead to different set of options for each database type (postres, MySQL, ...). It might get complicated.

Copilot AI review requested due to automatic review settings January 24, 2026 22:41

Copilot started reviewing on behalf of elmotec January 24, 2026 22:42 View session

Copilot AI reviewed Jan 24, 2026

View reviewed changes

replace restic backup options instead of extending

ab2fcfa

Per lawndoc#101 (comment). It does feel less surprising. Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

lawndoc reviewed Feb 7, 2026

View reviewed changes

elmotec added 2 commits February 8, 2026 15:14

format: apply uv run ruff format . in src/

4160c54

fix: restored dropped --verbose option

57fdbdd

See lawndoc#101 (comment)

elmotec requested a review from lawndoc February 8, 2026 20:36

feat: pass custom options to restic backup #101

Are you sure you want to change the base?

feat: pass custom options to restic backup #101

Uh oh!

Conversation

elmotec commented Jan 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Jan 24, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Jan 24, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lawndoc left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

elmotec commented Feb 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

elmotec commented Feb 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

elmotec commented Jan 24, 2026 •

edited

Loading

lawndoc left a comment •

edited

Loading

elmotec commented Feb 8, 2026 •

edited

Loading