dar-backup 1.0.0.1__py3-none-any.whl → 1.0.2__py3-none-any.whl

dar_backup/README.md

@@ -4,17 +4,19 @@
 **Reliable DAR backups, automated in clean Python**
 
 [![Codecov](https://codecov.io/gh/per2jensen/dar-backup/branch/main/graph/badge.svg)](https://codecov.io/gh/per2jensen/dar-backup)
-[![Snyk Vuln findings](https://snyk.io/test/github/per2jensen/dar-backup/badge.svg)](https://snyk.io/test/github/per2jensen/dar-backup)
+[![Snyk Vuln findings](https://snyk.io/test/github/per2jensen/dar-backup/badge.svg)](https://security.snyk.io/vuln/?search=dar-backup)
 ![CI](https://github.com/per2jensen/dar-backup/actions/workflows/py-tests.yml/badge.svg)
 [![PyPI version](https://img.shields.io/pypi/v/dar-backup.svg)](https://pypi.org/project/dar-backup/)
 [![PyPI downloads](https://img.shields.io/badge/dynamic/json?color=blue&label=PyPI%20downloads&query=total&url=https%3A%2F%2Fraw.githubusercontent.com%2Fper2jensen%2Fdar-backup%2Fmain%2Fdownloads.json)](https://pypi.org/project/dar-backup/)
-[![# clones](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/per2jensen/dar-backup/main/v2/doc/badges/badge_clones.json)](https://github.com/per2jensen/dar-backup/blob/main/v2/doc/weekly_clones.png)
-[![Milestone](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/per2jensen/dar-backup/main/v2/doc/badges/milestone_badge.json)](https://github.com/per2jensen/dar-backup/blob/main/v2/doc/weekly_clones.png)  <sub>🎯 Stats powered by [ClonePulse](https://github.com/per2jensen/clonepulse)</sub>
+[![# clones](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/per2jensen/dar-backup/main/clonepulse/badge_clones.json)](https://github.com/per2jensen/dar-backup/blob/main/clonepulse/weekly_clones.png)
+[![Milestone](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/per2jensen/dar-backup/main/clonepulse/milestone_badge.json)](https://github.com/per2jensen/dar-backup/blob/main/clonepulse/weekly_clones.png)  <sub>🎯 Stats powered by [ClonePulse](https://github.com/per2jensen/clonepulse)</sub>
 
 The wonderful 'dar' [Disk Archiver](https://github.com/Edrusb/DAR) is used for
 the heavy lifting, together with the [parchive](https://github.com/Parchive/par2cmdline) suite in these scripts.
 
-This is the `Python` based [**version 2**](https://github.com/per2jensen/dar-backup/tree/main/v2) of `dar-backup`.
+This is the `Python` based [**version 2**](v2) of `dar-backup`.
+
+You can see the [v2 Changelog](v2/Changelog.md) for details on features and progress.
 
 ## TL;DR
 
@@ -28,6 +30,9 @@ Version **1.0.0** was reached on October 9, 2025.
   - [TL;DR](#tldr)
   - [Table of Contents](#table-of-contents)
   - [My use case](#my-use-case)
+  - [My setup](#my-setup)
+    - [Why PAR2 is especially good for portable / offsite copies](#why-par2-is-especially-good-for-portable--offsite-copies)
+    - [Design choices](#design-choices)
   - [Features](#features)
   - [License](#license)
   - [Quick Guide](#quick-guide)
@@ -71,6 +76,8 @@ Version **1.0.0** was reached on October 9, 2025.
     - [restore test fails with exit code 5](#restore-test-fails-with-exit-code-5)
   - [Par2](#par2)
     - [Par2 to verify/repair](#par2-to-verifyrepair)
+      - [Par2 files kept with archives](#par2-files-kept-with-archives)
+      - [Par2 files in separate directory](#par2-files-in-separate-directory)
     - [Par2 create redundancy files](#par2-create-redundancy-files)
   - [Points of interest](#points-of-interest)
     - [Limitations on File Names with Special Characters](#limitations-on-file-names-with-special-characters)
@@ -88,8 +95,8 @@ Version **1.0.0** was reached on October 9, 2025.
     - [Performance tip due to par2](#performance-tip-due-to-par2)
     - [.darrc sets -vd -vf (since v0.6.4)](#darrc-sets--vd--vf-since-v064)
     - [Separate log file for command output](#separate-log-file-for-command-output)
+    - [Trace Logging (Debug details)](#trace-logging-debug-details)
     - [Skipping cache directories](#skipping-cache-directories)
-    - [Progress bar and current directory](#progress-bar-and-current-directory)
     - [Shell autocompletion](#shell-autocompletion)
       - [Use it](#use-it)
       - [Archive name completion (smart, context-aware)](#archive-name-completion-smart-context-aware)
@@ -103,12 +110,22 @@ Version **1.0.0** was reached on October 9, 2025.
     - [CLI Tools Overview](#cli-tools-overview)
     - [test coverage](#test-coverage)
     - [Dar-backup options](#dar-backup-options)
+      - [Dar-backup exit codes](#dar-backup-exit-codes)
+      - [Dar-backup env vars](#dar-backup-env-vars)
     - [Manager Options](#manager-options)
-    - [Cleanup options](#cleanup-options)
+      - [Cleanup env vars](#cleanup-env-vars)
     - [Clean-log options](#clean-log-options)
     - [Dar-backup-systemd options](#dar-backup-systemd-options)
     - [Installer options](#installer-options)
     - [Demo options](#demo-options)
+    - [Config changes](#config-changes)
+      - [1.0.1](#101)
+        - [DISCORD WEBHOOK](#discord-webhook)
+        - [Restore test config](#restore-test-config)
+        - [Par2](#par2-1)
+      - [1.0.2](#102)
+        - [Trace Logging](#trace-logging)
+        - [Command output Capture](#command-output-capture)
   
 ## My use case
 
@@ -118,7 +135,7 @@ I needed the following:
 - Backup primarily photos, home made video and different types of documents
 - I have cloud storage mounted on a directory within my home dir. The filesystem is [FUSE based](https://www.kernel.org/doc/html/latest/filesystems/fuse.html), which gives it a few special features
 
-  - Backup cloud storage (cloud is convenient, but I want control over my backups)
+  - Backup my cloud storage (cloud is convenient, but I want control over my backups)
   - A non-privileged user can perform a mount
   - A privileged user cannot look into the filesystem --> a backup script running as root is not suitable
 
@@ -129,6 +146,48 @@ I needed the following:
 
  I do not need the encryption features of dar, as all storage is already encrypted.
 
+## My setup
+
+1. Primary backup to server with an ext4 file system on mdadm RAID1
+
+2. Secondary copies to multiple USB disks / cloud
+
+3. Archive integrity verification anywhere using [Par2](#par2) and `dar -t`.
+
+4. Archive repair anywhere if needed. By default `dar-backup` creates par2 redundancy files with 5% coverage. Enough to fix localized bitrot.
+
+5. No dependency on original system
+
+### Why PAR2 is especially good for portable / offsite copies
+
+PAR2 parity is:
+
+> Self-contained (travels with the data)
+>
+>Format-agnostic (works on any filesystem)
+>
+>Location-agnostic (local disk, USB, cloud object storage)
+>
+>Tool-stable (PAR2 spec has not changed in years)
+>
+>That means:
+>
+>**Integrity protection moves with the archive**.
+
+### Design choices
+
+My design choices are boring, proven and pragmatic:
+>
+>mdadm handles disks
+>
+>PAR2 handles data integrity
+>
+>You control when and how verification happens
+>
+>Errors have a fair chance of being diagnosed and fixed, due to well known tooling.
+>
+>No hidden magic, no lock-in
+
 ## Features
 
 - The battle tested [dar](https://github.com/Edrusb/DAR) Disk Archiver is used for the actual backups - it comes highly recommended.
@@ -151,7 +210,7 @@ I needed the following:
 ## License
 
   These scripts are licensed under the GPLv3 license.
-  Read more here: [GNU  GPL3.0](https://www.gnu.org/licenses/gpl-3.0.en.html), or have a look at the ["LICENSE"](https://github.com/per2jensen/dar-backup/blob/main/LICENSE) file in this repository.
+  Read more here: [GNU  GPL3.0](https://www.gnu.org/licenses/gpl-3.0.en.html), or have a look at the ["LICENSE"](LICENSE) file in this repository.
 
 ## Quick Guide
 
@@ -496,7 +555,7 @@ This python version is v2 of dar-backup, v1 is made in bash.
 
 ## Community
 
-Please review the [Code of Conduct](https://github.com/per2jensen/dar-backup/blob/main/CODE_OF_CONDUCT.md) to help keep this project welcoming and focused.
+Please review the [Code of Conduct](CODE_OF_CONDUCT.md) to help keep this project welcoming and focused.
 
 ## Requirements
 
@@ -516,7 +575,7 @@ On Ubuntu, install the requirements this way:
 
 ### dar-backup overview
 
-![dar-backup overview](https://github.com/per2jensen/dar-backup/blob/main/v2/doc/dar-backup-overview.svg)
+[![dar-backup overview](v2/doc/dar-backup-overview-small.png)](v2/doc/dar-backup-overview.png)
 
 ### dar-backup
 
@@ -545,6 +604,15 @@ The `cleanup` application deletes DIFF and INCR if the archives are older than t
 
 `cleanup` will only remove FULL archives if the option  `--cleanup-specific-archives` is used. It requires the user to confirm deletion of FULL archives.
 
+Use `--dry-run` to preview which archives, PAR2 files, and catalogs would be removed without deleting anything.
+
+Examples:
+
+```bash
+cleanup --dry-run -d media-files --log-stdout
+cleanup --dry-run --cleanup-specific-archives -d media-files media-files_INCR_2025-12-22
+```
+
 ### manager
 
 `dar`has the concept of catalogs which can be exported and optionally be added to a catalog database. That database makes it much easier to restore the correct version of a backed up file if for example a target date has been set.
@@ -688,7 +756,7 @@ deactivate
 
 The configuration file's default location is: ~/.config/dar-backup/dar-backup.conf
 
-If you have your config file somewhere else, use the `--config` option to point to it.
+If you have your config file somewhere else, use the `--config-file` option to point to it.
 
 Tilde `~` and environment variables can be used in the paths for various file locations.
 
@@ -724,6 +792,17 @@ INCR_AGE = 40
 [PAR2]
 ERROR_CORRECTION_PERCENT = 5
 ENABLED = True
+# Optional PAR2 configuration
+# PAR2_DIR = /path/to/par2-store
+# PAR2_RATIO_FULL = 10
+# PAR2_RATIO_DIFF = 5
+# PAR2_RATIO_INCR = 5
+# PAR2_RUN_VERIFY = false
+
+# Optional per-backup overrides (section name = backup definition)
+[media-files]
+PAR2_DIR = /mnt/par2/media-files
+PAR2_RATIO_FULL = 10
 
 # scripts to run before the backup to setup the environment
 [PREREQ]
@@ -735,6 +814,16 @@ SCRIPT_1 = df -h
 #SCRIPT_2 = another_script.sh
 ```
 
+PAR2 notes:
+
+- If `PAR2_DIR` is unset, par2 files are created next to the archive slices (legacy behavior) and no manifest is written
+- When `PAR2_DIR` is set, dar-backup writes a manifest next to the par2 set:
+  `archive_base.par2.manifest.ini`
+- When generating a par2 set, par2 reads all archive slices before writing any output files; for large backups, this initial read can take hours
+- Verify or repair using:
+  `par2 verify -B <archive_dir> <par2_set.par2>`
+  `par2 repair -B <archive_dir> <par2_set.par2>`
+
 ### .darrc
 
 The package includes a default `darrc` file which configures `dar`.
@@ -1056,6 +1145,25 @@ This happens when the shell splits the quoted string or interprets globs before
 
 > 💡 **Tip:** See [dar's documentation](http://dar.linux.free.fr/doc/man/dar.html#COMMANDS%20AND%20OPTIONS)
 
+>
+> 💡💡 **Tip:** To filter all the empty directories away that `dar` emits when listing  contents, append this grep:
+>
+> ```bash
+> |grep -vE '\s+d[rwx-]{9}\s'
+>```
+>
+>Example using the grep to discard directory noise from `dar's` output:
+>
+> ```bash
+> dar-backup --list-contents media-files_INCR_2025-05-10 --selection="-I '*Z50*' -X '*.xmp'" | grep -vE '\s+d[rwx-]{9}\s'
+>[Saved][ ]       [-L-][   0%][X]  -rw-rw-r--   user user 26  Mio Fri May  9 11:26:16 2025 home/user/data/2025/2025-05-09-Roskilde-Nordisk-udstilling/Z50_0633.NEF
+>[Saved][ ]       [-L-][   0%][X]  -rw-rw-r--   user user 26  Mio Fri May  9 11:26:16 2025 home/user/data/2025/2025-05-09-Roskilde-Nordisk-udstilling/Z50_0632.NEF
+>[Saved][ ]       [-L-][   0%][X]  -rw-rw-r--   user user 28  Mio Fri May  9 11:09:04 2025 home/user/data/2025/2025-05-09-Roskilde-Nordisk-udstilling/Z50_0631.NEF
+>[Saved][ ]       [-L-][   0%][X]  -rw-rw-r--   user user 29  Mio Fri May  9 11:09:03 2025 home/user/data/2025/2025-05-09-Roskilde-Nordisk-udstilling/Z50_0630.NEF
+>[Saved][ ]       [-L-][   0%][X]  -rw-rw-r--   user user 29  Mio Fri May  9 11:09:03 2025 home/user/data/2025/2025-05-09-Roskilde-Nordisk-udstilling/Z50_0629.NEF
+>...
+>```
+
 ### select a directory
 
 Select files and sub directories in `home/user/data/2025/2025-05-09-Roskilde-Nordisk-udstilling`
@@ -1182,9 +1290,39 @@ If you need to use this option, un-comment it in the [.darrc](#darrc) file (loca
 
 ## Par2
 
+Why keep PAR2 on a different storage device:
+
+- Reduces single-disk failure impact: bitrot on the archive disk does not affect the parity.
+- Easier offsite rotation: you can sync only the PAR2 sets to a different failure domain.
+
+Redundancy guidance:
+
+- FULL backups: 10% is a practical default for larger data sets and longer retention.
+- DIFF/INCR: 5% is often enough because the delta is smaller and easier to re-create.
+- Increase the ratio if the storage is flaky or the backup is hard to re-run.
+
+Rule of thumb table:
+
+| Backup type | Suggested PAR2 ratio | Notes |
+|-------------|----------------------|-------|
+| FULL        | 10%                  | Longer retention, larger data set |
+| DIFF        | 5%                   | Smaller delta |
+| INCR        | 5%                   | Smaller delta |
+
+>
+>For large, contiguous archives on reliable local storage, 7–8% has proven sufficient in practice; 10% remains a conservative default.
+>
+
+Cloud sync / air-gap note:
+
+- Syncing PAR2 sets to a different device or remote store protects against bitrot and small corruption, but it cannot recover a completely lost archive.
+- An air-gapped PAR2 store is useful when the archive disk is exposed to ransomware or accidental deletion.
+
 ### Par2 to verify/repair
 
-You can run a par2 verification on an archive like this:
+#### Par2 files kept with archives
+
+If PAR2 files are stored next to the archives (legacy per-slice behavior), you can verify like this:
 
 ```bash
 for file in <archive>*.dar.par2; do
@@ -1198,6 +1336,14 @@ if there are problems with a slice, try to repair it like this:
   par2 repair <archive>.<slice number>.dar.par2
 ```
 
+#### Par2 files in separate directory
+
+See [docs on disk layout matters](v2/doc/portable-par2-layout.md)
+
+>Test case proving this flow:
+>
+>[tests/test_par2_manifest.py](v2/tests/test_par2_manifest.py)
+
 ### Par2 create redundancy files
 
 If you have merged archives, you will need to create the .par2 redundency files manually.
@@ -1211,6 +1357,15 @@ done
 
 where "c" is create, -r5 is 5% redundency and -n1 is 1 redundency file
 
+If you want to create a single parity set for all slices in an archive:
+
+```bash
+par2 create -B <archive_dir> -r5 <par2_dir>/<archive_base>.par2 <archive_dir>/<archive_base>.*.dar
+```
+
+**OBSERVE** [docs on disk layout matters](v2/doc/portable-par2-layout.md)
+
+
 ## Points of interest
 
 ### Limitations on File Names with Special Characters
@@ -1365,23 +1520,29 @@ In order to not clutter that log file with the output of commands being run, a n
 
 The secondary log file can get quite cluttered, if you want to remove the clutter, run the `clean-log`script with the `--file` option, or simply delete it.
 
-### Skipping cache directories
+### Trace Logging (Debug details)
 
-The author uses the `--cache-directory-tagging` option in his [backup definitions](#backup-definition-example).
+To keep the main log file clean while preserving essential debugging information, `dar-backup` creates a separate trace log file (e.g., `dar-backup.trace.log`) alongside the main log.
 
-The effect is that directories with the [CACHEDIR.TAG](https://bford.info/cachedir/) file are not backed up. Those directories contain content fetched from the net, which is of an ephemeral nature and probably not what you want to back up.
+- **Main Log (`dar-backup.log`)**: Contains clean, human-readable INFO/ERROR messages. Stack traces are suppressed here.
+- **Trace Log (`dar-backup.trace.log`)**: Captures ALL messages at `DEBUG` level, including full exception stack traces. Use this file for debugging crashes or unexpected behavior.
 
-If the option is not in the backup definition, the cache directories are backed up as any other.
+You can configure the rotation of this file in `[MISC]`:
+
+```ini
+[MISC]
+# ... other settings ...
+TRACE_LOG_MAX_BYTES = 10485760  # 10 MB default
+TRACE_LOG_BACKUP_COUNT = 1      # Keep 1 old trace file (default)
+```
 
-### Progress bar and current directory
+### Skipping cache directories
 
-If you run dar-backup interactively in a "normal" console on your computer,
-dar-backup displays 2 visual artifacts to show progress.
+The author uses the `--cache-directory-tagging` option in his [backup definitions](#backup-definition-example).
 
-1. a progress bar that fills up and starts over
-2. a status line showing the directory being backed up. If the directory is big and takes time to backup, the line is not changing, but you will probably know there is a lot to backup.
+The effect is that directories with the [CACHEDIR.TAG](https://bford.info/cachedir/) file are not backed up. Those directories contain content fetched from the net, which is of an ephemeral nature and probably not what you want to back up.
 
-The indicators are not shown if dar-backup is run from systemd or if it is used in terminal multiplexers like `tmux` or `screen`. So no polluting of journald logs.
+If the option is not in the backup definition, the cache directories are backed up as any other.
 
 ### Shell autocompletion
 
@@ -1566,7 +1727,6 @@ pytest                   # run the test suite
 
 - Perhaps look into pre-processing backup definitions. As `dar` does not expand env vars
   `dar-backup` could do so and feed the result to `dar`.
-- When run interactively, a progress bar during test and par2 generation would be nice.
 - Look into a way to move the .par2 files away from the `dar` slices, to maximize chance of good redundancy.
 - Add option to dar-backup to use the `dar` option `--fsa-scope none`
 
@@ -1591,15 +1751,15 @@ One backup definition per file
 
 ### CLI Tools Overview
 
-| Command              | Description                               |
-|----------------------|-------------------------------------------|
-| [dar-backup](#dar-backup-options)| Perform full, differential, or incremental backups with verification and restore testing |
-| [manager](#manager-options)      | Maintain and query catalog databases for archives |
-| [cleanup](#cleanup-options)      | Remove outdated DIFF/INCR archives (and optionally FULLs) |
-| [clean-log](#clean-log-options)  | Clean up excessive log output from dar command logs |
+| Command | Description |
+| --- | --- |
+| [dar-backup](#dar-backup-options) | Perform full, differential, or incremental backups with verification and restore testing |
+| [manager](#manager-options) | Maintain and query catalog databases for archives |
+| [cleanup](#cleanup-options) | Remove outdated DIFF/INCR archives (and optionally FULLs) |
+| [clean-log](#clean-log-options) | Clean up excessive log output from dar command logs |
 | [dar-backup-systemd](#dar-backup-systemd-options) | Generate (and optionally install) systemd timers and services for automated backups |
-| [installer](#installer-options)  | Set up directories and optionally create catalog databases according to a config file |
-| [demo](#demo-options)            | Set up required directories and config files for a demo|
+| [installer](#installer-options) | Set up directories and optionally create catalog databases according to a config file |
+| [demo](#demo-options) | Set up required directories and config files for a demo|
 
 ### test coverage
 
@@ -1654,6 +1814,7 @@ Available options:
 --examples                           Show examples of using dar-backup.py.
 -l, --list                           List available backups.
 --list-contents <archive>            List the contents of a specified archive.
+--list-definitions                   List backup definitions from BACKUP.D_DIR.
 --selection <params>                 Define file selection for listing/restoring.
 --restore <archive>                  Restore a specified archive.
 -r, --restore <archive>              Restore archive.
@@ -1663,6 +1824,7 @@ Available options:
 --log-level <level>                  `debug` or `trace`, default is `info`.
 --log-stdout                         Also print log messages to stdout.
 --do-not-compare                     Do not compare restores to file system.
+--preflight-check                    Run preflight checks and exit (runs automatically; this flag just exits after checks).
 --examples                           Show examples of using dar-backup.
 --readme                             Print README.md and exit
 --readme-pretty                      Print README.md with Markdown styling and exit
@@ -1671,6 +1833,22 @@ Available options:
 -v, --version                         Show version and license information.
 ```
 
+#### Dar-backup exit codes
+
+- 0: Success.
+- 1: Error (backup/restore/preflight failure).
+- 2: Warning (restore test failed or backup already exists and is skipped).
+- 127: Typically an error during startup, file or config value missing
+  - if the `dar -t` test fails, exit code 1 is emitted
+  - restore tests could fail if the source file has changed after the backup
+
+#### Dar-backup env vars
+
+| Env var | Value | Description |
+| --- | --- | --- |
+| DAR_BACKUP_CONFIG_FILE | Full path to config file | Overrides built-in default, overridden by --config-file |
+| DAR_BACKUP_DISCORD_WEBHOOK_URL | https://discord.com/api/webhooks/\<userID\>/\<webhook UUID\> | The full url |
+
 ### Manager Options
 
 This script manages `dar` databases and catalogs.
@@ -1690,7 +1868,12 @@ Available options:
 --find-file <file>                   Search catalogs for a specific file.
 --verbose                            Enable verbose output.
 --log-level <level>                  Set log level (`debug` or `trace`, default is `info`).
-```
+
+#### Manager env vars
+
+| Env var | Value | Description |
+| --- | --- | --- |
+| DAR_BACKUP_CONFIG_FILE | path to the config file | Default is $HOME/.config/dar-backup/dar-backup.conf |```
 
 ### Cleanup options
 
@@ -1707,12 +1890,19 @@ Supported options:
 --alternate-archive-dir                           Clean up in this directory instead of the default one.
 --cleanup-specific-archives "<archive>, <>, ..."  Comma separated list of archives to cleanup.
 -l, --list                                       List available archives (filter using the -d option).
+--dry-run                                        Show what would be deleted without removing files.
 --verbose                                         Print various status messages to screen.
 --log-level <level>                               `debug` or `trace`, default is `info`", default="info".
 --log-stdout                                      Print log messages to stdout.
 --test-mode                                       This is used when running pytest test cases
 ```
 
+#### Cleanup env vars
+
+| Env var | Value | Description |
+| --- | --- | --- |
+| DAR_BACKUP_CONFIG_FILE | path to the config file | Default is $HOME/.config/dar-backup/dar-backup.conf |
+
 ### Clean-log options
 
 This script removes excessive logging output from `dar` logs, improving readability and efficiency. Available options:
@@ -1762,8 +1952,8 @@ Create directories:
 - ~/.config/dar-backup/
   - ~/.config/dar-backup/backup.d/
 - ~/dar-backup/
-  - ~/dar-backup/backups
-  - ~/dar-backup/restore
+  - ~/dar-backup/backups/
+  - ~/dar-backup/restore/
 
 Sets up demo config files:
 
@@ -1782,3 +1972,134 @@ Sets up demo config files:
 -v, --version       Display version and licensing information.
 -h, --help          Displays usage info
 ```
+
+### Config changes
+
+#### 1.0.1
+
+##### DISCORD WEBHOOK
+
+For Discord notifications use the `DAR_BACKUP_DISCORD_WEBHOOK_URL` environment variable. It should not be placed in the config file.
+
+DAR_BACKUP_DISCORD_WEBHOOK_URL is the entire endpoint like this:
+
+```bash
+export DAR_BACKUP_DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/\<userId\>/\<uuid\>
+```
+
+##### Restore test config
+
+Restore tests choose random files from the archive and compare them with the live filesystem.
+To avoid noisy paths (caches, temp files, logs), you can exclude candidates before the random
+selection happens. All matching is case-insensitive.
+
+Config keys (in [MISC]):
+
+- RESTORETEST_EXCLUDE_PREFIXES: comma-separated path prefixes to skip. Matches from the start of
+  the path (after trimming a leading "/"). Use trailing "/" for directories.
+- RESTORETEST_EXCLUDE_SUFFIXES: comma-separated filename suffixes to skip.
+- RESTORETEST_EXCLUDE_REGEX: optional regex to skip anything matching the path.
+
+Example:
+
+```ini
+[MISC]
+RESTORETEST_EXCLUDE_PREFIXES = .cache/, .local/share/Trash/, .mozilla/, snap/firefox/common/.mozilla/
+RESTORETEST_EXCLUDE_SUFFIXES = .sqlite-wal, .sqlite-shm, .log, .tmp, .lock, .journal
+RESTORETEST_EXCLUDE_REGEX = (^|/)(Cache|cache|Logs|log)/
+```
+
+Regex tips (case-insensitive):
+
+- Match common cache/log directories anywhere:
+  `(^|/)(cache|logs)/`
+- Skip thumbnails and temp dirs:
+  `(^|/)(thumbnails|tmp|temp)/`
+- Exclude browser profile noise while keeping other files:
+  `(^|/)\.mozilla/|/snap/firefox/common/\.mozilla/`
+
+##### Par2
+
+New optional PAR2 settings were added to the config file. If none of these keys are added, dar-backup behaves exactly as before (PAR2 files next to archives, per-slice parity).
+
+| Name | Description | When it is in effect | Suggested value |
+|------|-------------|----------------------|-----------------|
+| PAR2_DIR | Directory to store .par2 and .vol*.par2 files | When set | A different device or mount from BACKUP_DIR |
+| PAR2_RATIO_FULL | Redundancy percent for FULL | When set | 10 (%) |
+| PAR2_RATIO_DIFF | Redundancy percent for DIFF | When set | 5  (%)|
+| PAR2_RATIO_INCR | Redundancy percent for INCR | When set | 5  (%)|
+| PAR2_RUN_VERIFY | Verify after create | When set | false |
+
+Notes:
+
+- PAR2_RATIO_*, and PAR2_RUN_VERIFY apply even if PAR2_DIR is not set (i.e. par2 output stays next to the archives).
+
+Per-backup overrides use a section named after the backup definition with the same PAR2_* keys:
+
+```text
+
+######################################################################
+# Per-backup configuration example overrides
+######################################################################
+
+# --------------------------------------------------------------------
+# Per-backup overrides (section name must match backup.d filename stem)
+# Example: backup.d/home.conf  ->  [home]
+# --------------------------------------------------------------------
+
+#[home]
+# Disable PAR2 entirely for this backup definition
+PAR2_ENABLED = false
+#
+#[media]
+# Store PAR2 files in a separate location for this backup definition
+#PAR2_DIR = /samba/par2/media
+# Raise redundancy only for FULL
+#
+[documents]
+# Run verify par2 sets after creation
+PAR2_RUN_VERIFY = true
+#
+#[etc]
+# Keep global PAR2 settings but tweak ratios for this backup definition
+# RATIO is given in percent (%)
+#PAR2_RATIO_FULL = 15  
+#PAR2_RATIO_DIFF = 8
+#PAR2_RATIO_INCR = 8
+```
+
+[Per-backup override test case: `tests/test_par2_overrides.py`](v2/tests/test_par2_overrides.py)
+
+#### 1.0.2
+
+##### Trace Logging
+
+To support debugging without cluttering the main log file, a secondary trace log is now created (e.g., `dar-backup.trace.log`).
+This file captures all `DEBUG` level messages and full exception stack traces.
+
+You can configure its rotation in the `[MISC]` section:
+
+- `TRACE_LOG_MAX_BYTES`: Max size of the trace log file in bytes. Default is `10485760` (10 MB).
+- `TRACE_LOG_BACKUP_COUNT`: Number of rotated trace log files to keep. Default is `1`.
+
+Example:
+
+```ini
+[MISC]
+TRACE_LOG_MAX_BYTES = 10485760
+TRACE_LOG_BACKUP_COUNT = 1
+```
+
+##### Command output Capture
+
+- New optional `[MISC]` setting: `COMMAND_CAPTURE_MAX_BYTES` (default 102400).
+  - Limits how much stdout/stderr is kept in memory per command while still logging full output.
+  - Set to `0` to disable buffering entirely. Command output is still streamed to dar-backup-commands.log
+  - If set to `0`, the calling function cannot rely on output from the executed command. The exit value is the only result provided.
+
+Example:
+
+```ini
+[MISC]
+COMMAND_CAPTURE_MAX_BYTES = 102400
+```

dar_backup/__about__.py

@@ -1,6 +1,7 @@
-__version__ = "1.0.0.1"
+__version__ = "1.0.2"
+
+__author__ = "Per Jensen"
 
 __license__ = '''Licensed under GNU GENERAL PUBLIC LICENSE v3, see the supplied file "LICENSE" for details.
 THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW, not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 See section 15 and section 16 in the supplied "LICENSE" file.'''
-