dots

Yet another dotfiles management tool.

✨ Features

• 🔗 Dotfiles stored in a central folder and symlinked to their real location
• 🔁 Automatic git versioning on every change
• 💻 Per-machine configuration via hostname-based config sections
• ⚠️ Conflict detection and resolution during sync
• 🔒 Encryption for sensitive files

📋 Requirements

• Python 3.12+
• git

📦 Installation

Install with uv:

uv tool install dotsman

To update to the latest version:

uv tool upgrade dotsman

⚙️ Configuration

The configuration file should be located at ~/.dots.conf.

Settings are organized in sections named after the machine's hostname. The [DEFAULT] section provides fallback values used when no hostname-specific section exists.

Available settings

Example

[DEFAULT]
repo_dir = ~/dots

[work-laptop]
repo_dir = ~/dotfiles
ignored_files = .bashrc, .config/personal/*

[home-desktop]
age_identity = ~/.age/dots.key

🚀 Usage

Global options

dots [--config PATH] [--verbose] [--version] COMMAND

dots add <file> (alias: a)

Add a file to the repository. The file is copied into the repo and replaced with a symlink.

dots add ~/.bashrc
dots add ~/.config/git/config

When --encrypt is used, the file is stored as a .age file in the repo (encrypted at rest), with a decrypted working copy in a gitignored .decrypted/ directory. The symlink points to the decrypted copy so the file remains usable. Requires age_identity to be set in the config.

If the file is already tracked as plaintext, --encrypt encrypts it and removes the tracked plaintext file.

dots remove <file> (aliases: rm, rem, del, delete)

Remove a file from the repository. The symlink is replaced with the original file.

dots remove ~/.bashrc

dots list (aliases: l, ls)

List all files in the repository and their sync status.

dots list

dots sync (alias: s)

Synchronize the repository with the filesystem. Creates missing symlinks and detects conflicts.

dots sync

--force-add and --force-link are mutually exclusive. Without force flags, dots prompts interactively when conflicts are found.

🔒 Encryption

Sensitive dotfiles can be encrypted at rest using age. Encrypted files are safe to push to public repositories.

Setup

1. Generate an age identity:

   age-keygen -o ~/.age/dots.key
   

2. Add the identity path to your config (~/.dots.conf):

   [DEFAULT]
   age_identity = ~/.age/dots.key
   

3. Add files with encryption:

   dots add --encrypt ~/.config/secrets.env
   

How it works

• Encrypted files are stored in the repo with a .age extension (e.g., secrets.env.age)
• Decrypted working copies live in a gitignored .decrypted/ directory inside the repo
• Symlinks point to the decrypted copies, so files are usable as normal
• dots sync detects changes to decrypted files and re-encrypts them automatically
• On a new machine, dots sync decrypts all .age files and creates symlinks
• If the age identity is not configured, encrypted files are skipped with a warning during sync

📜 License

BSD 3-Clause. See LICENSE for details.