Packages
A package is a single managed unit — one file or one directory — with a
source inside the repository and a destination on disk. Every package lives
under [packages.<name>] in config.toml.
[packages.nvim]
src = "dotfiles/nvim"
dest = "~/.config/nvim/"
srcis relative to the repository root (the directory containingconfig.toml).destis the deployment target.~is expanded to the user’s home directory.
Creating packages
Packages are usually created with dotr import, which copies a file or
directory into dotfiles/ and writes the corresponding [packages.*]
entry:
dotr import ~/.bashrc
dotr import ~/.config/nvim/ --name neovim
The package name defaults to a sanitized version of the path (leading .
stripped, ./- replaced with _, directories prefixed with d_, files
with f_), or you can set it explicitly with --name.
Fields
| Field | Type | Purpose |
|---|---|---|
src | string | Path to the file/directory in the repository |
dest | string | Deployment destination |
dependencies | list of strings | Other packages that must be deployed alongside this one — see Dependencies |
variables | table | Package-scoped variables — see Variables |
pre_actions | list of strings | Shell commands run before deploying — see Actions |
post_actions | list of strings | Shell commands run after deploying — see Actions |
targets | table (profile/platform → path) | Per-profile (or per-platform) destination override, see below |
skip | bool | If true, excluded from profile-driven deploys (see below) |
prompts | table | Package-scoped prompts — see Prompts |
ignore | list of glob patterns | Files to exclude from deployment/cleaning — see Ignoring Files |
symlink | bool | Deploy as a symlink instead of a copy; overrides the global symlink setting either way when set explicitly — see Symlinks |
unfold_symlink | bool | Symlink individual files rather than the whole directory — see Symlinks |
clean | bool (default true) | Remove stray files in the destination — see Clean Mode |
Per-profile destinations (targets)
A package can deploy to a different path depending on the active profile:
[packages.gitconfig]
src = "dotfiles/gitconfig"
dest = "~/.gitconfig"
[packages.gitconfig.targets]
work = "~/.gitconfig-work"
When the work profile is active, gitconfig deploys to
~/.gitconfig-work instead of the default dest. Any profile not listed in
targets falls back to dest.
Sharing a target across profiles by platform
targets can also be keyed by a profile’s
platform value instead of its name, so multiple profiles
that set the same platform share one override without repeating it under
each profile’s own name:
[profiles.home]
platform = "macos"
[profiles.work]
platform = "macos"
[packages.gitconfig.targets]
macos = "~/.gitconfig-mac"
Both home and work deploy gitconfig to ~/.gitconfig-mac. If a
package’s targets has entries for both a profile’s own name and its
platform, the profile-name entry wins — it’s the more specific override.
Skipping a package by default (skip)
[packages.experimental]
src = "dotfiles/experimental"
dest = "~/.config/experimental"
skip = true
A package with skip = true is left out when packages are selected
implicitly (via a profile, i.e. no --packages flag). It’s still deployed
if you name it explicitly: dotr deploy --packages experimental.
Operating on packages directly
The packages subcommand groups import/deploy/update/diff/remove/
list under one namespace — each behaves the same as its top-level
equivalent (dotr import, dotr deploy, … dotr remove):
dotr packages list
dotr packages list --verbose
dotr packages import ~/.tmux.conf
dotr packages deploy --packages nvim
dotr packages update --packages nvim
dotr packages diff --packages nvim
dotr packages remove nvim
dotr packages remove nvim --remove-orphans
remove (equivalently, top-level dotr remove) deletes the package’s entry
from config.toml and its files from dotfiles/. It refuses to remove a
package that other packages or profiles still depend on unless you pass
--force. --remove-orphans additionally removes any of its dependencies
that are no longer referenced elsewhere.