dar-backup 0.6.20__py3-none-any.whl → 0.6.21__py3-none-any.whl

dar_backup/README.md

@@ -1,14 +1,18 @@
 <!-- markdownlint-disable MD024 -->
-# Full, differential or incremental backups using 'dar'
+# `dar-backup`
+
+**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)
+![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 monthly downloads](https://img.shields.io/pypi/dm/dar-backup)](https://pypi.org/project/dar-backup/)
 [![Total Downloads](https://img.shields.io/badge/dynamic/json?color=blue&label=Total%20Downloads&query=total&url=https%3A%2F%2Fraw.githubusercontent.com%2Fper2jensen%2Fdar-backup%2Fmain%2Fdownloads.json)](https://pypi.org/project/dar-backup/)
 
 The wonderful 'dar' [Disk Archiver](https://github.com/Edrusb/DAR) is used for
-the heavy lifting, together with the par2 suite in these scripts.
+the heavy lifting, together with the [parchive](https://github.com/Parchive/par2cmdline) suite in these scripts.
 
-This is the `Python` based **version 2** of `dar-backup`.
+This is the `Python` based [**version 2**](https://github.com/per2jensen/dar-backup/tree/main/v2) of `dar-backup`.
 
 ## TL;DR
 
@@ -16,13 +20,15 @@ This is the `Python` based **version 2** of `dar-backup`.
 
 ## Table of Contents
 
-- [Full, differential or incremental backups using 'dar'](#full-differential-or-incremental-backups-using-dar)
+- [Reliable `dar` backups wrapped in Python](#dar-backup)
 - [My use case](#my-use-case)
 - [License](#license)
+- [Changelog version 2](https://github.com/per2jensen/dar-backup/blob/main/v2/Changelog.md)
 - [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)
@@ -43,8 +49,7 @@ This is the `Python` based **version 2** of `dar-backup`.
 - [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 file dates in the directory](#select-file-dates-in-the-directory)
-  - [Exclude .xmp files from that date](#exclude-xmp-files-from-that-date)
+  - [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)
@@ -64,6 +69,7 @@ This is the `Python` based **version 2** of `dar-backup`.
   - [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)
 - [Todo](#todo)
 - [Known Limitations / Edge Cases](#known-limitations--edge-cases)
 - [Reference](#reference)
@@ -73,8 +79,9 @@ This is the `Python` based **version 2** of `dar-backup`.
   - [manager](#manager-options)
   - [cleanup](#cleanup-options)
   - [clean-log](#clean-log-options)
-  - [installer](#installer-options)
   - [dar-backup-systemd](#dar-backup-systemd)
+  - [Installer](#installer)
+  - [demo](#demo)
   
 ## My use case
 
@@ -87,7 +94,7 @@ I have cloud storage mounted on a directory within my home dir. The filesystem i
 
 - Backup my cloud storage to something local (cloud is convenient, but I want control over my backups)
 - Backup primarily photos, video and different types of documents
-- Have a simple non-complicated way of restoring, possibly years into the future. 'dar' fits that scenario with a single statically linked binary (kept with the archives). There is no need install/configure anything - restoring is simple and works well.
+- Have a simple way of restoring, possibly years into the future. 'dar' fits that scenario with a single statically linked binary (kept with the archives). There is no need install/configure anything - restoring is simple and works well.
 - During backup archives must be tested and a restore test (however small) performed
 - Archives stored on a server with a reliable file system (easy to mount a directory over sshfs)
 - Easy to verify archive's integrity, after being moved around.
@@ -97,7 +104,7 @@ I have cloud storage mounted on a directory within my home dir. The filesystem i
 ## License
 
   These scripts are licensed under the GPLv3 license.
-  Read more here: [GNU CPL 3.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"](https://github.com/per2jensen/dar-backup/blob/main/LICENSE) file in this repository.
 
 ## Status
 
@@ -109,9 +116,13 @@ As of February 13, 2025, I have changed the status from alpha --> beta, as the f
 
 To increase the security and authenticity of dar-backup packages, all releases from v2-beta-0.6.18 onwards will be digitally signed using the GPG key below.
 
-🔐 GPG Signing Key Details
+<br>
+
+<details>
+
+<summary>🎯 GPG Signing Key Details</summary>
 
-```` text
+```text
 Name:        Per Jensen (author of dar-backup)
 Email:       dar-backup@pm.me
 Primary key: 4592 D739 6DBA EFFD 0845  02B8 5CCE C7E1 6814 A36E
@@ -120,9 +131,13 @@ Created:     2025-03-29
 Expires:     2030-03-28
 Key type:    ed25519 (primary, SC)  
 Subkeys:     ed25519 (S), ed25519 (A), cv25519 (E)
-````
+```
+
+<br>
 
-🔏 Where to Find Release Signatures
+<details>
+
+<summary>🎯 Where to Find Release Signatures</summary>
 
 PyPI does *Not* host .asc Signature Files
 
@@ -130,7 +145,7 @@ Although the `dar-backup` packages on PyPI are GPG-signed, PyPI itself does **no
 
 Therefore, you will not find `.asc` files on PyPI.
 
-✅ Where to Get `.asc` Signature Files
+**Where to Get `.asc` Signature Files**
 
 You can always download the signed release artifacts and their `.asc` files from the official GitHub Releases page:
 
@@ -146,43 +161,55 @@ Each release includes:
 
 - `dar_backup-x.y.z-py3-none-any.whl.asc`
 
-🔐 How to Verify a Release from GitHub
+</details>
+
+<br>
+
+<details>
+
+<summary>🎯 How to Verify a Release from GitHub</summary>
 
 1. Import the GPG public key:
 
-   ```` bash
+   ```bash
    curl https://keys.openpgp.org/vks/v1/by-fingerprint/4592D7396DBAEFFD084502B85CCEC7E16814A36E | gpg --import
-   ````
+   ```
 
 2. Download the wheel or tarball and its .asc signature from the GitHub.
 
 3. Run GPG to verify it:
 
-   ```` bash
+   ```bash
    gpg --verify dar_backup-x.y.z.tar.gz.asc dar_backup-x.y.z.tar.gz
    # or
    gpg --verify dar_backup-x.y.z-py3-none-any.whl.asc dar_backup-x.y.z-py3-none-any.whl
-   ````
+   ```
 
 4. If the signature is valid, you'll see:
 
-   ```` text
+   ```text
    gpg: Good signature from "Per Jensen (author of dar-backup) <dar-backup@pm.me>"
-   ````
+   ```
 
 🛡️ Reminder: Verify the signing subkey
 
 Only this subkey is used to sign PyPI packages:
 
-```` text
+```text
 B54F 5682 F28D BA36 22D7  8E04 58DB FADB BBAC 1BB1
-````
+```
 
 You can view it with:
 
-```` bash
+```bash
 gpg --list-keys --with-subkey-fingerprints dar-backup@pm.me
-````
+```
+
+</details>
+
+</details>
+
+<br>
 
 ### Breaking change in version 0.6.0
 
@@ -194,17 +221,22 @@ Version 0.6.0 and forwards requires the config variable *COMMAND_TIMEOUT_SECS* i
 
 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.
+
 ## Requirements
 
 - dar
 - par2
 - python3
+- python3-venv
 
 On Ubuntu, install the requirements this way:
 
-```` bash
-    sudo apt install dar par2 python3
-````
+```bash
+    sudo apt install dar par2 python3 python3-venv
+```
 
 ## dar-backup principles
 
@@ -255,7 +287,9 @@ Installation is currently in a venv. These commands are installed in the venv:
 - cleanup
 - manager
 - clean-log
+- dar-backup-systemd
 - installer
+- demo
 
 Note:
 
@@ -263,44 +297,53 @@ The module `inputimeout` is installed into the venv and used for the confirmatio
 
 To install, create a venv and run pip:
 
-```` bash
+```bash
 mkdir $HOME/tmp
 cd $HOME/tmp
 python3 -m venv venv    # create the virtual environment 
 . venv/bin/activate     # activate the virtual env
 pip install dar-backup  # run pip to install `dar-backup`
-````
+```
 
 I have an alias in ~/.bashrc pointing to my venv:
 
-```` bash
+```bash
 alias db=". ~/tmp/venv/bin/activate; dar-backup -v"
-````
+```
 
-Typing `db` at the command line gives this
+drop the alias into ~/.bashrc like this:
 
-```` bash
+```bash
+grep -qxF 'alias db=". ~/tmp/venv/bin/activate; dar-backup -v"' ~/.bashrc \
+  || echo 'alias db=". ~/tmp/venv/bin/activate; dar-backup -v"' >> ~/.bashrc
+
+source ~/.bashrc
+```
+
+Typing `db` at the command line gives something like this:
+
+```bash
 (venv) user@machine:~$ db
 dar-backup 0.6.12
 dar-backup.py source code is here: https://github.com/per2jensen/dar-backup
 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.
-````
+```
 
 ### 2 - configuration
 
-The dar-backup installer is non-destructive and stops if some of the default directories exist.
+The dar-backup `demo` is non-destructive and stops if some of the default directories exist.
 
-Run the installer
+Run `demo`
 
-```` bash
-installer --install
-````
+```bash
+demo --install
+```
 
 The output is
 
-```` text
+```text
 Directories created: `/home/user/dar-backup/` and `/home/user/.config/dar-backup`
 Config file deployed to /home/user/.config/dar-backup/dar-backup.conf
 Default backup definition deployed to /home/user/.config/dar-backup/backup.d/default
@@ -308,7 +351,7 @@ Default backup definition deployed to /home/user/.config/dar-backup/backup.d/def
 2. Then you can run `dar-backup --full-backup` to create a backup.
 3. List backups with `dar-backup --list`
 4. List contents of a backup with `dar-backup --list-contents <backup-name>`
-````
+```
 
 ### 3 - generate catalog databases
 
@@ -316,9 +359,9 @@ Generate the archive catalog database(s).
 
 `dar-backup` expects the catalog databases to be in place, it does not automatically create them (by design)
 
-```` bash
+```bash
 manager --create-db
-````
+```
 
 ### 4 - do FULL backups
 
@@ -327,9 +370,9 @@ Prereq:
 
 You are ready to do backups of all your backup definitions.
 
-```` bash
+```bash
 dar-backup --full-backup 
-````
+```
 
 If you want to see dar-backup's log entries in the terminal, use the `--log-stdout` option. This can be useful if dar-backup is started by systemd.
 
@@ -337,17 +380,17 @@ If you want more log messages, use the `--verbose` or `--log-level debug` for ev
 
 If you want a backup of a single definition, use the `-d <backup definition>` option. The definition's name is the filename of the definition in the `backup.d` config directory.
 
-```` bash
+```bash
 dar-backup --full-backup -d <your backup definition>
-````
+```
 
 ### 5 - deactivate venv
 
 Deactivate the virtual environment (venv)
 
-```` bash
+```bash
 deactivate
-````
+```
 
 ## Config
 
@@ -359,7 +402,7 @@ If you have your config file somewhere else, use the `--config` option to point
 
 Tilde `~` and environment variables can be used in the paths for various file locations.
 
-```` code
+```text
 [MISC]
 LOGFILE_LOCATION=~/.dar-backup.log
 MAX_SIZE_VERIFICATION_MB = 20
@@ -374,6 +417,9 @@ COMMAND_TIMEOUT_SECS = 86400
 BACKUP_DIR = /some/where/dar-backup/backups/
 BACKUP.D_DIR = /some/where/dar-backup/backup.d
 TEST_RESTORE_DIR = /tmp/dar-backup/restore/
+# Optional parameter
+# If you want to store the catalog databases away from the BACKUP_DIR, use the MANAGER_DB_DIR variable.
+#MANAGER_DB_DIR = /some/where/else/
 
 [AGE]
 # age settings are in days
@@ -392,7 +438,7 @@ SCRIPT_1 = ls -l /tmp
 [POSTREQ]
 SCRIPT_1 = df -h
 #SCRIPT_2 = another_script.sh
-````
+```
 
 ### .darrc
 
@@ -402,7 +448,7 @@ You can override the default `.darrc` using the `--darrc` option.
 
 The default `.darrc` contents are as follows:
 
-```` code
+```text
 #  .darrc configuration file for `dar` as used by the `dar-backup` script.
 #  `dar-backup` lives here: https://github.com/per2jensen/dar-backup
 
@@ -523,7 +569,7 @@ compress-exclusion:
 # Now we swap back to case sensitive mode for masks which is the default
 #mode:
 -acase
-````
+```
 
 ### Backup definition example
 
@@ -532,7 +578,7 @@ The name of the file is the name of the backup definition.
 
 You can use as many backup definitions as you need.
 
-```` code
+```text
  # Switch to ordered selection mode, which means that the following
  # options will be considered top to bottom
  -am
@@ -566,7 +612,7 @@ You can use as many backup definitions as you need.
 # http://dar.linux.free.fr/doc/Features.html
 # https://bford.info/cachedir/
 --cache-directory-tagging
-````
+```
 
 ## Generate systemd files
 
@@ -576,7 +622,7 @@ The timers are set as the author uses them, modify to your taste and needs.
 
 Example run:
 
-```` bash
+```bash
 dar-backup-systemd --venv /home/user/tmp/venv --dar-path /home/user/.local/dar/bin
 Generated dar-full-backup.service and dar-full-backup.timer
   → Fires on: *-12-30 10:03:00
@@ -586,7 +632,7 @@ Generated dar-incr-backup.service and dar-incr-backup.timer
   → Fires on: *-*-04/3 19:03:00
 Generated dar-clean.service and dar-clean.timer
   → Fires on: *-*-* 21:07:00
-````
+```
 
 ## Systemctl examples
 
@@ -604,17 +650,17 @@ systemctl --user daemon-reload
 
 Verify your timers are set up as you want:
 
-```` bash
+```bash
 systemctl --user list-timers
-````
+```
 
 ## Service: dar-backup --incremental-backup
 
-This is an exmaple of a systemd user service unit.
+This is an example of a systemd user service unit.
 
 File:  dar-incr-backup.service
 
-```` bash
+```bash
 /tmp/test$ dar-backup-systemd --venv '$HOME/programmer/dar-backup.py/venv'  --dar-path '$HOME/.local/dar/bin'
 
 Generated dar-full-backup.service and dar-full-backup.timer
@@ -640,7 +686,7 @@ RemainAfterExit=no
 
 
 ExecStart=/bin/bash -c 'PATH=$HOME/.local/dar/bin:$PATH && . $HOME/programmer/dar-backup.py/venv/bin/activate && dar-backup -I --verbose --log-stdout'
-````
+```
 
 ## Timer: dar-backup --incremental-backup
 
@@ -648,7 +694,7 @@ This is an example of a systemd user timer
 
 File:  dar-incr-backup.timer
 
-```` code
+```text
 [Unit]
 Description=dar-backup INCR timer
 
@@ -658,7 +704,7 @@ Persistent=true
 
 [Install]
 WantedBy=timers.target
-````
+```
 
 ## systemd timer note
 
@@ -666,118 +712,94 @@ WantedBy=timers.target
 
 ## list contents of an archive
 
-```` bash
-. <the virtual evn>/bin/activate
-dar-backup --list-contents example_FULL_2024-06-23 --selection "-X '*.xmp' -I '*2024-06-16*' -g home/pj/tmp/LUT-play"
+```bash
+# Activate your virtual environment
+source <the virtual evn>/bin/activate
+dar-backup --list-contents media-files_INCR_2025-05-10
+# Deactivate when done
 deactivate
-````
-
-gives
+```
 
-``` code
-[Data ][D][ EA  ][FSA][Compr][S]| Permission | User  | Group | Size    |          Date                 |    filename
---------------------------------+------------+-------+-------+---------+-------------------------------+------------
-[Saved][-]       [-L-][   0%][ ]  drwxr-xr-x   root   root    113 Mio   Sat May 11 16:16:48 2024        home
-[Saved][-]       [-L-][   0%][ ]  drwxrwxr-x   pj     pj      113 Mio   Sun Jun 23 10:46:30 2024        home/pj
-[Saved][-]       [-L-][   0%][ ]  drwxrwxr-x   pj     pj      113 Mio   Sun Jun 23 09:17:42 2024        home/pj/tmp
-[Saved][-]       [-L-][   1%][ ]  drwxrwxr-x   pj     pj      50 Mio    Wed Jun 19 20:52:13 2024        home/pj/tmp/LUT-play
-[Saved][ ]       [-L-][   0%][X]  -rw-rw-r--   pj     pj      49 Mio    Sun Jun 16 12:52:22 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15.NEF
+gives something like
+
+```text
+[Saved][-]       [-L-][   0%][ ]  drwxrwxr-x   pj pj  2 Gio   Sat May 10 14:15:07 2025  home/pj
+[Saved][ ]       [-L-][  93%][ ]  -rw-rw-r--   pj pj  29 kio  Fri May  9 16:45:38 2025  home/pj/data/2023/2023-02-11-Udstilling-Fredericia/DSC_0568.NEF.xmp
+[Saved][-]       [-L-][   0%][ ]  drwxrwxr-x   pj pj  2 Gio   Fri May  9 12:49:04 2025  home/pj/data/2025
+[Saved][-]       [-L-][   1%][ ]  drwxrwxr-x   pj pj  193 Mio Thu May  8 15:59:17 2025  home/pj/data/2025/2025-05-09-Viltrox-25mm-AIR
+[Saved][ ]       [-L-][   1%][X]  -rw-rw-r--   pj pj  15 Mio  Thu May  8 15:52:27 2025  home/pj/data/2025/2025-05-09-Viltrox-25mm-AIR/DSC_0563.NEF
+[Saved][ ]       [-L-][   1%][X]  -rw-rw-r--   pj pj  10 Mio  Thu May  8 15:52:27 2025  home/pj/data/2025/2025-05-09-Viltrox-25mm-AIR/DSC_0563.JPG
+[Saved][ ]       [-L-][   1%][X]  -rw-rw-r--   pj pj  9 Mio   Thu May  8 15:51:53 2025  home/pj/data/2025/2025-05-09-Viltrox-25mm-AIR/DSC_0559.JPG
+[Saved][ ]       [-L-][   1%][X]  -rw-rw-r--   pj pj  16 Mio  Thu May  8 15:51:45 2025  home/pj/data/2025/2025-05-09-Viltrox-25mm-AIR/DSC_0558.NEF
+[Saved][ ]       [-L-][   1%][X]  -rw-rw-r--   pj pj  12 Mio  Thu May  8 15:51:45 2025  home/pj/data/2025/2025-05-09-Viltrox-25mm-AIR/DSC_0558.JPG
+[Saved][ ]       [-L-][   1%][X]  -rw-rw-r--   pj pj  16 Mio  Thu May  8 15:51:24 2025  home/pj/data/2025/2025-05-09-Viltrox-25mm-AIR/DSC_0557.NEF
+[Saved][ ]       [-L-][   1%][X]  -rw-rw-r--   pj pj  12 Mio  Thu May  8 15:51:23 2025  home/pj/data/2025/2025-05-09-Viltrox-25mm-AIR/DSC_0557.JPG
+[Saved][ ]       [-L-][  91%][ ]  -rw-rw-r--   pj pj  22 kio  Thu May  8 15:59:58 2025  home/pj/data/2025/2025-05-09-Viltrox-25mm-AIR/DSC_0557.JPG.xmp
+[Saved][ ]       [-L-][  92%][ ]  -rw-rw-r--   pj pj  30 kio  Thu May  8 16:00:36 2025  home/pj/data/2025/2025-05-09-Viltrox-25mm-AIR/DSC_0557.NEF.xmp
+[Saved][ ]       [-L-][  91%][ ]  -rw-rw-r--   pj pj  22 kio  Thu May  8 16:00:29 2025  home/pj/data/2025/2025-05-09-Viltrox-25mm-AIR/DSC_0558.JPG.xmp
 ```
 
 ## dar file selection examples
 
-### select a directory
+> ⚠️ **Quoting matters**
+>
+> Always pass `--selection` as `--selection="-I '*.NEF'"` to ensure it’s treated as a single argument.
+>
+> Avoid splitting `--selection` and the string into separate tokens.
 
-``` bash
-dar -l /tmp/example_FULL_2024-06-23  -g home/pj/tmp/LUT-play
-```
+**Why does --selection give “expected one argument” error?**
 
-gives
+This happens when the shell splits the quoted string or interprets globs before `dar-backup` sees them.  
+✅ Use:   `--selection="-I '*.NEF'"`  
+❌ Avoid: `--selection "-I '*.NEF'"`  
 
-```` code
-[Data ][D][ EA  ][FSA][Compr][S]| Permission | User  | Group | Size    |          Date                 |    filename
---------------------------------+------------+-------+-------+---------+-------------------------------+------------
-[Saved][-]       [-L-][   0%][ ]  drwxr-xr-x   root   root    113 Mio   Sat May 11 16:16:48 2024        home
-[Saved][-]       [-L-][   0%][ ]  drwxrwxr-x   pj     pj      113 Mio   Sun Jun 23 10:46:30 2024        home/pj
-[Saved][-]       [-L-][   0%][ ]  drwxrwxr-x   pj     pj      113 Mio   Sun Jun 23 09:17:42 2024        home/pj/tmp
-[Saved][-]       [-L-][   1%][ ]  drwxrwxr-x   pj     pj      50 Mio    Wed Jun 19 20:52:13 2024        home/pj/tmp/LUT-play
-[Saved][ ]       [-L-][   0%][X]  -rw-rw-r--   pj     pj      49 Mio    Sun Jun 16 12:52:22 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15.NEF
-[Saved][ ]       [-L-][  95%][ ]  -rw-rw-r--   pj     pj      48 kio    Sat Jun 22 21:51:24 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15.NEF.xmp
-[Saved][ ]       [-L-][  95%][ ]  -rw-rw-r--   pj     pj      50 kio    Sat Jun 22 21:51:25 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_01.NEF.xmp
-[Saved][ ]       [-L-][  95%][ ]  -rw-rw-r--   pj     pj      51 kio    Sat Jun 22 21:51:26 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_02.NEF.xmp
-[Saved][ ]       [-L-][  95%][ ]  -rw-rw-r--   pj     pj      51 kio    Sat Jun 22 21:51:27 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_03.NEF.xmp
-[Saved][ ]       [-L-][  95%][ ]  -rw-rw-r--   pj     pj      51 kio    Sat Jun 22 21:51:27 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_04.NEF.xmp
-[Saved][ ]       [-L-][  97%][ ]  -rw-rw-r--   pj     pj      77 kio    Sat Jun 22 21:50:16 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_05.NEF.xmp
-[Saved][ ]       [-L-][  95%][ ]  -rw-rw-r--   pj     pj      52 kio    Sat Jun 22 21:49:37 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_06.NEF.xmp
-[Saved][ ]       [-L-][  92%][ ]  -rw-rw-r--   pj     pj      24 kio    Sat Jun 22 21:50:47 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_07.NEF.xmp
-[Saved][ ]       [-L-][  92%][ ]  -rw-rw-r--   pj     pj      24 kio    Sat Jun 22 21:51:12 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_08.NEF.xmp
-[Saved][ ]       [-L-][  92%][ ]  -rw-rw-r--   pj     pj      24 kio    Sat Jun 22 21:51:12 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_09.NEF.xmp
-[Saved][ ]       [-L-][  92%][ ]  -rw-rw-r--   pj     pj      24 kio    Sat Jun 22 21:50:39 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_10.NEF.xmp
-[Saved][ ]       [-L-][  92%][ ]  -rw-rw-r--   pj     pj      24 kio    Sat Jun 22 21:50:36 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_11.NEF.xmp
-[Saved][ ]       [-L-][  92%][ ]  -rw-rw-r--   pj     pj      24 kio    Sat Jun 22 21:50:35 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_12.NEF.xmp
-[Saved][ ]       [-L-][  88%][ ]  -rw-rw-r--   pj     pj      15 kio    Sat Jun 22 21:51:11 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_13.NEF.xmp
-[Saved][ ]       [-L-][  96%][ ]  -rw-rw-r--   pj     pj      84 kio    Sat Jun 22 21:51:09 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_14.NEF.xmp
-[Saved][ ]       [-L-][  96%][ ]  -rw-rw-r--   pj     pj      90 kio    Sat Jun 22 21:51:04 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_15.NEF.xmp
-[Saved][ ]       [-L-][  92%][ ]  -rw-rw-r--   pj     pj      24 kio    Sat Jun 22 21:51:15 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_16.NEF.xmp
-[Saved][ ]       [-L-][  92%][ ]  -rw-rw-r--   pj     pj      24 kio    Sat Jun 22 21:50:48 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_17.NEF.xmp
-[Saved][ ]       [-L-][  92%][ ]  -rw-rw-r--   pj     pj      24 kio    Sat Jun 22 21:50:19 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_18.NEF.xmp
-````
+> 💡 **Tip:** See [dar's documentation](http://dar.linux.free.fr/doc/man/dar.html#COMMANDS%20AND%20OPTIONS)
+
+### select a directory
 
-### select file dates in the directory
+Select files and sub directories in `home/pj/data/2025/2025-05-09-Roskilde-Nordisk-udstilling`
 
-``` bash
-dar -l /tmp/example_FULL_2024-06-23  -I '*2024-06-16*' -g home/pj/tmp/LUT-play
+```bash
+dar-backup --list-contents media-files_INCR_2025-05-10 --selection="-g 'home/pj/data/2025/2025-05-09-Roskilde-Nordisk-udstilling'"
 ```
 
 gives
 
-``` code
-[Data ][D][ EA  ][FSA][Compr][S]| Permission | User  | Group | Size    |          Date                 |    filename
---------------------------------+------------+-------+-------+---------+-------------------------------+------------
-[Saved][-]       [-L-][   0%][ ] drwxr-xr-x   root    root    113 Mio   Sat May 11 16:16:48 2024        home
-[Saved][-]       [-L-][   0%][ ]  drwxrwxr-x   pj     pj      113 Mio   Sun Jun 23 10:46:30 2024        home/pj
-[Saved][-]       [-L-][   0%][ ]  drwxrwxr-x   pj     pj      113 Mio   Sun Jun 23 09:17:42 2024        home/pj/tmp
-[Saved][-]       [-L-][   1%][ ]  drwxrwxr-x   pj     pj      50 Mio    Sed Jun 19 20:52:13 2024        home/pj/tmp/LUT-play
-[Saved][ ]       [-L-][   0%][X]  -rw-rw-r--   pj     pj      49 Mio    Sun Jun 16 12:52:22 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15.NEF
-[Saved][ ]       [-L-][  95%][ ]  -rw-rw-r--   pj     pj      48 kio    Sat Jun 22 21:51:24 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15.NEF.xmp
-[Saved][ ]       [-L-][  95%][ ]  -rw-rw-r--   pj     pj      50 kio    Sat Jun 22 21:51:25 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_01.NEF.xmp
-[Saved][ ]       [-L-][  95%][ ]  -rw-rw-r--   pj     pj      51 kio    Sat Jun 22 21:51:26 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_02.NEF.xmp
-[Saved][ ]       [-L-][  95%][ ]  -rw-rw-r--   pj     pj      51 kio    Sat Jun 22 21:51:27 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_03.NEF.xmp
-[Saved][ ]       [-L-][  95%][ ]  -rw-rw-r--   pj     pj      51 kio    Sat Jun 22 21:51:27 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_04.NEF.xmp
-[Saved][ ]       [-L-][  97%][ ]  -rw-rw-r--   pj     pj      77 kio    Sat Jun 22 21:50:16 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_05.NEF.xmp
-[Saved][ ]       [-L-][  95%][ ]  -rw-rw-r--   pj     pj      52 kio    Sat Jun 22 21:49:37 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_06.NEF.xmp
-[Saved][ ]       [-L-][  92%][ ]  -rw-rw-r--   pj     pj      24 kio    Sat Jun 22 21:50:47 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_07.NEF.xmp
-[Saved][ ]       [-L-][  92%][ ]  -rw-rw-r--   pj     pj      24 kio    Sat Jun 22 21:51:12 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_08.NEF.xmp
-[Saved][ ]       [-L-][  92%][ ]  -rw-rw-r--   pj     pj      24 kio    Sat Jun 22 21:51:12 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_09.NEF.xmp
-[Saved][ ]       [-L-][  92%][ ]  -rw-rw-r--   pj     pj      24 kio    Sat Jun 22 21:50:39 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_10.NEF.xmp
-[Saved][ ]       [-L-][  92%][ ]  -rw-rw-r--   pj     pj      24 kio    Sat Jun 22 21:50:36 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_11.NEF.xmp
-[Saved][ ]       [-L-][  92%][ ]  -rw-rw-r--   pj     pj      24 kio    Sat Jun 22 21:50:35 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_12.NEF.xmp
-[Saved][ ]       [-L-][  88%][ ]  -rw-rw-r--   pj     pj      15 kio    Sat Jun 22 21:51:11 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_13.NEF.xmp
-[Saved][ ]       [-L-][  96%][ ]  -rw-rw-r--   pj     pj      84 kio    Sat Jun 22 21:51:09 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_14.NEF.xmp
-[Saved][ ]       [-L-][  96%][ ]  -rw-rw-r--   pj     pj      90 kio    Sat Jun 22 21:51:04 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_15.NEF.xmp
-[Saved][ ]       [-L-][  92%][ ]  -rw-rw-r--   pj     pj      24 kio    Sat Jun 22 21:51:15 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_16.NEF.xmp
-[Saved][ ]       [-L-][  92%][ ]  -rw-rw-r--   pj     pj      24 kio    Sat Jun 22 21:50:48 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_17.NEF.xmp
-[Saved][ ]       [-L-][  92%][ ]  -rw-rw-r--   pj     pj      24 kio    Sat Jun 22 21:50:19 2024        home/pj/tmp/LUT-play/2024-06-16_12:52:22,15_18.NEF.xmp
+```text
+...
+[Saved][ ]       [-L-][   0%][X]  -rw-rw-r--   pj pj 29  Mio Fri May  9 10:33:42 2025 home/pj/data/2025/2025-05-09-Roskilde-Nordisk-udstilling/Z50_0572.NEF
+[Saved][ ]       [-L-][   0%][X]  -rw-rw-r--   pj pj 28  Mio Fri May  9 10:33:12 2025 home/pj/data/2025/2025-05-09-Roskilde-Nordisk-udstilling/Z50_0571.NEF
+[Saved][ ]       [-L-][   0%][X]  -rw-rw-r--   pj pj 25  Mio Fri May  9 10:33:08 2025 home/pj/data/2025/2025-05-09-Roskilde-Nordisk-udstilling/Z50_0570.NEF
+[Saved][ ]       [-L-][   0%][X]  -rw-rw-r--   pj pj 27  Mio Fri May  9 10:32:46 2025 home/pj/data/2025/2025-05-09-Roskilde-Nordisk-udstilling/Z50_0569.NEF
+[Saved][ ]       [-L-][   0%][X]  -rw-rw-r--   pj pj 27  Mio Fri May  9 10:32:46 2025 home/pj/data/2025/2025-05-09-Roskilde-Nordisk-udstilling/Z50_0568.NEF
+[Saved][-]       [-L-][   1%][ ]  drwxrwxr-x   pj pj 833 Mio Fri May  9 12:49:57 2025 home/pj/data/2025/2025-05-09-Roskilde-Nordisk-udstilling/jpeg
+[Saved][ ]       [-L-][   1%][X]  -rw-rw-r--   pj pj 11  Mio Fri May  9 10:32:45 2025 home/pj/data/2025/2025-05-09-Roskilde-Nordisk-udstilling/jpeg/Z50_0568.JPG
+[Saved][ ]       [-L-][   1%][X]  -rw-rw-r--   pj pj 11  Mio Fri May  9 10:32:46 2025 home/pj/data/2025/2025-05-09-Roskilde-Nordisk-udstilling/jpeg/Z50_0569.JPG
+[Saved][ ]       [-L-][   1%][X]  -rw-rw-r--   pj pj 9   Mio Fri May  9 10:33:08 2025 home/pj/data/2025/2025-05-09-Roskilde-Nordisk-udstilling/jpeg/Z50_0570.JPG
+[Saved][ ]       [-L-][   1%][X]  -rw-rw-r--   pj pj 13  Mio Fri May  9 10:33:12 2025 home/pj/data/2025/2025-05-09-Roskilde-Nordisk-udstilling/jpeg/Z50_0571.JPG
+...
 ```
 
-### exclude .xmp files from that date
-
-``` bash
-dar -l /tmp/example_FULL_2024-06-23 -X '*.xmp' -I '*2024-06-16*' -g home/pj/tmp/LUT-play
+### select files with "Z50" in the file name and exclude .xmp files
 
+```bash
+dar-backup --list-contents media-files_INCR_2025-05-10 --selection="-I '*Z50*' -X '*.xmp'"
 ```
 
-gives
-
-```` code
-[Data ][D][ EA  ][FSA][Compr][S]| Permission | User  | Group | Size    |          Date                 |    filename
---------------------------------+------------+-------+-------+---------+-------------------------------+------------
-[Saved][-]       [-L-][   0%][ ]  drwxr-xr-x   root   root    113 Mio   Sat May 11 16:16:48 2024        home
-[Saved][-]       [-L-][   0%][ ]  drwxrwxr-x   pj     pj      113 Mio   Sun Jun 23 10:46:30 2024        ome/pj
-[Saved][-]       [-L-][   0%][ ]  drwxrwxr-x   pj     pj      113 Mio   Sun Jun 23 09:17:42 2024        ome/pj/tmp
-[Saved][-]       [-L-][   1%][ ]  drwxrwxr-x   pj     pj      50 Mio    Wed Jun 19 20:52:13 2024      ` ome/pj/tmp/LUT-play
-[Saved][ ]       [-L-][   0%][X]  -rw-rw-r--   pj     pj      49 Mio    Sun Jun 16 12:52:22 2024      ` home/pj/tmp/LUT-play/2024-06-16_12:52:22,15.NEF
-````
+gives something like
+
+```text
+[Saved][-]       [-L-][   0%][ ]  drwxrwxr-x   pj pj 2   Gio Sat May 10 14:15:07 2025 home/pj
+[Saved][-]       [-L-][   0%][ ]  drwxrwxr-x   pj pj 2   Gio Fri May  9 12:49:04 2025 home/pj/data/2025
+[Saved][-]       [-L-][   1%][ ]  drwxrwxr-x   pj pj 193 Mio Thu May  8 15:59:17 2025 home/pj/data/2025/2025-05-09-Viltrox-25mm-AIR
+[Saved][-]       [-L-][   0%][ ]  drwxrwxr-x   pj pj 2   Gio Fri May  9 16:47:37 2025 home/pj/data/2025/2025-05-09-Roskilde-Nordisk-udstilling
+[Saved][ ]       [-L-][   0%][X]  -rw-rw-r--   pj pj 26  Mio Fri May  9 11:26:16 2025 home/pj/data/2025/2025-05-09-Roskilde-Nordisk-udstilling/Z50_0633.NEF
+[Saved][ ]       [-L-][   0%][X]  -rw-rw-r--   pj pj 26  Mio Fri May  9 11:26:16 2025 home/pj/data/2025/2025-05-09-Roskilde-Nordisk-udstilling/Z50_0632.NEF
+[Saved][ ]       [-L-][   0%][X]  -rw-rw-r--   pj pj 28  Mio Fri May  9 11:09:04 2025 home/pj/data/2025/2025-05-09-Roskilde-Nordisk-udstilling/Z50_0631.NEF
+[Saved][ ]       [-L-][   0%][X]  -rw-rw-r--   pj pj 29  Mio Fri May  9 11:09:03 2025 home/pj/data/2025/2025-05-09-Roskilde-Nordisk-udstilling/Z50_0630.NEF
+[Saved][ ]       [-L-][   0%][X]  -rw-rw-r--   pj pj 29  Mio Fri May  9 11:09:03 2025 home/pj/data/2025/2025-05-09-Roskilde-Nordisk-udstilling/Z50_0629.NEF
+...
+```
 
 ## Restoring
 
@@ -797,7 +819,7 @@ The directory supplied functions as the Root of the restore operation.
 
 A backup has been taken using this backup definition:
 
-``` code
+```text
 -R /
 -g home/user/Documents
 ```
@@ -806,16 +828,15 @@ When restoring and using `/tmp` for --restore-dir, the restored files can be fou
 
 ### a single file
 
-``` code
+```text
 . <the virtual env>/bin/activate
 dar-backup --restore <archive_name> --selection "-g path/to/file"
 deactivate
-
 ```
 
 ### a directory
 
-``` bash
+```bash
 . <the virtual env>/bin/activate
 dar-backup --restore <archive_name> --selection "-g path/to/directory"
 deactivate
@@ -823,7 +844,7 @@ deactivate
 
 ### .NEF from a specific date
 
-``` bash
+```bash
 . <the virtual env>/bin/activate
 dar-backup --restore <archive_name>  --selection "-X '*.xmp' -I '*2024-06-16*' -g home/pj/tmp/LUT-play"
 deactivate
@@ -831,9 +852,9 @@ deactivate
 
 ### restore test fails with exit code 4
 
-"dar" in newer versions emits a question about file ownership, which is "answered" with a "no" via the "-Q" option. That in turn leads to an error code 4.
+`dar` in newer versions emits a question about file ownership, which is "answered" with a "no" via the "-Q" option. That in turn leads to an error code 4.
 
-Thus the dar option "--comparison-field=ignore-owner" has been placed in the supplied [.darrc](#darrc) file (located in the virtual environment where dar-backup is installed).
+Thus the dar option `--comparison-field=ignore-owner` has been placed in the supplied [.darrc](#darrc) file (located in the virtual environment where dar-backup is installed).
 
 This causes dar to restore without an error.
 
@@ -846,7 +867,7 @@ If exit code 5 is emitted on the restore test, FSA (File System specific Attribu
 That (might) occur if you backup a file stored on one type of filesystem, and restore it on another type.
 My home directory is on a btrfs filesystem, while /tmp (for the restore test) is on zfs.
 
-The restore test can result in an exit code 5, due to the different filesystems used. In order to avoid the errors, the "option "--fsa-scope none" can be used. That will restult in FSA's not being restored.
+The restore test can result in an exit code 5, due to the different filesystems used. In order to avoid the errors, the option `--fsa-scope none` can be used. That will restult in FSA's not being restored.
 
 If you need to use this option, un-comment it in the [.darrc](#darrc) file (located in the virtual environment where dar-backup is installed)
 
@@ -856,28 +877,28 @@ If you need to use this option, un-comment it in the [.darrc](#darrc) file (loca
 
 You can run a par2 verification on an archive like this:
 
-```` bash
+```bash
 for file in <archive>*.dar.par2; do
   par2 verify "$file"
 done
-````
+```
 
 if there are problems with a slice, try to repair it like this:
 
-```` bash
+```bash
   par2 repair <archive>.<slice number>.dar.par2
-````
+```
 
 ### Par2 create redundancy files
 
 If you have merged archives, you will need to create the .par2 redundency files manually.
 Here is an example
 
-```` bash
+```bash
 for file in <some-archive>_FULL_yyyy-mm-dd.*; do
   par2 c -r5 -n1 "$file"
 done
-````
+```
 
 where "c" is create, -r5 is 5% redundency and -n1 is 1 redundency file
 
@@ -890,7 +911,7 @@ One way to do that, is to let dar create a FULL archive from scratch, another is
 
 I do backups of my homedir. Here it is shown how a FULL archive is merged with a DIFF, creating a new FULL archive.
 
-```` bash
+```bash
 dar --merge pj-homedir_FULL_2021-09-12  -A pj-homedir_FULL_2021-06-06  -@pj-homedir_DIFF_2021-08-29 -s 12G
 
 # test the new FULL archive
@@ -900,8 +921,7 @@ dar -t pj-homedir_FULL_2021-09-12
 for file in pj-homedir_FULL_yyyy-mm-dd.*.dar; do
   par2 c -r5 -n1 "$file"
 done
-
-````
+```
 
 ### dar manager databases
 
@@ -949,8 +969,144 @@ dar-backup displays 2 visual artifacts to show progress.
 
 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.
 
+### Shell autocompletion
+
+The `dar-backup`, `manager`, and `cleanup` scripts now support dynamic Bash tab-completion, making them easier and faster to use.
+
+✅ Features
+
+- Autocomplete for all long options (--config-file, --restore, etc.)
+
+- Dynamic suggestions based on your config:
+
+- --backup-definition shows available definitions from backup.d/
+
+- show relevant archives when a backup definition has been chosen:
+
+  dar-backup: --restore, --list-contents, and --alternate-reference-archive
+
+  cleanup: --cleanup-specific-archives
+
+  manager:  --list-archive-contents, --add-specific-archive (autocomplete those **not* in the catalog database), --remove-specific-archive
+  
+- Supports paths like ~ and $HOME correctly
+
+#### Use it
+
+Try typing:
+
+```bash
+dar-backup --<TAB>
+```
+
+You should see all available flags like --full-backup, --restore, etc.
+
+Try completion of backup definition and then list contents:
+
+```bash
+    dar-backup --backup-definition <TAB>
+    dar-backup -d <the chosen backup-definition> --list-contents <TAB>
+```
+
+#### Archive name completion (smart, context-aware)
+
+When using `manager--list-archive-contents`, the tab-completer suggests valid archive names.
+
+The behavior is smart and context-aware:
+
+- If a --backup-definition (-d) is provided, archive suggestions are restricted to that .db catalog.
+
+- If no backup definition is given, the completer will:
+
+  - Scan all .db files in the backup_dir
+
+  - Aggregate archive names across all catalogs
+
+  - Sort results by:
+
+    - Backup name (e.g. pCloudDrive, media-files)
+
+    - Date inside the archive name (e.g. 2025-04-19)
+
+It’s blazing fast and designed for large backup sets.
+
+```bash
+# With a backup definition
+manager -d pCloudDrive --list-archive-contents <TAB>
+# ⤷ Suggests: pCloudDrive_FULL_2025-03-04, pCloudDrive_INCR_2025-04-19, ...
+
+# Without a backup definition
+manager --list-archive-contents <TAB>
+# ⤷ Suggests: all archives across all known backup definitions
+# ⤷ Example: media-files_FULL_2025-01-04, pCloudDrive_INCR_2025-04-19, ...
+
+# Filter by prefix
+manager --list-archive-contents media-<TAB>
+# ⤷ Suggests: media-files_FULL_2025-01-04, media-files_INCR_2025-02-20, ...
+```
+
+#### Enabling Bash completion
+
+Try auto completion in your session:
+
+```bash
+eval "$(register-python-argcomplete dar-backup)"
+eval "$(register-python-argcomplete cleanup)"
+eval "$(register-python-argcomplete manager)"
+complete -o nosort -C 'python -m argcomplete cleanup' cleanup
+complete -o nosort -C 'python -m argcomplete manager' manager
+```
+
+To make it persistent across sessions, add this to your ~/.bashrc:
+
+```bash
+# Enable autocompletion for dar-backup
+eval "$(register-python-argcomplete dar-backup)"
+eval "$(register-python-argcomplete cleanup)"
+eval "$(register-python-argcomplete manager)"
+# This disables bash sorting, so sorting is by <backup definition> and <date>
+complete -o nosort -C 'python -m argcomplete cleanup' cleanup
+complete -o nosort -C 'python -m argcomplete manager' manager
+```
+
+If you're using a virtual environment and register-python-argcomplete isn't in your global PATH, use:
+
+```bash
+# Enable autocompletion for dar-backup
+eval "$($(which register-python-argcomplete) dar-backup)"
+eval "$($(which register-python-argcomplete) cleanup)"
+eval "$($(which register-python-argcomplete) manager)"
+
+# If it's not working, try reactivating your virtualenv and restarting your terminal.
+```
+
+Then reload your shell:
+
+```bash
+source ~/.bashrc
+```
+
+#### Enable Zsh Completion
+
+If you're using Zsh, add this to your .zshrc:
+
+```zsh
+autoload -U bashcompinit
+bashcompinit
+eval "$(register-python-argcomplete dar-backup)"
+eval "$(register-python-argcomplete cleanup)"
+eval "$(register-python-argcomplete manager)"
+```
+
+Then reload Zsh:
+
+```zsh
+source ~/.zshrc
+```
+
 ## Todo
 
+- 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`
 
@@ -962,54 +1118,65 @@ One backup definition per file
 
 .par2 files created for each slice (may be moved in future)
 
+## Projects these scripts benefit from
+
+ 1. [The wonderful dar achiver](https://github.com/Edrusb/DAR)
+ 2. [The Parchive suite](https://github.com/Parchive)
+ 3. [shellcheck - a bash linter](https://github.com/koalaman/shellcheck)
+ 4. [Ubuntu of course :-)](https://ubuntu.com/)
+ 5. [PyPI](https://pypi.org/)
+ 6. Tracking PyPI downloads with [pypi-total-downloads-tracker](https://github.com/per2jensen/pypi-total-downloads-tracker)
+
 ## Reference
 
 ### CLI Tools Overview
 
-| Command               | Description                               |
-|-----------------------|-------------------------------------------|
-| `dar-backup`          | Perform full, differential, or incremental backups with verification and restore testing |
-| `manager`             | Maintain and query catalog databases for archives |
-| `cleanup`             | Remove outdated DIFF/INCR archives (and optionally FULLs) |
-| `clean-log`           | Clean up excessive log output from dar command logs |
-| `installer`           | Set up required directories and default config files |
-| `dar-backup-systemd`  | Generate (and optionally install) systemd timers and services for automated backups |
+| 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 default config files |
 
 ### test coverage
 
 Running
 
-```` bash
+```bash
 pytest --cov=dar_backup tests/
-````
+```
 
-results for a dev version 0.6.19 in this report:
+Results for a version 0.6.19 in this report:
 
-```` code
----------- coverage: platform linux, python 3.12.3-final-0 -----------
+```text
 Name                                   Stmts   Miss  Cover
 ----------------------------------------------------------
 src/dar_backup/__about__.py                1      0   100%
 src/dar_backup/__init__.py                 0      0   100%
 src/dar_backup/clean_log.py               68     13    81%
-src/dar_backup/cleanup.py                193     17    91%
-src/dar_backup/command_runner.py          73      1    99%
-src/dar_backup/config_settings.py         66      8    88%
-src/dar_backup/dar_backup.py             535     56    90%
+src/dar_backup/cleanup.py                196     17    91%
+src/dar_backup/command_runner.py          80      3    96%
+src/dar_backup/config_settings.py         66      7    89%
+src/dar_backup/dar_backup.py             539     56    90%
 src/dar_backup/dar_backup_systemd.py      56      7    88%
 src/dar_backup/installer.py               59      6    90%
-src/dar_backup/manager.py                351     56    84%
+src/dar_backup/manager.py                403     54    87%
 src/dar_backup/rich_progress.py           70      7    90%
-src/dar_backup/util.py                   130     15    88%
+src/dar_backup/util.py                   231     24    90%
 ----------------------------------------------------------
-TOTAL                                   1602    186    88%
-````
+TOTAL                                   1769    194    89%
+```
 
-### dar-backup options
+### Dar-backup options
 
-This script does backups, validation and restoring. It has the following options:
+This script does backups including par2 redundancy, validation and restoring.
 
-``` code
+Available options:
+
+```bash
 -F, --full-backup                    Perform a full backup.
 -D, --differential-backup            Perform a differential backup.
 -I, --incremental-backup             Perform an incremental backup.
@@ -1028,34 +1195,39 @@ This script does backups, validation and restoring. It has the following 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.
--v --version                         Show version and license information.
+-v, --version                         Show version and license information.
 ```
 
-### manager options
+### Manager Options
+
+This script manages `dar` databases and catalogs.
 
-This script manages `dar` databases and catalogs. Available options:
+Available options:
 
-``` code
--c, --config-file                    Path to dar-backup.conf
+```bash
+-c, --config-file <path>             Path to dar-backup.conf.
 --create-db                          Create missing databases for all backup definitions.
 --alternate-archive-dir <path>       Use this directory instead of BACKUP_DIR in the config file.
 --add-dir <path>                     Add all archive catalogs in this directory to databases.
--d, --backup-def <name>              Restrict to work only on this backup definition.
---add-specific-archive <archive>     Add this archive to the catalog database.
---remove-specific-archive <archive>  Remove this archive from the catalog database.
+-d, --backup-def <name>              Restrict operations to this backup definition.
+--add-specific-archive <archive>     Add a specific archive to the catalog database.
+--remove-specific-archive <archive>  Remove a specific archive from the catalog database.
 -l, --list-catalogs                  List catalogs in databases for all backup definitions.
---list-catalog-contents <num>        List contents of a catalog by catalog number.
---list-archive-contents <archive>    List contents of an archive’s catalog, given the archive name.
+--list-archive-contents <archive>    List the contents of an archive’s catalog by archive name.
 --find-file <file>                   Search catalogs for a specific file.
 --verbose                            Enable verbose output.
---log-level <level>                  `debug` or `trace`, default is `info`", default="info".
+--log-level <level>                  Set log level (`debug` or `trace`, default is `info`).
 ```
 
-### cleanup options
+### Cleanup options
 
-This script cleans up old backups and par2 files. Supported options:
+This script removes old backups and par2 files according to `[AGE]` settings in config file.
 
-``` code
+Catalogs in catalog databases are also removed.
+
+Supported options:
+
+```bash
 -d, --backup-definition                           Backup definition to cleanup.
 -c, --config-file                                 Path to 'dar-backup.conf'
 -v, --version                                     Show version & license information.
@@ -1068,11 +1240,11 @@ This script cleans up old backups and par2 files. Supported options:
 --test-mode                                       This is used when running pytest test cases
 ```
 
-### clean-log options
+### Clean-log options
 
 This script removes excessive logging output from `dar` logs, improving readability and efficiency. Available options:
 
-``` code
+```bash
 -f, --file <path>          Specify the log file(s) to be cleaned.
 -c, --config-file <path>   Path to dar-backup.conf.
 --dry-run                  Show which lines would be removed without modifying the file.
@@ -1080,9 +1252,33 @@ This script removes excessive logging output from `dar` logs, improving readabil
 -h, --help                 Displays usage info
 ```
 
-### installer options
+### Dar-backup-systemd options
+
+Generates and optionally install systemd user service units and timers.
+
+```bash
+-h, --help           Show this help message and exit
+--venv VENV          Path to the Python venv with dar-backup
+--dar-path DAR_PATH  Optional path to dar binary's directory
+--install            Install the units to ~/.config/systemd/user
+```
+
+### Installer options
+
+Sets up `dar-backup` according to provided config file.
 
-Sets up `dar-backup`for a user.
+The installer creates the necessary backup catalog databases if `--create-db` is given.
+
+```bash
+--config             Sets up `dar-backup`.
+--create-db          Create backup catalog databases.
+-v, --version        Display version and licensing information.
+-h, --help           Displays usage info
+```
+
+### Demo options
+
+Sets up `dar-backup` in a demo configuration.
 
 It is non-destructive and stops if directories are already in place.
 
@@ -1099,19 +1295,8 @@ Sets up demo config files:
 - ~/.config/dar-backup/dar-backup.conf
 - ~/.config/dar-backup/backup.d/default
 
-``` code
+```bash
 -i, --install              Sets up `dar-backup`.
 -v, --version              Display version and licensing information.
 -h, --help                 Displays usage info
 ```
-
-### dar-backup-systemd
-
-Generates and optionally install systemd user service units and timers
-
-``` code
--h, --help           Show this help message and exit
---venv VENV          Path to the Python venv with dar-backup
---dar-path DAR_PATH  Optional path to dar binary's directory
---install            Install the units to ~/.config/systemd/user
-```