dar-backup 0.8.1__tar.gz → 0.8.3__tar.gz

{dar_backup-0.8.1/src/dar_backup → dar_backup-0.8.3}/Changelog.md

@@ -1,6 +1,34 @@
 <!-- markdownlint-disable MD024 -->
 # dar-backup Changelog
 
+## v2-beta-0.8.3 - 2025-08-23
+
+Github link: [v2-beta-0.8.3](https://github.com/per2jensen/dar-backup/tree/v2-beta-0.8.3/v2)
+
+### Added
+
+- Dar-backup now deletes files if noted as "removed" in the archive catalog for DIFF and INCR backups.
+  - This ensures a restore of a FULL + DIFF + INCR matches the files in the source directories.
+  - Options '-wa' & '-/ Oo'  added to the restore command.
+
+## v2-beta-0.8.2 - 2025-07-17
+
+Github link: [v2-beta-0.8.2](https://github.com/per2jensen/dar-backup/tree/v2-beta-0.8.2/v2)
+
+### Added
+
+- Security hardening: CommandRunner now performs strict command-line sanitization
+  - Disallows potentially dangerous characters (e.g. ;, &, |) in command arguments
+  - Prevents injection-style misuse when restoring specific files or invoking custom commands
+
+- Documentation:
+  - New [README section](https://github.com/per2jensen/dar-backup?tab=readme-ov-file#limitations-on-file-names-with-special-characters) explains filename restrictions and safe workarounds (e.g. restoring directly with dar, if needed)
+  - Includes a Markdown table listing all disallowed characters
+
+- Test suite:
+  - Existing test cases updated to comply with the new sanitization rules
+  - Additional tests ensure CommandRunner handles large binary output and edge cases cleanly
+
 ## v2-beta-0.8.1 - 2025-07-16
 
 Github link: [v2-beta-0.8.1](https://github.com/per2jensen/dar-backup/tree/v2-beta-0.8.1/v2)

{dar_backup-0.8.1 → dar_backup-0.8.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dar-backup
-Version: 0.8.1
+Version: 0.8.3
 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
@@ -740,71 +740,90 @@ This is the `Python` based [**version 2**](https://github.com/per2jensen/dar-bac
 
 ## Table of Contents
 
-- [Reliable `dar` backups wrapped in Python](#dar-backup)
-- [My use case](#my-use-case)
-- [Features](#features)
-- [License](#license)
-- [Changelog version 2](https://github.com/per2jensen/dar-backup/blob/main/v2/Changelog.md)
-- [Quick Guide](#quick-guide)
-- [Status](#status)
-  - [GPG Signing key](#gpg-signing-key)
-  - [Breaking change in version 0.6.0](#breaking-change-in-version-060)
-- [Homepage - Github](#homepage---github)
-- [Community](#community)
-- [Requirements](#requirements)
-- [Principles](#dar-backup-principles)
-- [How to run](#how-to-run)
-  - [1 - installation](#1---installation)
-  - [2 - configuration](#2---configuration)
-  - [3 - generate catalog databases](#3---generate-catalog-databases)
-  - [4 - give `dar-backup` a spin](#4---give-dar-backup-a-spin)
-  - [5 - deactivate venv](#5---deactivate-venv)
-- [Config](#config)
-  - [Config file](#config-file)
-  - [.darrc](#darrc)
-  - [Backup definition](#backup-definition-example)
-- [Systemd examples](#systemctl-examples)
+- [`dar-backup`](#dar-backup)
+  - [TL;DR](#tldr)
+  - [Table of Contents](#table-of-contents)
+  - [My use case](#my-use-case)
+  - [Features](#features)
+  - [License](#license)
+  - [Quick Guide](#quick-guide)
+  - [Status](#status)
+    - [GPG Signing key](#gpg-signing-key)
+    - [Breaking change in version 0.6.0](#breaking-change-in-version-060)
+  - [Homepage - Github](#homepage---github)
+  - [Community](#community)
+  - [Requirements](#requirements)
+  - [dar-backup principles](#dar-backup-principles)
+    - [dar-backup](#dar-backup-1)
+    - [cleanup](#cleanup)
+    - [manager](#manager)
+  - [How to run](#how-to-run)
+    - [1 - installation](#1---installation)
+    - [2 - configuration](#2---configuration)
+    - [3 - generate catalog databases](#3---generate-catalog-databases)
+    - [4 - give dar-backup a spin](#4---give-dar-backup-a-spin)
+    - [5 - deactivate venv](#5---deactivate-venv)
+  - [Config](#config)
+    - [Config file](#config-file)
+    - [.darrc](#darrc)
+    - [Backup definition example](#backup-definition-example)
   - [Generate systemd files](#generate-systemd-files)
-  - [Service: dar-back --incremental-backup](#service-dar-backup---incremental-backup)
-  - [Timer: dar-back --incremental-backup](#timer-dar-backup---incremental-backup)
-  - [Systemd timer note](#systemd-timer-note)
-- [List contents of an archive](#list-contents-of-an-archive)
-- [dar file selection examples](#dar-file-selection-examples)
-  - [Select a directory](#select-a-directory)
-  - [Include and exclude some file](#select-files-with-z50-in-the-file-name-and-exclude-xmp-files)
-- [Restoring](#restoring)
-  - [Default location for restores](#default-location-for-restores)
-  - [--restore-dir option](#--restore-dir-option)
-  - [A single file](#a-single-file)
-  - [A directory](#a-directory)
-  - [.NEF from a specific date](#nef-from-a-specific-date)
-  - [Restore test fails with exit code 4](#restore-test-fails-with-exit-code-4)
-  - [Restore test fails with exit code 5](#restore-test-fails-with-exit-code-5)
-- [Par2](#par2)
-  - [Par2 to verify/repair](#par2-to-verifyrepair)
-  - [Par2 create redundancy files](#par2-create-redundancy-files)
-- [Points of interest](#points-of-interest)
-  - [Merge FULL with DIFF, creating new FULL](#merge-full-with-diff-creating-new-full)
-  - [dar manager databases](#dar-manager-databases)
-  - [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)
-  - [Skipping cache directories](#skipping-cache-directories)
-  - [Progress bar + current directory](#progress-bar-and-current-directory)
-  - [Shell Autocompletion](#shell-autocompletion)
+  - [Systemctl examples](#systemctl-examples)
+  - [Service: dar-backup --incremental-backup](#service-dar-backup---incremental-backup)
+  - [Timer: dar-backup --incremental-backup](#timer-dar-backup---incremental-backup)
+  - [systemd timer note](#systemd-timer-note)
+  - [list contents of an archive](#list-contents-of-an-archive)
+  - [dar file selection examples](#dar-file-selection-examples)
+    - [select a directory](#select-a-directory)
+    - [select files with "Z50" in the file name and exclude .xmp files](#select-files-with-z50-in-the-file-name-and-exclude-xmp-files)
+  - [Restoring](#restoring)
+    - [default location for restores](#default-location-for-restores)
+    - [--restore-dir option](#--restore-dir-option)
+    - [a single file](#a-single-file)
+    - [a directory](#a-directory)
+    - [.NEF from a specific date](#nef-from-a-specific-date)
+    - [restore test fails with exit code 4](#restore-test-fails-with-exit-code-4)
+    - [restore test fails with exit code 5](#restore-test-fails-with-exit-code-5)
+  - [Par2](#par2)
+    - [Par2 to verify/repair](#par2-to-verifyrepair)
+    - [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)
+      - [Why this matters](#why-this-matters)
+      - [Workarounds](#workarounds)
+        - [Restoring Files with Forbidden Characters in Their Names](#restoring-files-with-forbidden-characters-in-their-names)
+        - [Backups: Safe and Fully Functional](#backups-safe-and-fully-functional)
+        - [Restores via CLI: Limited by Sanitizer](#restores-via-cli-limited-by-sanitizer)
+        - [Workaround: Use `dar` Directly](#workaround-use-dar-directly)
+        - [Example: Manual Restore Using `dar`](#example-manual-restore-using-dar)
+        - [🧪 How to Locate Files with Forbidden Characters](#-how-to-locate-files-with-forbidden-characters)
+      - [Summary](#summary)
+    - [Merge FULL with DIFF, creating new FULL](#merge-full-with-diff-creating-new-full)
+    - [dar manager databases](#dar-manager-databases)
+    - [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)
+    - [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)
+      - [Enabling Bash completion](#enabling-bash-completion)
+      - [Enable Zsh Completion](#enable-zsh-completion)
   - [Easy development setup](#easy-development-setup)
-- [Todo](#todo)
-- [Known Limitations / Edge Cases](#known-limitations--edge-cases)
-- [Reference](#reference)
-  - [CLI Tools Overview](#cli-tools-overview)
-  - [Test coverage report](#test-coverage)
-  - [dar-backup](#dar-backup-options)
-  - [manager](#manager-options)
-  - [cleanup](#cleanup-options)
-  - [clean-log](#clean-log-options)
-  - [dar-backup-systemd](#dar-backup-systemd-options)
-  - [Installer](#installer-options)
-  - [demo](#demo-options)
+  - [Todo](#todo)
+  - [Known Limitations / Edge Cases](#known-limitations--edge-cases)
+  - [Projects these scripts benefit from](#projects-these-scripts-benefit-from)
+  - [Reference](#reference)
+    - [CLI Tools Overview](#cli-tools-overview)
+    - [test coverage](#test-coverage)
+    - [Dar-backup options](#dar-backup-options)
+    - [Manager Options](#manager-options)
+    - [Cleanup options](#cleanup-options)
+    - [Clean-log options](#clean-log-options)
+    - [Dar-backup-systemd options](#dar-backup-systemd-options)
+    - [Installer options](#installer-options)
+    - [Demo options](#demo-options)
   
 ## My use case
 
@@ -1901,6 +1920,109 @@ where "c" is create, -r5 is 5% redundency and -n1 is 1 redundency file
 
 ## Points of interest
 
+### Limitations on File Names with Special Characters
+
+`dar-backup` strictly validates all command-line arguments passed to its internal execution engine to protect against command injection and shell-based attacks. As part of this security measure, certain characters are disallowed in user-provided inputs — particularly those that carry special meaning in shell environments:
+
+Disallowed characters include:
+
+```text
+\$ & ; | > < ` \n
+```
+
+#### Why this matters
+
+When restoring specific files using the --selection argument or similar mechanisms, filenames that contain one or more of these characters (e.g., file_with_currency$.txt) cannot be safely passed as command-line arguments. As a result, attempting to restore such a file by name using the CLI will result in a validation error.
+
+✅ Backups and Restores Still Work
+
+  ✅ These files are still backed up and restored automatically as part of normal FULL, DIFF, or INCR operations.
+
+  ❌ They cannot be explicitly specified for restore using CLI options like --selection="-g path/to/file_with_currency$.txt".
+
+#### Workarounds
+
+If you need to restore such a file:
+
+  Perform a restore of the entire directory using a more general selection (e.g., --selection="-g path/to/parent-directory").
+
+  Manually retrieve the restored file afterward.
+
+##### Restoring Files with Forbidden Characters in Their Names
+
+The DAR Backup system enforces a strict command-line argument sanitizer to improve security and prevent shell injection attacks. As a result, certain characters are **not allowed** in filenames or arguments passed to the CLI, especially during restore operations. This includes characters like:
+
+| Character | Reason Blocked                  |
+|----------:|---------------------------------|
+| `;`       | Shell command separator         |
+| `&`       | Background execution operator   |
+| `\|`      | Pipe operator                   |
+| `<` / `>` | Redirection operators           |
+| `#`       | Shell comment                   |
+| `` ` ``   | Command substitution            |
+| `"` / `'` | Quoting that may be unbalanced  |
+
+However, **backups of files with such names still work** — they are preserved correctly within the archive. The limitation only applies to **invoking restore commands via the CLI**, where such filenames cannot be safely passed as arguments.
+
+##### Backups: Safe and Fully Functional
+
+Files with special characters in their names **are backed up without issue**. The only issue you might encounter is restoring a file and giving the file name on the command line (with forbidden characters.)
+
+##### Restores via CLI: Limited by Sanitizer
+
+Attempting to restore such files via:
+
+```bash
+    dar-backup restore --file "weird#name.txt"
+```
+
+...will fail with an error like:
+
+```bash
+    Unsafe argument detected: weird#name.txt
+```
+
+---
+
+##### Workaround: Use `dar` Directly
+
+You can always restore the file manually using the `dar` command-line utility itself, bypassing any CLI restrictions imposed by the backup tool.
+
+##### Example: Manual Restore Using `dar`
+
+```bash
+    dar -x /path/to/backup/example -g "weird#name.txt"
+```
+
+Where:
+
+- `/path/to/backup/example` is the base name of the archive (without `.dar`, `.1.dar`, etc.).
+- `"weird#name.txt"` is the exact filename with the special character(s).
+
+You may need to quote the argument or escape characters depending on your shell.
+
+---
+
+##### 🧪 How to Locate Files with Forbidden Characters
+
+To search for such files inside the archive:
+
+```bash
+    dar -l /path/to/backup/example | grep '[#;<>|&]'
+```
+
+This will help you identify files that require manual restoration.
+
+---
+
+#### Summary
+
+- 🚫 Forbidden characters are blocked **only** in CLI arguments to maintain safety.
+- ✅ Files containing these characters are **still archived and restorable**.
+- 🛠 Use `dar` directly for full manual control when restoring such files.
+
+
+
 ### Merge FULL with DIFF, creating new FULL
 
 Over time, the DIFF archives become larger and larger. At some point one wishes to create a new FULL archive to do DIFF's on.
@@ -2234,12 +2356,18 @@ Available options:
 --list-contents <archive>            List the contents of a specified archive.
 --selection <params>                 Define file selection for listing/restoring.
 --restore <archive>                  Restore a specified archive.
--r, --restore-dir <path>             Directory to restore files to.
+-r, --restore <archive>              Restore archive.
+--restore-dir                        Directory on which to restore
 --verbose                            Enable verbose output.
 --suppress-dar-msg                   Filter out this from the darrc: "-vt", "-vs", "-vd", "-vf", "-va"
 --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.
+--examples                           Show examples of using dar-backup.
+--readme                             Print README.md and exit
+--readme-pretty                      Print README.md with Markdown styling and exit
+--changelog                          Print Changelog and exit
+--changelog-pretty                   Print Changelog with Markdown styling and exit
 -v, --version                         Show version and license information.
 ```
 

{dar_backup-0.8.1 → dar_backup-0.8.3}/README.md

@@ -22,71 +22,90 @@ This is the `Python` based [**version 2**](https://github.com/per2jensen/dar-bac
 
 ## Table of Contents
 
-- [Reliable `dar` backups wrapped in Python](#dar-backup)
-- [My use case](#my-use-case)
-- [Features](#features)
-- [License](#license)
-- [Changelog version 2](https://github.com/per2jensen/dar-backup/blob/main/v2/Changelog.md)
-- [Quick Guide](#quick-guide)
-- [Status](#status)
-  - [GPG Signing key](#gpg-signing-key)
-  - [Breaking change in version 0.6.0](#breaking-change-in-version-060)
-- [Homepage - Github](#homepage---github)
-- [Community](#community)
-- [Requirements](#requirements)
-- [Principles](#dar-backup-principles)
-- [How to run](#how-to-run)
-  - [1 - installation](#1---installation)
-  - [2 - configuration](#2---configuration)
-  - [3 - generate catalog databases](#3---generate-catalog-databases)
-  - [4 - give `dar-backup` a spin](#4---give-dar-backup-a-spin)
-  - [5 - deactivate venv](#5---deactivate-venv)
-- [Config](#config)
-  - [Config file](#config-file)
-  - [.darrc](#darrc)
-  - [Backup definition](#backup-definition-example)
-- [Systemd examples](#systemctl-examples)
+- [`dar-backup`](#dar-backup)
+  - [TL;DR](#tldr)
+  - [Table of Contents](#table-of-contents)
+  - [My use case](#my-use-case)
+  - [Features](#features)
+  - [License](#license)
+  - [Quick Guide](#quick-guide)
+  - [Status](#status)
+    - [GPG Signing key](#gpg-signing-key)
+    - [Breaking change in version 0.6.0](#breaking-change-in-version-060)
+  - [Homepage - Github](#homepage---github)
+  - [Community](#community)
+  - [Requirements](#requirements)
+  - [dar-backup principles](#dar-backup-principles)
+    - [dar-backup](#dar-backup-1)
+    - [cleanup](#cleanup)
+    - [manager](#manager)
+  - [How to run](#how-to-run)
+    - [1 - installation](#1---installation)
+    - [2 - configuration](#2---configuration)
+    - [3 - generate catalog databases](#3---generate-catalog-databases)
+    - [4 - give dar-backup a spin](#4---give-dar-backup-a-spin)
+    - [5 - deactivate venv](#5---deactivate-venv)
+  - [Config](#config)
+    - [Config file](#config-file)
+    - [.darrc](#darrc)
+    - [Backup definition example](#backup-definition-example)
   - [Generate systemd files](#generate-systemd-files)
-  - [Service: dar-back --incremental-backup](#service-dar-backup---incremental-backup)
-  - [Timer: dar-back --incremental-backup](#timer-dar-backup---incremental-backup)
-  - [Systemd timer note](#systemd-timer-note)
-- [List contents of an archive](#list-contents-of-an-archive)
-- [dar file selection examples](#dar-file-selection-examples)
-  - [Select a directory](#select-a-directory)
-  - [Include and exclude some file](#select-files-with-z50-in-the-file-name-and-exclude-xmp-files)
-- [Restoring](#restoring)
-  - [Default location for restores](#default-location-for-restores)
-  - [--restore-dir option](#--restore-dir-option)
-  - [A single file](#a-single-file)
-  - [A directory](#a-directory)
-  - [.NEF from a specific date](#nef-from-a-specific-date)
-  - [Restore test fails with exit code 4](#restore-test-fails-with-exit-code-4)
-  - [Restore test fails with exit code 5](#restore-test-fails-with-exit-code-5)
-- [Par2](#par2)
-  - [Par2 to verify/repair](#par2-to-verifyrepair)
-  - [Par2 create redundancy files](#par2-create-redundancy-files)
-- [Points of interest](#points-of-interest)
-  - [Merge FULL with DIFF, creating new FULL](#merge-full-with-diff-creating-new-full)
-  - [dar manager databases](#dar-manager-databases)
-  - [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)
-  - [Skipping cache directories](#skipping-cache-directories)
-  - [Progress bar + current directory](#progress-bar-and-current-directory)
-  - [Shell Autocompletion](#shell-autocompletion)
+  - [Systemctl examples](#systemctl-examples)
+  - [Service: dar-backup --incremental-backup](#service-dar-backup---incremental-backup)
+  - [Timer: dar-backup --incremental-backup](#timer-dar-backup---incremental-backup)
+  - [systemd timer note](#systemd-timer-note)
+  - [list contents of an archive](#list-contents-of-an-archive)
+  - [dar file selection examples](#dar-file-selection-examples)
+    - [select a directory](#select-a-directory)
+    - [select files with "Z50" in the file name and exclude .xmp files](#select-files-with-z50-in-the-file-name-and-exclude-xmp-files)
+  - [Restoring](#restoring)
+    - [default location for restores](#default-location-for-restores)
+    - [--restore-dir option](#--restore-dir-option)
+    - [a single file](#a-single-file)
+    - [a directory](#a-directory)
+    - [.NEF from a specific date](#nef-from-a-specific-date)
+    - [restore test fails with exit code 4](#restore-test-fails-with-exit-code-4)
+    - [restore test fails with exit code 5](#restore-test-fails-with-exit-code-5)
+  - [Par2](#par2)
+    - [Par2 to verify/repair](#par2-to-verifyrepair)
+    - [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)
+      - [Why this matters](#why-this-matters)
+      - [Workarounds](#workarounds)
+        - [Restoring Files with Forbidden Characters in Their Names](#restoring-files-with-forbidden-characters-in-their-names)
+        - [Backups: Safe and Fully Functional](#backups-safe-and-fully-functional)
+        - [Restores via CLI: Limited by Sanitizer](#restores-via-cli-limited-by-sanitizer)
+        - [Workaround: Use `dar` Directly](#workaround-use-dar-directly)
+        - [Example: Manual Restore Using `dar`](#example-manual-restore-using-dar)
+        - [🧪 How to Locate Files with Forbidden Characters](#-how-to-locate-files-with-forbidden-characters)
+      - [Summary](#summary)
+    - [Merge FULL with DIFF, creating new FULL](#merge-full-with-diff-creating-new-full)
+    - [dar manager databases](#dar-manager-databases)
+    - [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)
+    - [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)
+      - [Enabling Bash completion](#enabling-bash-completion)
+      - [Enable Zsh Completion](#enable-zsh-completion)
   - [Easy development setup](#easy-development-setup)
-- [Todo](#todo)
-- [Known Limitations / Edge Cases](#known-limitations--edge-cases)
-- [Reference](#reference)
-  - [CLI Tools Overview](#cli-tools-overview)
-  - [Test coverage report](#test-coverage)
-  - [dar-backup](#dar-backup-options)
-  - [manager](#manager-options)
-  - [cleanup](#cleanup-options)
-  - [clean-log](#clean-log-options)
-  - [dar-backup-systemd](#dar-backup-systemd-options)
-  - [Installer](#installer-options)
-  - [demo](#demo-options)
+  - [Todo](#todo)
+  - [Known Limitations / Edge Cases](#known-limitations--edge-cases)
+  - [Projects these scripts benefit from](#projects-these-scripts-benefit-from)
+  - [Reference](#reference)
+    - [CLI Tools Overview](#cli-tools-overview)
+    - [test coverage](#test-coverage)
+    - [Dar-backup options](#dar-backup-options)
+    - [Manager Options](#manager-options)
+    - [Cleanup options](#cleanup-options)
+    - [Clean-log options](#clean-log-options)
+    - [Dar-backup-systemd options](#dar-backup-systemd-options)
+    - [Installer options](#installer-options)
+    - [Demo options](#demo-options)
   
 ## My use case
 
@@ -1183,6 +1202,109 @@ where "c" is create, -r5 is 5% redundency and -n1 is 1 redundency file
 
 ## Points of interest
 
+### Limitations on File Names with Special Characters
+
+`dar-backup` strictly validates all command-line arguments passed to its internal execution engine to protect against command injection and shell-based attacks. As part of this security measure, certain characters are disallowed in user-provided inputs — particularly those that carry special meaning in shell environments:
+
+Disallowed characters include:
+
+```text
+\$ & ; | > < ` \n
+```
+
+#### Why this matters
+
+When restoring specific files using the --selection argument or similar mechanisms, filenames that contain one or more of these characters (e.g., file_with_currency$.txt) cannot be safely passed as command-line arguments. As a result, attempting to restore such a file by name using the CLI will result in a validation error.
+
+✅ Backups and Restores Still Work
+
+  ✅ These files are still backed up and restored automatically as part of normal FULL, DIFF, or INCR operations.
+
+  ❌ They cannot be explicitly specified for restore using CLI options like --selection="-g path/to/file_with_currency$.txt".
+
+#### Workarounds
+
+If you need to restore such a file:
+
+  Perform a restore of the entire directory using a more general selection (e.g., --selection="-g path/to/parent-directory").
+
+  Manually retrieve the restored file afterward.
+
+##### Restoring Files with Forbidden Characters in Their Names
+
+The DAR Backup system enforces a strict command-line argument sanitizer to improve security and prevent shell injection attacks. As a result, certain characters are **not allowed** in filenames or arguments passed to the CLI, especially during restore operations. This includes characters like:
+
+| Character | Reason Blocked                  |
+|----------:|---------------------------------|
+| `;`       | Shell command separator         |
+| `&`       | Background execution operator   |
+| `\|`      | Pipe operator                   |
+| `<` / `>` | Redirection operators           |
+| `#`       | Shell comment                   |
+| `` ` ``   | Command substitution            |
+| `"` / `'` | Quoting that may be unbalanced  |
+
+However, **backups of files with such names still work** — they are preserved correctly within the archive. The limitation only applies to **invoking restore commands via the CLI**, where such filenames cannot be safely passed as arguments.
+
+##### Backups: Safe and Fully Functional
+
+Files with special characters in their names **are backed up without issue**. The only issue you might encounter is restoring a file and giving the file name on the command line (with forbidden characters.)
+
+##### Restores via CLI: Limited by Sanitizer
+
+Attempting to restore such files via:
+
+```bash
+    dar-backup restore --file "weird#name.txt"
+```
+
+...will fail with an error like:
+
+```bash
+    Unsafe argument detected: weird#name.txt
+```
+
+---
+
+##### Workaround: Use `dar` Directly
+
+You can always restore the file manually using the `dar` command-line utility itself, bypassing any CLI restrictions imposed by the backup tool.
+
+##### Example: Manual Restore Using `dar`
+
+```bash
+    dar -x /path/to/backup/example -g "weird#name.txt"
+```
+
+Where:
+
+- `/path/to/backup/example` is the base name of the archive (without `.dar`, `.1.dar`, etc.).
+- `"weird#name.txt"` is the exact filename with the special character(s).
+
+You may need to quote the argument or escape characters depending on your shell.
+
+---
+
+##### 🧪 How to Locate Files with Forbidden Characters
+
+To search for such files inside the archive:
+
+```bash
+    dar -l /path/to/backup/example | grep '[#;<>|&]'
+```
+
+This will help you identify files that require manual restoration.
+
+---
+
+#### Summary
+
+- 🚫 Forbidden characters are blocked **only** in CLI arguments to maintain safety.
+- ✅ Files containing these characters are **still archived and restorable**.
+- 🛠 Use `dar` directly for full manual control when restoring such files.
+
+
+
 ### Merge FULL with DIFF, creating new FULL
 
 Over time, the DIFF archives become larger and larger. At some point one wishes to create a new FULL archive to do DIFF's on.
@@ -1516,12 +1638,18 @@ Available options:
 --list-contents <archive>            List the contents of a specified archive.
 --selection <params>                 Define file selection for listing/restoring.
 --restore <archive>                  Restore a specified archive.
--r, --restore-dir <path>             Directory to restore files to.
+-r, --restore <archive>              Restore archive.
+--restore-dir                        Directory on which to restore
 --verbose                            Enable verbose output.
 --suppress-dar-msg                   Filter out this from the darrc: "-vt", "-vs", "-vd", "-vf", "-va"
 --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.
+--examples                           Show examples of using dar-backup.
+--readme                             Print README.md and exit
+--readme-pretty                      Print README.md with Markdown styling and exit
+--changelog                          Print Changelog and exit
+--changelog-pretty                   Print Changelog with Markdown styling and exit
 -v, --version                         Show version and license information.
 ```
 

{dar_backup-0.8.1 → dar_backup-0.8.3}/doc/badges/badge_clones.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
   "label": "# clones",
-  "message": "1453",
+  "message": "1820",
   "color": "deeppink"
 }