dotling 0.2.0

dotling 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, multi-OS support — so you can set up a new machine in seconds.

Features

• Symlink & copy deployment — choose per file, switch anytime
• 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 Encryption — natively encrypt sensitive files (API keys, .env) using age
• Git-integrated — init, commit, push, pull, and sync in one workflow
• 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 link ~/.zshrc
dotling link ~/.config/nvim

# Push to remote
dotling push "initial setup"

# On another machine, clone and deploy
dotling init git@github.com:you/dotfiles.git

Commands

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.

Copies (--copy): the deployed file is a standalone copy — use dotling pull-back to sync changes back.

Path Mapping

Files are organized into categories automatically:

Configuration Format

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

[[links]]
src = "shell/zshrc"
dest = "~/.zshrc"

[[links]]
src = "config/nvim/init.lua"
dest = "~/.config/nvim/init.lua"
method = "copy"

[[links]]
src = "shell/bashrc"
dest = "~/.bashrc"
os = "linux"

Multi-OS Support

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

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

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

Encryption

dotling includes built-in, secure encryption using age. This lets you safely commit API keys, .env files, or ssh configs to your public dotfiles repo.

1. Generate a keypair:

   dotling keygen --save
   

   This generates a new x25519 keypair, saving your secret key in ~/.dotling/identities/default.txt, and printing your public key.

2. Add the public key to .dotling.toml:

   [encryption]
   recipients = [
       "age1yur9...",
   ]
   

3. Link a file with encryption:

   dotling link ~/.ssh/config --encrypt
   

   dotling will read your local file, encrypt it with your configured public key, store the ciphertext in your git repo, and deploy the decrypted file locally.

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
cargo build

# Run tests
cargo test

# Lint
cargo clippy --all-targets -- -D warnings
cargo fmt --check

License

Licensed under either of:

• MIT License
• Apache License, Version 2.0

at your option.