Dotfiles

dotkit link mirrors a folder into a destination directory as symlinks. Point it at a folder of dotfiles and they land in your home directory.

Setup

Put your dotfiles in a folder:

• Directorydotkit/

  • mac.dotkit
  • Directorydotfiles/

    • .zshrc
    • .gitignore_global
    • Directory.config/

      • Directorynvim/

        • init.lua

Then link it from your dotkit file:

dotkit link dotfiles

Every file is symlinked to the corresponding path under the destination:

.zshrc                → ~/.zshrc
.gitignore_global     → ~/.gitignore_global
.config/nvim/init.lua → ~/.config/nvim/init.lua

Parent directories are created automatically.

Note

The folder has no type. Nothing inside it marks it as dotfiles; the dotkit link line in your dotkit file is what makes it one. Swap that line for stow dotfiles and the folder is unchanged.

Destination

DEST defaults to ~, which is where dotfiles go in almost every case. Pass it explicitly for anything else:

dotkit link dotfiles
dotkit link dotfiles ~
dotkit link etc /etc
dotkit link shared ../other-machine

It may be absolute, ~/path, or relative to the source folder.

Behaviour

For each file, dotkit checks what is already at the destination:

Destination state	Action
Missing	Symlink created
Already correct symlink	Reported ok, skipped
Symlink to elsewhere	Backed up with timestamp, replaced
Real file	Backed up with timestamp, replaced

Backups use the pattern filename.bak.YYYYMMDDHHMMSS. If a real file is backed up, dotkit also shows a diff so you can review what changed.

Running it twice is safe. The second run reports everything ok and changes nothing.

Previewing

dotkit link --dry-run dotfiles

Prints what would be linked and what would be backed up, without touching anything.

Running manually

Re-apply symlinks at any time:

dotkit link dotfiles
dotkit link ~/dotkit/dotfiles ~

Excluded files

*.env and *.dotkit files are never symlinked. They configure the kit rather than belonging to your home directory.

Several destinations

One folder per destination, each with its own line:

• Directorydotkit/

  • mac.dotkit
  • Directorydotfiles/

    • Directorybase/

      • …
    • Directorypost/

      • …

dotkit link dotfiles/base
---
map dotkit run {{item}}

packages
---
dotkit link dotfiles/post

Here base lands before packages are installed and post lands after, which matters for config files that a tool overwrites on first launch.

If the split gets complicated, give the folder its own dotkit file and let it describe itself:

dotfiles/.dotkit

dotkit link base ~
dotkit link post ~

Then the parent only needs dotkit run dotfiles.

Nested dotfiles

The folder structure mirrors exactly. A file at dotfiles/.config/nvim/init.lua symlinks to ~/.config/nvim/init.lua, and any missing parent directories are created.