Managing Symlinks

Managing Symlinks

dots doesn't hard-code any configuration. Instead, you declare which files should be symlinked in a manifest at ~/.dots/links.toml, and dots creates and repairs them. This lets you keep your actual dotfiles in any repo or directory you like.

Both forms below are lowered to the same symlink engine, so dots health repairs everything you declare.

The manifest: ~/.dots/links.toml

There are two ways to declare links — you can mix both in one file.

Explicit links

One symlink per entry: the real file lives at source, and the symlink is created at target.

[[link]]
source = "~/dotfiles/starship.toml"
target = "~/.config/starship.toml"

[[link]]
source = "~/dotfiles/zsh/.zshrc"
target = "~/.zshrc"

Stow-style folding

Mirror each package subdirectory of dir into target, GNU Stow style. A subdirectory is "folded" into a single symlink when its destination doesn't already exist as a real directory; otherwise dots "unfolds" and recurses, so it never clobbers a real directory holding files it doesn't manage.

[stow]
dir      = "~/dotfiles"                          # your dotfiles repo
target   = "~"                                   # optional, defaults to $HOME
packages = ["nvim", "git"]                       # subdirs of `dir` to link
ignore   = [".DS_Store", "*.bak", "README.md"]   # optional

With the above, ~/dotfiles/nvim/... and ~/dotfiles/git/... are mirrored into ~.

Managing links from the CLI

You usually don't edit the manifest by hand — the dots link subcommands do it for you:

# Adopt an existing file: moves it into <source>, then symlinks it back.
dots link add ~/dotfiles/starship.toml ~/.config/starship.toml

dots link list      # show declared links and their status
dots link apply     # create or repair everything declared
dots link remove ~/.config/starship.toml

dots link add is adoption-aware: if nothing exists yet at source but a real file/dir sits at target, it moves the real file into source first, then creates the symlink — so you can pull an existing config into your dotfiles repo in one step.

Statuses

dots link list and the Health screen report each link as:

Status	Meaning
ok	Symlink exists and points where it should
missing	Nothing exists at the target
broken	Symlink exists but its destination is gone
not a link	A real file/dir sits at the target instead of a symlink
wrong target	Symlink points somewhere other than declared

Backups

When dots needs to replace something at a target path, it never destroys your data: the existing file/dir is moved aside to a timestamped *.bak.<date> backup (with a numeric suffix if needed) before the symlink is created.