From Dotfile Managers

Dotfile managers focus on one job: keeping dotfiles in sync between a repo and your home directory. Dotkit does that too, but it’s also responsible for installing tools, packages, and running any other setup steps. If you’re already using a dotfile manager, you can keep it, wrap it, or replace its symlinking job with dotkit link.

Keeping your current tool

If your dotfile manager is working well, you don’t need to replace it. Just call it from a dotkit shell script:

profiles/personal/dotfiles.sh

cd ~/dotfiles
stow -t ~ .         # or: chezmoi apply, or: rcup, etc.

Dotkit handles execution order and bootstrap. Your existing tool handles symlinking. They don’t conflict. You can use dotkit for packages, tools, and configs while keeping your dotfile manager for dotfiles.

It’s also possible to use any subfolder of a run.env folder, as it will skip execution. Then use a runner to execute your dotfile manager on the subfolder.

If you want to keep your dotfiles colocated in your dotkit profile at the dir level, ignore it’s execution with !dotfiles in order.txt.

Replacing symlinking with dotkit link

If you want dotkit to own the symlinking, just add a link.env file with DEST=~:

Before (separate dotfiles repo with a symlink tool):

~/dotfiles/
  .zshrc
  .gitconfig
  .config/nvim/init.lua

After (with link.env):

~/dotfiles/
  link.env          ← DEST=~
  .zshrc
  .gitconfig
  .config/nvim/init.lua

Then install dotkit CLI and run dotkit link ~/dotfiles to symlink every file to ~/, mirroring the structure. Existing files are backed up before being replaced.

Note

Dotkit’s link behavior is straightforward: it walks the folder recursively and creates a symlink for each file at the corresponding path under DEST. No templates, no encryption, no conditionals, just symlinks.

If you need per-machine conditional files, templating, or encrypted secrets, keep using your current tool for those files and use dotkit link for the rest.

Migrating dotfiles to a dotkit profile

1. Copy your dotfiles into profiles/personal/dotfiles/
2. Add link.env with DEST=~
3. Run dotkit link dotfiles --dry-run (or dotkit apply --dry-run) to preview
4. Run dotkit link dotfiles to apply (existing files are backed up automatically)