Toda

Toda (תודה) gives you the power to safely deploy files using symlinks on any operating system with Python installed.

Toda requires only core Python, supporting versions 3.10+. Toda has multi-platform support for POSIX-compliant systems, Linux (Debian, Ubuntu, etc), Windows, macOS and BSDs in that order of priority.

Catch22: Toda requires admin rights on Windows. See #8

toda

usage: toda [-h] [-n] [-m MANIFEST] [-f] [-v] [-d DIR] [--no-preflight]
            [--format {text,json}] [--color {auto,always,never}] [--only-changed]
            [{install,purge,inspect,trace,reconcile}] [section [section ...]]

creates symlinks described by a manifest

positional arguments:
  {install,purge,inspect,trace,reconcile}
  section               manifest target

optional arguments:
  -h, --help            show this help message and exit
  -n, --dry-run         nop out all syscalls, verbose
  -m MANIFEST, --manifest MANIFEST
                        path to custom manifest file
  -f, --force           allow clobbering files in target paths
  -v, --verbose
  -d DIR, --dir DIR     override HOME and USERPROFILE (tilde expansion)
  --no-preflight        skip the preflight sanity checks
  --format {text,json}  output format for trace/reconcile actions
  --color {auto,always,never}
                        color mode for text output
  --only-changed        for reconcile text output, hide entries with status=ok

MANIFEST file syntax

• ~/bin/destination_link: ./section/source_file

  • destination-to-source mapping, with the two arguments delimited by a colon

• $ bin

  • defines the bin section

• /bin/sh: @delete deletes /bin/sh

• @include: bin default

  • includes bin and default
  • includes are resolved recursively in deterministic order and each included section is processed once

Provenance (trace)

trace shows where each resolved link came from in the manifest:

toda trace default

Example text output:

/Users/me/.config/git/config <- /repo/dotfiles/gitconfig [section=base line=12 chain=default -> base]

Use JSON for tooling:

toda trace --format json default

Reconciliation (reconcile)

reconcile compares manifest expectations against the filesystem and prints a colored diff-style report. It also returns non-zero for drift in CI usage.

Statuses:

• ok (green): destination exists as a symlink and points to expected source.
• missing (red): destination does not exist.
• wrong_target (red): destination is a symlink but points somewhere else.
• overwritten_file (yellow): destination exists as a regular file.
• overwritten_dir (yellow): destination exists as a directory.
• manifest_conflict (magenta): multiple manifest declarations resolve to the same destination with different sources.

Examples:

toda reconcile --only-changed default
toda reconcile --format json default
toda reconcile --color never default

reconcile exit codes:

• 0: all links are ok
• 2: drift/conflicts detected
• 1: operational failure

CI Example

toda install --manifest ./MANIFEST --no-preflight default
toda reconcile --manifest ./MANIFEST --format json --color never default

Why did you roll your own dotfiles management script?

See the wiki