Sync

dotling sync is the core command that keeps your repo and actual filesystem in sync. It handles symlinks, copies, encrypted entries, and templates — all in one pass.

Sync direction

dotling sync decides the direction per entry:

When both sides differ and timestamps are equal, dotling defaults to repo wins (push). Pass --prefer-actual to flip this.

Sync process

For each entry, dotling:

1. Checks if the entry’s OS matches the current platform (skips if not)
2. Determines the entry state: Deployed, Modified, Missing, Broken, or Conflict
3. Uses fingerprint comparison (for copy/encrypted) or mtime to decide direction
4. If both sides changed, prompts for conflict resolution (unless --force or --no-interactive)
5. Executes the sync action (push or pull)
6. Records fingerprints for future comparison
7. Runs entry-level hooks (before/after)

Global hooks (before/after) run at the very beginning and end of the sync session.

Conflict resolution

When sync detects a conflict between the repository and your local target, you can choose:

Three-way merge

The merge option performs a line-level three-way merge using the last-in-sync snapshot as the base, combining modifications from both the repo (ours) and local target (theirs). Non-overlapping changes are cleanly auto-merged, while overlapping conflicts are highlighted with standard git conflict markers:

<<<<<<< repo
repo version content
=======
actual local content
>>>>>>> actual

The merge outcome is written back to both the local disk and the repository.

Conflict types

• First seen — a file exists at the target path but was never tracked by dotling
• Both modified — both the repo and local file changed since the last sync
• Timestamp tie — files differ but modification times are identical

Snapshots

Snapshots used as the merge base are stored in ~/.dotling/snapshots/<source> and are updated after each successful sync of a copy-mode plain file.

Fingerprints

dotling uses Blake2s-256 content hashes stored in ~/.dotling/fingerprints.toml for change detection. This avoids decrypting encrypted files just to check if they’ve changed.

• After each successful sync, dotling records the content hashes of the source, target, and (if encrypted) the ciphertext
• On subsequent checks, dotling compares current hashes against stored fingerprints
• Benefit: dotling status and dotling sync --dry-run work instantly without entering your vault password

Lifecycle Hooks

Global hooks

Global hooks run at the very beginning and very end of the dotling sync session:

Entry-level hooks

Each entry can define its own hooks:

Execution context

Hooks are executed in the repository root directory. The following environment variables are set:

Hook trust system

To protect against malicious code in imported dotfile repositories, dotling prompts for verification before running a hook for the first time:

  ⚡ Untrusted hook detected (type: entry_before):
    echo "updating shell configuration"
    ? Do you want to run this hook? [y]es (once) / [n]o (skip) / [a]lways (trust) / [s]kip all >

Selecting always stores the Blake2s-256 hash of the command string in ~/.dotling/state/trusted_hooks.

• Pass --allow-hooks (or set DOTLING_ALLOW_HOOKS=1) to auto-execute all hooks
• Pass --no-hooks (or set DOTLING_NO_HOOKS=1) to disable all hooks

Hook retry

If a hook exits with a non-zero status, dotling retries up to 3 times (1 initial + 2 retries) before aborting.

Flags