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

{dar_backup-1.0.0.1.dist-info → dar_backup-1.0.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dar-backup
-Version: 1.0.0.1
+Version: 1.0.2
 Summary: A script to do full, differential and incremental backups using dar.     Some files are restored from the backups during verification, after which par2 redundancy files are created.     The script also has a cleanup feature to remove old backups and par2 files.
 Project-URL: GPG Public Key, https://keys.openpgp.org/search?q=dar-backup@pm.me
 Project-URL: Homepage, https://github.com/per2jensen/dar-backup/tree/main/v2
@@ -686,9 +686,9 @@ Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: End Users/Desktop
 Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
 Classifier: Operating System :: POSIX :: Linux
-Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.11
 Classifier: Topic :: System :: Archiving :: Backup
-Requires-Python: >=3.9
+Requires-Python: >=3.11
 Requires-Dist: argcomplete>=3.6.2
 Requires-Dist: inputimeout>=1.0.4
 Requires-Dist: jinja2>=3.1.6
@@ -722,17 +722,19 @@ Description-Content-Type: text/markdown
 **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
 
@@ -746,6 +748,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)
@@ -789,6 +794,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)
@@ -806,8 +813,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)
@@ -821,12 +828,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
 
@@ -836,7 +853,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
 
@@ -847,6 +864,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.
@@ -869,7 +928,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
 
@@ -1214,7 +1273,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
 
@@ -1234,7 +1293,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
 
@@ -1263,6 +1322,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.
@@ -1406,7 +1474,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.
 
@@ -1442,6 +1510,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]
@@ -1453,6 +1532,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`.
@@ -1774,6 +1863,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`
@@ -1900,9 +2008,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
@@ -1916,6 +2054,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.
@@ -1929,6 +2075,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
@@ -2083,23 +2238,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
 
@@ -2284,7 +2445,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`
 
@@ -2309,15 +2469,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
 
@@ -2372,6 +2532,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.
@@ -2381,6 +2542,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
@@ -2389,6 +2551,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.
@@ -2408,7 +2586,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
 
@@ -2425,12 +2608,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:
@@ -2480,8 +2670,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:
 
@@ -2500,3 +2690,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-1.0.2.dist-info/RECORD

@@ -0,0 +1,25 @@
+dar_backup/.darrc,sha256=-aerqivZmOsW_XBCh9IfbYTUvw0GkzDSr3Vx4GcNB1g,2113
+dar_backup/Changelog.md,sha256=gIAlrXElafjmReneKZlhaPd5FcXU7SJ58_P-huzLTO8,19436
+dar_backup/README.md,sha256=b9w97562AlVTE7ob_5kmf1pc9EiUi7swv8g11M4NOrE,78420
+dar_backup/__about__.py,sha256=0lLpLB4_DxcwxlIZF1F8V8O6WVfjzKepl2PPulVwn2Q,370
+dar_backup/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dar_backup/clean_log.py,sha256=Uf6MjpS_v1IVZdfx7ogRo6j5EIscdxjLImn8GKZo_rc,7038
+dar_backup/cleanup.py,sha256=aC7ogT68u570ufXrzFgpCcxWgzN5dX0o5LIgZhgbQKo,19147
+dar_backup/command_runner.py,sha256=ktK_LmVUZATZlfXPniGLC4W_8x187OzKreK7Dhb5LUA,13123
+dar_backup/config_settings.py,sha256=PKe6iTVeSsN1DW4kTgFbUHsl8S5E-f0I3Lhn4P9a4hs,12723
+dar_backup/dar-backup.conf,sha256=ejucmhEbSdqFU4JEVfrWbFj9H6U87TWSnhex3LraEUY,2124
+dar_backup/dar-backup.conf.j2,sha256=kD13msmP2IXLjnJ9lZmqtLTnsUZq1EkPZAI1LlOkYXo,3852
+dar_backup/dar_backup.py,sha256=997dp6zjXluoenldo19KYtDVt91uMJxoHOI6cIVzohs,69805
+dar_backup/dar_backup_systemd.py,sha256=PwAc2H2J3hQLWpnC6Ib95NZYtB2G2NDgkSblfLj1n10,3875
+dar_backup/demo.py,sha256=KaW-KOqP1sBX4TYJoO-Wr84e81ILI2kN2iV57QU6rbg,8243
+dar_backup/demo_backup_def.j2,sha256=hQW2Glp0QGV3Kt8cwjS0mpOCdyzjVlpgbgL6LpXTKJA,1793
+dar_backup/exceptions.py,sha256=dBQwgKUilgfb1Tnlm_m1Dl1IqoY75L0n1uRkm0DBVTk,158
+dar_backup/installer.py,sha256=yJ0xXi24C1Vo6gnj2BlhV1X55ZIG5t21t8tNKTYSclM,7616
+dar_backup/manager.py,sha256=rctD1WNdSwyEiDw81wnhPyzIVKjrax2QU71PRSx4MqQ,34995
+dar_backup/rich_progress.py,sha256=SfwFxebBl6jnDQMUQr4McknkW1yQWaJVo1Ju1OD3okA,3221
+dar_backup/util.py,sha256=wVyHzdZIQSnXPSup2m0Wx1w-PKx_ornsg4MMEW5AoKs,38608
+dar_backup-1.0.2.dist-info/METADATA,sha256=7_shfQw0tpdJbnlfR46Abd03LxkTzQZj_Xv1mtjNAIM,121126
+dar_backup-1.0.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+dar_backup-1.0.2.dist-info/entry_points.txt,sha256=pOK9M8cHeAcGIatrYzkm_1O89kPk0enyYONALYjFBx4,286
+dar_backup-1.0.2.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+dar_backup-1.0.2.dist-info/RECORD,,

{dar_backup-1.0.0.1.dist-info → dar_backup-1.0.2.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.27.0
+Generator: hatchling 1.28.0
 Root-Is-Purelib: true
 Tag: py3-none-any