Yet another dotfiles management tool.

• 🔗 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

• Python 3.12+
• git

Install with uv:

uv tool install dotsman

To update to the latest version:

uv tool upgrade dotsman

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.

[DEFAULT]
repo_dir = ~/dots

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

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

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

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.

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

dots remove ~/.bashrc

List all files in the repository and their sync status.

dots list

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.

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

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

• 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

BSD 3-Clause. See LICENSE for details.