Directory synchronization tool yd

Build and execute rsync commands from TOML configuration files.

(Un)Install

To install, run

uv tool install yd-cli

Then run

yd --install-completion

to install auto-completion in your shell.

In bash, the completion code is stored in ~/.bash_completions/yd.sh and that file is sourced from ~/.bashrc. Remove both and call uv tool uninstall yd-cli to remove this tool. The below mentioned configuration files need to be removed separately.

Create a config

Create a new configuration called photos with:

yd edit --new photos

This command

• creates ~/.config/yd/photos.toml (or under $XDG_CONFIG_HOME/yd if set; relative paths are resolved from your home directory), and
• opens it with the executable selected via EDITOR, or nvim when EDITOR is unset.

Reopen an existing configuration with:

yd edit photos

Configuration format

Example

# Phone backup
src_home = "/home/alice"
target_home = "/mnt/backup"
backup = "deleted/%Y-%m-%d"
exclude = [".venv/", "__pycache__/"]

[[commands]]
src = "Documents"
exclude = ["*.log"]

[[commands]]
src = "Pictures"
target = "pics-%Y-%m-%d"
delete_extra = false

Leading comment lines directly at the top of the file are treated as the configuration description and are shown by yd ls.

Top-level options

mtp_target matters because rsync normally copies to a temporary file and renames it afterward, but that is not possible when syncing via MTP.

Command options

Notes

• src and target must stay within src_home and target_home after path resolution.
• Literal targets are retained when they contain only empty directories. Dated targets serve as snapshots: if a dated target did not exist before synchronization and contains neither files nor symlinks afterward, yd removes its empty directory tree.
• src_home or target_home may be omitted from the configuration, but every missing value must then be supplied when running (via CLI parameters).
• Exactly one of --src-home - and --target-home - may read from standard input in a single run.
• If backup is omitted, yd creates a timestamped backup directory automatically unless --no-backup is specified.
• If a configured source directory exists but is empty, yd reports that no synchronization was performed for that command. E.g., forgetting to mount an external drive does not delete all corresponding copies on hard-drive.
• If a valid date placeholder is included in the target, then the target_home is scanned for matching directories (possibly) created by this rule before today. The 20 most recent matches are included as additional comparison destinations in the synchronization: if a file in src is included in one of those reference directories, then it will not be copied to target.

Run a config

Run a saved configuration by name:

yd run photos

Options

Logging

Set YD_LOGLEVEL to a numeric Python logging level, such as 10 for debug, 20 for info, or 40 for errors. When set, yd appends JSON Lines records to .yd.jsonl in the current working directory. Records contain time, level, logger, and message fields, plus exception type, message, and traceback when applicable.

Logging is effectively disabled by default. Enable it when diagnosing a failed or interrupted run.

List configs

List available configurations with:

yd ls

This shows the configuration name together with the optional leading-comment description.

Why yd?

• Has one character from synchronize and one from directory.
• Easy to type with both QWERTZ and QWERTY keyboards.
• Name was still available on PyPI.