Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Configuration File Reference

Everything DotR manages is described in a single config.toml at the repository root, created by dotr init.

Editor support (schema validation)

dotr init writes a taplo #:schema directive as the first line of the generated config.toml:

#:schema https://raw.githubusercontent.com/uroybd/DotR/main/schema/config.schema.json

This associates the file with a JSON Schema describing every field on this page — giving you inline validation, autocomplete, and hover documentation as you edit, in any editor that uses taplo as its TOML language server:

  • VS Code — install the Even Better TOML extension; it picks up the directive automatically.
  • Neovim — via nvim-lspconfig’s built-in taplo preset: require('lspconfig').taplo.setup {}.
  • Vim, Emacs, Helix, Sublime — any setup that runs taplo as the TOML language server (via vim-lsp/coc.nvim, lsp-mode, etc.) picks it up the same way, since the directive is parsed by taplo itself, not by a particular editor plugin.

This isn’t published on SchemaStore — config.toml is too generic a filename for filename-based catalog matching (Hugo’s own config.toml is SchemaStore’s canonical example of a pattern they reject for exactly this reason). The inline directive avoids that ambiguity entirely, since it points at a specific schema explicitly rather than relying on the filename.

If you have a config.toml from before this was added, add the line above to the top of the file yourself, or configure your editor’s schema association for the file manually (e.g. evenBetterToml.schema.associations in VS Code settings).

Top level

banner = true
symlink = false
prompt_backend = "file"
bitwarden_note = "dotr-secrets"

[variables]
# ...

[prompts]
# ...

[packages.<name>]
# ...

[profiles.<name>]
# ...

[platforms.<name>]
# ...
FieldTypeDefaultPurpose
bannerbooltruePrint the DotR ASCII banner on commands. Set false for quiet output.
symlinkboolfalseDeploy every directory package as a symlink, without setting symlink = true on each one individually — see Symlinks.
variablestable{}Config-level variables — see Variables.
promptstable{}Config-level prompts — see Prompts.
prompt_backend"file" | "keychain" | "bitwarden"unset (behaves as "file")Repo-wide default storage backend for every prompt — see Prompts. A profile’s own prompt_backend overrides this.
bitwarden_notestring"dotr-secrets"Name of the Bitwarden secure note used when prompt_backend = "bitwarden" — see Prompts. Can be overridden per-machine via DOTR_BITWARDEN_NOTE — see machine-local override.
packagestable{}Package definitions, keyed by name — see below.
profilestable{ default = {} }Profile definitions, keyed by name — see below. A default profile always exists.
platformstable{}Platform definitions, keyed by name — see below and Platforms. A profile whose platform field names one picks up its variables.

[packages.<name>]

[packages.nvim]
src = "dotfiles/nvim"
dest = "~/.config/nvim/"
dependencies = ["fonts"]
pre_actions = ["mkdir -p ~/.local/share/nvim"]
post_actions = ["nvim --headless +PluginInstall +qall"]
skip = false
symlink = false
unfold_symlink = false
clean = true
ignore = ["*.log"]

[packages.nvim.variables]
THEME = "gruvbox"

[packages.nvim.targets]
work = "~/work-config/nvim/"

[packages.nvim.prompts]
NVIM_TOKEN = "Enter your plugin registry token"
FieldTypeDefaultPurpose
srcstring—Path to the file/directory in the repository. Required.
deststring—Deployment destination. ~ and template variables are expanded. Required.
dependencieslist of stringsnoneOther packages deployed alongside this one — Dependencies.
variablestable{}Package-scoped variables — Variables.
pre_actionslist of strings[]Shell commands run before deploy — Actions.
post_actionslist of strings[]Shell commands run after deploy — Actions.
targetstable (profile/platform → path){}Per-profile (or per-platform) destination override — Packages.
skipboolfalseExcluded from profile-driven (implicit) selection — Packages.
promptstable{}Package-scoped prompts — Prompts.
ignorelist of glob patterns[]Files excluded from deploy/clean — Ignoring Files.
symlinkboolunset (follows the global symlink setting)Deploy as a symlink instead of a copy. An explicit true/false here always overrides the global flag — Symlinks.
unfold_symlinkboolfalseSymlink individual files instead of the whole directory, so untracked content can coexist at dest — implied by a non-empty ignore — Symlinks.
cleanbooltrueRemove stray files at the destination — Clean Mode.

[profiles.<name>]

[profiles.work]
dependencies = ["nvim", "git"]
prompt_backend = "keychain"
platform = "macos"
pre_actions = ["echo 'Deploying the work profile'"]

[profiles.work.variables]
GIT_EMAIL = "work@company.com"

[profiles.work.prompts]
WORK_TOKEN = "Enter your work VPN token"
FieldTypeDefaultPurpose
dependencieslist of strings[]Packages deployed when this profile is active and no --packages is given — Profiles.
variablestable{}Profile-scoped variables — Variables.
promptstable{}Profile-scoped prompts — Prompts.
prompt_backend"file" | "keychain" | "bitwarden"unset (follows the top-level prompt_backend)Overrides the repo-wide default backend while this profile is active — Prompts.
bitwarden_notestringunset (follows the top-level bitwarden_note)Overrides which Bitwarden secure note this profile’s bitwarden-backed prompts use — Prompts. Can itself be overridden per-machine via DOTR_BITWARDEN_NOTE — see machine-local override.
platformstringunsetNames an entry in the top-level platforms table. Shares that platform’s variables, pre_actions/post_actions, and a package’s targets destination with every other profile that sets the same value. A targets entry keyed by the profile’s own name beats one keyed by its platform, and the profile’s own variables beat the platform’s. — Platforms, Packages.
pre_actionslist of strings[]Shell commands run once before a dotr deploy under this profile, wrapping the per-package actions — Actions.
post_actionslist of strings[]Shell commands run once after such a deploy — Actions.

[platforms.<name>]

[platforms.macos]
variables = { CLIPBOARD = "pbcopy" }
pre_actions = ["softwareupdate --install-rosetta --agree-to-license || true"]

[platforms.linux]
variables = { CLIPBOARD = "xclip -selection clipboard" }

Keyed by platform name — a free-form string (macos, linux, wsl, …); DotR matches it against profiles’ platform fields and never inspects the running OS. A profile whose platform names a platform here inherits its variables and actions; several profiles can name the same platform and all inherit them. Naming a platform that isn’t declared here is allowed and simply yields nothing.

FieldTypeDefaultPurpose
variablestable{}Variables shared by every profile naming this platform. Override config-level and environment variables; overridden by package, profile, and user variables — Variables, Platforms.
pre_actionslist of strings[]Shell commands run once before a dotr deploy for any profile on this platform — outermost, wrapping the profile’s own actions — Actions.
post_actionslist of strings[]Shell commands run once after such a deploy — Actions.

Other files DotR creates

FileTracked in git?Purpose
config.tomlYesThe configuration described above.
dotfiles/YesPackage sources — the actual file/directory content for each package.
.gitignoreYesWritten by dotr init; excludes .uservariables.toml and deployed.
.uservariables.tomlNoAnswers to prompts — secrets live here.
deployed/NoStaging directory for symlinked packages.