dotling 0.4.0

dotling v0.3.1 has been rebuilt from scratch. It moves your config files into a central git repository and replaces them with symlinks (or copies). It handles the tedious parts — path mapping, conflict detection, encryption, and multi-OS support — so you can set up a new machine in seconds.

Features

• Symlink & copy deployment — choose per file, switch anytime
• Bidirectional sync — dotling sync pushes from repo → actual and pulls from actual → repo automatically
• Automatic path mapping — ~/.config/nvim → config/nvim, ~/.zshrc → shell/zshrc
• Multi-OS support — tag entries as linux, macos, or windows; skip irrelevant files automatically
• Secure Password Vault — encrypt sensitive files (API keys, .env) using an Argon2id + ChaCha20-Poly1305 Vault
• Encrypted sync — sync handles encrypted entries in both directions; modified plaintext is re-encrypted back into the repo automatically
• Portable Secrets — export your vault to easily unlock secrets on a new machine
• Native Git integration — dotling manages the symlinks, you manage the repo with native git commands
• Health checks — dotling doctor audits broken links, orphaned entries, and repo issues
• Conflict-safe — refuses to overwrite unmanaged files without explicit confirmation

Installation

From crates.io (recommended)

cargo install dotling

Prebuilt binaries

Download a prebuilt binary from the latest GitHub release for your platform:

# Example: Linux x86_64
curl -fsSL https://github.com/auricvex/dotling/releases/latest/download/dotling-x86_64-linux.tar.gz \
  | tar xz -C ~/.local/bin/

Nix

nix run github:auricvex/dotling
# or add to your flake inputs

Quick Start

# Initialize a new dotfiles repo
dotling init ~/dotfiles

# Or clone an existing one
dotling init git@github.com:you/dotfiles.git

# Track files
dotling add ~/.zshrc
dotling add ~/.config/nvim

# Sync everything (repo → actual and actual → repo)
dotling sync

# Since dotling doesn't wrap git, you can commit and push directly!
cd ~/dotfiles
git add .
git commit -m "initial setup"
git push

Commands

Key Flags

How It Works

dotling moves your config files into a central git repository and replaces them with symlinks (or copies). Each tracked file is recorded in a dotling.toml config at the repo root.

Symlinks (default): the deployed file points to the repo — edits are instantly reflected in your repo. dotling sync ensures the symlink is present and correct.

Copies (--copy): the deployed file is a standalone copy. Useful for apps that don't support symlinks. dotling sync compares modification times and copies in whichever direction is newer.

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.

Path Mapping

Files are organized into categories automatically:

Configuration Format

Tracked entries are stored in dotling.toml at the repo root:

[[entries]]
source = "shell/zshrc"
target = "~/.zshrc"

[[entries]]
source = "config/nvim/init.lua"
target = "~/.config/nvim/init.lua"
method = "copy"

[[entries]]
source = "shell/bashrc"
target = "~/.bashrc"
os = "linux"

Multi-OS Support

Tag entries with --os to restrict them to a specific platform:

dotling add ~/.zshrc --os macos
dotling add ~/.bashrc --os linux

When deploying, dotling automatically skips entries that don't match the current OS. Entries tagged all (the default) deploy everywhere.

Encryption Vault

dotling v0.3.1 includes a built-in portable encryption Vault protected by Argon2id and ChaCha20-Poly1305. This lets you safely commit API keys, .env files, or ssh configs to your public dotfiles repo.

1. Initialize your Vault:

   dotling vault init
   

   You'll be prompted for a password. This creates a secure identity in ~/.dotling/vault/.

2. Add a file with encryption:

   dotling add ~/.ssh/config --encrypt
   

   dotling will read your local file, encrypt it, store the ciphertext (config.enc) in your git repo, and deploy the decrypted file locally with secure permissions.

3. Sync encrypted entries: dotling sync handles encrypted entries in both directions. If you edit the deployed plaintext file, running sync will re-encrypt it back into the repo:

   # Edit your deployed file, then sync it back
   vim ~/.ssh/config
   dotling sync   # detects the file is newer → re-encrypts into ssh/config.enc
   

4. Migrating to a new machine: Export your vault bundle from your old machine:

   dotling vault export my-vault.bundle
   

   Then import it on the new machine and sync:

   dotling vault import my-vault.bundle
   dotling sync
   

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feat/my-feature)
3. Commit your changes (git commit -m 'feat: add my feature')
4. Push to the branch (git push origin feat/my-feature)
5. Open a Pull Request

Development

# Clone and build
git clone https://github.com/auricvex/dotling.git
cd dotling
nix develop --command cargo build

# Run tests
nix develop --command cargo test

# Lint
nix develop --command cargo clippy
nix develop --command cargo fmt --check

License

Licensed under either of:

• MIT License
• Apache License, Version 2.0

at your option.