Getting Started

Installation

From crates.io (recommended)

cargo install dotling

Prebuilt binaries

Download a prebuilt binary from the latest GitHub release:

# 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/

Homebrew (macOS & Linux)

brew tap auricvex/auricvex
brew install dotling

Nix

nix run github:auricvex/dotling

Quick Start

1. Initialize a dotfiles repo

# Create a new repo
dotling init ~/dotfiles

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

This creates the repo directory, initializes git, and writes a dotling.toml config file.

2. Track your config files

dotling add ~/.zshrc
dotling add ~/.config/nvim

dotling moves each file into the repo (organized by category) and deploys a symlink back to the original location. See Path Mapping for how files are organized.

3. Sync everything

dotling sync

This pushes repo files to their actual locations (creating or fixing symlinks) and pulls any copy-mode entries that were modified locally.

4. Commit and push

Since dotling doesn’t wrap git, use native commands:

cd ~/dotfiles
git add .
git commit -m "initial setup"
git push

5. Set up a new machine

# Clone your dotfiles repo
dotling init git@github.com:you/dotfiles.git

# Deploy everything
dotling sync

# If you have encrypted entries, import your vault first
dotling vault import my-vault.bundle
dotling sync

Next steps

• Configuration — learn about dotling.toml and entry options
• Templates — add machine-specific values to dotfiles
• Encryption — encrypt sensitive files with the vault
• CLI Reference — explore all commands and flags