Introduction

DotR is a dotfiles manager that is as dear as a daughter.

It keeps a repository of your configuration files (“dotfiles”) separate from where they’re actually used on disk, and manages copying — or symlinking — them into place. The repository is the source of truth; your ~/.bashrc, ~/.config/nvim/, and friends are deployments of it.

Why DotR?

• Plain files, not magic. Your dotfiles repository is just files and directories under dotfiles/, described by a single config.toml.
• Copy or symlink, your choice. Deploy as copies for a snapshot-based workflow, or as symlinks for live-editing.
• Environment-aware. Profiles let the same repository describe different machines — work, home, server — with different packages, variables, and destinations.
• Templated when you need it. Config files can embed Tera template syntax, compiled at deploy time with live variables, so the same template can render differently per machine or profile.
• Hooks for the messy parts. Pre/post actions run shell commands around deployment — installing dependencies, reloading a service, fixing permissions.
• Safe by default. Dry-run mode previews every operation, diff shows exactly what would change, and deploys only touch files that actually changed.

How it fits together

1. You import an existing file or directory into the repository: dotr import ~/.bashrc. DotR copies it into dotfiles/ and registers it as a package in config.toml.
2. On a new machine, you deploy: dotr deploy. DotR copies (or symlinks) every package from the repository to its destination.
3. After editing a deployed file, you update: dotr update. DotR copies the changed file back into the repository, so dotfiles/ always reflects what’s actually deployed.

Everything else in this book — profiles, variables, templating, actions, prompts, symlinks, clean mode, ignoring files, dependencies — builds on that loop.

Where to go next

• New to DotR? Start with Installation and Quick Start.
• Looking for a specific flag or config field? Jump straight to the CLI Reference or Configuration File Reference.

Installation

Homebrew (macOS and Linux)

Supports both Apple Silicon and Intel Macs.

brew tap uroybd/tap
brew install dotr

Cargo

cargo install dotr-dear

This installs a binary named dotr (the crate is published as dotr-dear since dotr was already taken on crates.io).

From source

cargo install --git https://github.com/uroybd/DotR

Pre-built binaries

Download the latest release for your platform from the releases page:

Extract and move the binary onto your PATH:

tar xzf dotr-*.tar.gz
sudo mv dotr /usr/local/bin/

Verifying the install

dotr --version
dotr --help

Quick Start

1. Initialize a repository

dotr init

This creates, in the current directory:

• config.toml — the repository’s configuration (packages, profiles, variables, prompts)
• dotfiles/ — where imported files actually live
• .gitignore — pre-populated to exclude .uservariables.toml (your local secrets) and deployed (the symlink staging directory, see Symlinks)

Run this inside a git repository you intend to push somewhere, so the dotfiles themselves are version-controlled.

2. Import your existing dotfiles

dotr import ~/.bashrc
dotr import ~/.config/nvim/

# Import as a symlink instead of a copy (live-editing workflow)
dotr import ~/.config/nvim/ --symlink

# Import into a specific profile
dotr import ~/.ssh/config --profile work

Each import copies the file or directory into dotfiles/, and registers a package for it in config.toml with a source and destination — see Packages.

3. Deploy dotfiles on a (new) machine

# Deploy every package
dotr deploy

# Deploy only packages in the "work" profile
dotr deploy --profile work

# Deploy specific packages by name
dotr deploy --packages nvim,tmux

# Preview what would happen, without touching disk
dotr deploy --dry-run

4. Check what would change before deploying

dotr diff
dotr diff --packages nvim,bashrc
dotr diff --profile work

diff shows a colored, line-by-line diff between what’s in the repository and what’s currently deployed.

5. Pull local edits back into the repository

dotr update
dotr update --profile work
dotr update --dry-run

If you edited a deployed file directly (e.g. tweaked ~/.bashrc by hand), update copies those changes back into dotfiles/ so the repository stays the source of truth.

6. Manage packages and profiles

# Packages
dotr packages list
dotr packages list --verbose
dotr packages remove nvim
dotr packages remove nvim --remove-orphans

# Profiles
dotr profiles list
dotr profiles list --verbose
dotr profiles add laptop
dotr profiles remove work
dotr profiles remove work --remove-orphans

Next steps

• Profiles for per-machine configuration
• Variables and Templating for config files that adapt to their environment
• Actions for shell hooks around deployment
• The full CLI Reference and Configuration File Reference

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/"

• src is relative to the repository root (the directory containing config.toml).
• dest is 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

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.

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.

Profiles

A profile describes an environment — work, home, a particular server — as a set of packages, variables, and prompts. The same repository can deploy differently depending on which profile is active.

Every repository has a default profile, created automatically by dotr init.

[profiles.work]
dependencies = ["nvim", "git"]

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

[profiles.home]
dependencies = ["nvim", "gaming"]

[profiles.home.variables]
GIT_EMAIL = "personal@email.com"

Selecting a profile

Most commands accept -P/--profile:

dotr deploy --profile work
dotr import ~/.ssh/config --profile work
dotr update --profile work
dotr diff --profile work

If no --profile is given, DotR resolves the active profile in this order:

1. A DOTR_PROFILE variable (from the environment or .uservariables.toml), if set.
2. Otherwise, default.

Referencing a profile that doesn’t exist is an error (except default, which is created on the fly if missing).

Fields

How a profile decides which packages deploy

When you run dotr deploy (or update/diff) without --packages, DotR deploys every package listed in the active profile’s dependencies that doesn’t have skip = true (see Packages).

When you pass --packages explicitly, the profile’s dependencies list is irrelevant to selection — only the named packages (and their own dependencies) are used — but the profile still supplies variables, prompts, and any targets override.

Managing profiles

dotr profiles list
dotr profiles list --verbose
dotr profiles add laptop
dotr profiles add laptop --set-as-current
dotr profiles remove work
dotr profiles remove work --remove-orphans

--set-as-current writes DOTR_PROFILE = "laptop" into .uservariables.toml, so laptop becomes the implicit profile on this machine without needing --profile laptop on every command.

profiles remove deletes the profile from config.toml. --remove-orphans additionally removes any packages that were only referenced by that profile’s dependencies and no others.

Removing the default profile is not allowed.

Variables

Variables are the values available to templates and actions — things like {{ EDITOR }} or {{ git.email }}.

Sources

Variables come from five places:

• Config-level — [variables] in config.toml, available everywhere.
• Environment variables — every variable in your shell environment.
• Package-level — [packages.<name>.variables], scoped to that package.
• Profile-level — [profiles.<name>.variables], active only when that profile is selected.
• User variables — answers to prompts, saved to the gitignored .uservariables.toml so secrets never end up in the repository.

[variables]
EDITOR = "nvim"

[variables.git]
name = "Your Name"
email = "you@example.com"

Used in a template as {{ EDITOR }} and {{ git.email }}. Nested tables and arrays are supported.

Priority

When the same key is defined in more than one place, the more specific source wins:

user variables  >  profile variables  >  package variables  >  environment variables  >  config variables

In other words: a package’s own [packages.<name>.variables] can override [variables] in config.toml or a same-named environment variable; the active profile’s [profiles.<name>.variables] can override the package; and anything answered via a prompt (stored in .uservariables.toml) wins over all of it.

Environment variables sit above config-level variables but below package/profile/user variables — if your shell exports a variable with the same name as a [variables] entry in config.toml, the environment wins there, but a package or profile can still override it.

Viewing resolved variables

dotr print-vars
dotr print-vars --profile work

Shows every variable currently resolved for that profile, useful for debugging why a template rendered the way it did.

.uservariables.toml

Created automatically the first time a prompt is answered, and listed in .gitignore by dotr init. It’s the right place for secrets — API tokens, personal emails, machine-specific paths — that shouldn’t be committed to the dotfiles repository.

Templating

DotR compiles files through the Tera template engine at deploy time, using the resolved variables for that package and profile.

# a config file with Tera templates
[user]
name = "{{ git.name }}"
email = "{{ git.email }}"

{% if HOME %}
[paths]
data = "{{ HOME }}/Data"
{% endif %}

• {{ variable }} — variable substitution
• {% if condition %}...{% endif %} — conditionals
• {# comment #} — comments, stripped from output

Any construct Tera supports (loops, filters, macros) works, since DotR hands the file straight to Tera’s renderer.

Detection is automatic

A file is treated as templated if it contains any of {{, }}, {%, %}, {#, or #} (including Tera’s whitespace-trimming variants like {%- and -%}) anywhere in its content — no extension, header, or config flag required. Regular and templated files can coexist in the same package or directory.

Destination paths are templated too

Not just file contents — the dest path (and any per-profile targets override) is also run through Tera before use, so a destination can depend on variables:

[packages.ssh_config]
src = "dotfiles/ssh_config"
dest = "{{ HOME }}/.ssh/config"

Templated files are never backed up

dotr update normally copies a deployed file’s changes back into the repository. For a templated file, that would overwrite the template source with rendered output — so update (and the underlying backup step) skips templated packages entirely, leaving the template as the single source of truth. You’ll see a message like:

Skipping backup for templated 'nvim_config'

If you need to change a templated file, edit the template in dotfiles/ directly and redeploy.

Actions

Actions are shell commands run around a package’s deployment — useful for installing dependencies, reloading a service, fixing permissions, or anything else that isn’t just “put this file here.”

[packages.nvim]
src = "dotfiles/nvim"
dest = "~/.config/nvim/"

pre_actions = ["mkdir -p ~/.local/share/nvim"]
post_actions = ["nvim --headless +PluginInstall +qall"]

• pre_actions run before the package’s files are copied/symlinked.
• post_actions run after.
• Both are lists — multiple actions run in order, each waiting for the previous one to finish.

Execution details

• Each action string is compiled through Tera first, so {{ variable }} interpolation works exactly like in file templates.
• Actions run via $SHELL -c "<action>", falling back to /bin/sh if $SHELL isn’t set.
• The working directory is the repository root (the directory containing config.toml), not the package’s src/dest.
• If an action exits non-zero, the whole deploy/update operation fails immediately — later actions and the rest of that package’s deployment do not run, unless --ignore-errors was passed (which moves on to the next package, not the next action within a failed one).

[packages.aws]
src = "dotfiles/aws"
dest = "~/.aws/"
variables = { PROFILE = "default" }
pre_actions = ["echo 'Using AWS profile: {{ PROFILE }}'"]

Skipping actions

dotr deploy (and dotr packages deploy) accept flags to skip actions for that invocation without editing config.toml:

# Skip both pre- and post-actions
dotr deploy --skip-actions

# Skip only pre-actions
dotr deploy --skip-pre-actions

# Skip only post-actions
dotr deploy --skip-post-actions

This is useful when actions are expensive (e.g. reinstalling plugins) and you only want to sync files, or when debugging a failing action by first confirming the file deployment itself is fine.

Dry run

Under --dry-run, actions are not executed — each one is printed as (Dry Run) Would execute action: <command> instead. See Dry Run Mode.

Prompts

Prompts ask for a value interactively the first time it’s needed, then remember the answer — so secrets and machine-specific values never have to be hard-coded in config.toml.

# Config-level (global)
[prompts]
GIT_EMAIL = "Enter your git email"

# Package-level
[packages.aws]
[packages.aws.prompts]
AWS_ACCESS_KEY = "Enter AWS access key"

# Profile-level
[profiles.work]
[profiles.work.prompts]
WORK_EMAIL = "Enter work email"

Each entry maps a variable name to the message shown when prompting for it.

When prompts run

Prompts are collected — from config-level, the active profile, and every package being operated on — and checked before deploy, update, and diff. Any key not already present in .uservariables.toml triggers an interactive prompt; the rest are skipped silently.

Where answers go

Answers are saved to .uservariables.toml in the repository root, which dotr init adds to .gitignore. Once a key has an answer there, it’s never prompted for again — delete the line (or the whole file) to be asked again.

Values from .uservariables.toml become user variables — the highest-priority source in variable resolution, overriding profile, package, environment, and config variables. See Variables.

Symlinks

By default, DotR copies files from the repository to their destination. For configs you edit frequently and want to reflect immediately — no update step — a package can instead be deployed as a symlink.

[packages.nvim]
src = "dotfiles/nvim"
dest = "~/.config/nvim/"
symlink = true

Importing with a symlink

dotr import ~/.config/nvim/ --symlink

--symlink sets symlink = true on the new package and immediately deploys it (a plain dotr import only copies into the repository and registers the package, without deploying).

How it works

1. import copies the source into dotfiles/<name>/ in the repository, as normal.
2. deploy copies those files again into deployed/<name>/ (a staging directory at the repository root — dotr init adds deployed to .gitignore, since it’s derived, not source, content).
3. deploy then creates a symlink at the package’s dest pointing at deployed/<name>/.

dotfiles/nvim/   (repository — source of truth, git-tracked)
      │  deploy copies files
      ▼
deployed/nvim/   (staging — gitignored)
      ▲  symlink
      │
~/.config/nvim/  (dest — symlinked to deployed/nvim/)

Editing files at ~/.config/nvim/ edits deployed/nvim/ directly (it’s a symlink), so changes take effect immediately. Run dotr update to copy those changes back into dotfiles/nvim/ when you’re ready to commit them.

Redeploying

If dest already exists (as a symlink, a directory, or a plain file) when deploy runs, it’s removed first and replaced with the fresh symlink — so re-running dotr deploy after changing symlink = true/false correctly switches a package between copy-mode and symlink-mode.

Clean Mode

By default, deploy and update remove files found in the destination that don’t exist in the repository — keeping deployed configs in sync with dotfiles/, rather than merely additive.

# Deploy with cleaning (default)
dotr deploy

# Deploy without cleaning extra files
dotr deploy --clean=false

# Update with cleaning (default)
dotr update

# Update without cleaning
dotr update --clean=false

What’s protected from cleaning

• Backup files (.dotrbak extension, see below) are never removed.
• Files matching an ignore pattern for that package are left alone.
• Anything that is part of the current deployment, obviously.

Per-package configuration

[packages.nvim]
src = "dotfiles/nvim"
dest = "~/.config/nvim/"
clean = false  # disable cleaning for this package specifically

clean defaults to true. The --clean CLI flag, when passed, overrides whatever the package specifies for that one invocation; when omitted, the package’s own setting is used.

Backups

When a file at the destination would be overwritten, DotR writes a per-file backup (<file>.dotrbak) alongside it before copying — a lightweight safety net, distinct from dotr update’s job of syncing intentional edits back into the repository. Backup files are always excluded from cleaning, so they won’t be swept away by the same operation that created them.

Ignoring Files

A package can exclude specific files within its src directory from both deployment and cleaning, using glob patterns matched against each file’s path relative to the package root.

[packages.nvim]
src = "dotfiles/nvim"
dest = "~/.config/nvim/"
ignore = ["*.log", "cache/*", ".DS_Store"]

• Patterns are matched with glob-match semantics (*, **, ?, [...], etc.) against the path relative to the package’s src — not against absolute paths.
• A matched file is skipped entirely during deploy/update: it isn’t copied, and if it already exists at the destination it isn’t removed by clean mode either — ignore means “hands off,” not “delete this.”
• ignore only applies to directory packages (it has no effect on a package whose src is a single file).

This is separate from your top-level .gitignore (which controls what git tracks in the repository) — ignore controls what DotR itself touches at deploy time.

Dependencies

A package can declare other packages it depends on. Whenever it’s selected for an operation, its dependencies are pulled in automatically.

[packages.nvim]
src = "dotfiles/nvim"
dest = "~/.config/nvim/"
dependencies = ["fonts"]

[packages.fonts]
src = "dotfiles/fonts"
dest = "~/.local/share/fonts/"

Deploying just nvim…

dotr deploy --packages nvim

…also deploys fonts, since nvim depends on it. This applies to deploy, update, and diff — anywhere packages are selected.

Skipping dependency resolution

Pass --ignore-dependencies to select only the named (or profile-driven) packages, without pulling in anything they depend on:

dotr deploy --packages nvim --ignore-dependencies

This is currently available on deploy (dotr deploy and dotr packages deploy).

Removing a package with dependents

dotr packages remove (and top-level dotr remove) refuses to remove a package that another package’s dependencies — or a profile’s dependencies — still references, to avoid leaving a dangling reference in config.toml:

Package 'fonts' cannot be removed because it is depended on by profiles: [] and packages: ["nvim"]. Use --force to override.

Pass --force to remove it anyway. See also --remove-orphans, which does the reverse: clean up dependencies that are no longer referenced by anything after a removal.

Dry Run Mode

--dry-run previews a deploy or update without changing anything on disk:

dotr deploy --dry-run
dotr update --dry-run

# Combine with other flags
dotr deploy --dry-run --profile work --packages nvim,bashrc
dotr deploy --dry-run --clean=false

Under --dry-run:

• No files are written. Deployments print what would be copied or symlinked instead of touching disk.
• No backups are created.
• Pre/post actions are not executed — each is printed as (Dry Run) Would execute action: <command> instead. See Actions.
• Clean mode still previews its removals — it runs by default and reports (Dry Run) Would remove file: <path> for anything it would clean up, without actually deleting it. Pass --clean=false alongside --dry-run if you don’t want to see those either.

Dry run is the safest way to check what a deploy or update will do before committing to it — especially useful after changing dest, targets, or ignore patterns, or before deploying to a machine for the first time. For comparing file contents rather than previewing an operation, see dotr diff in the CLI Reference.

Configuration File Reference

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

Top level

banner = true

[variables]
# ...

[prompts]
# ...

[packages.<name>]
# ...

[profiles.<name>]
# ...

[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
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"

[profiles.<name>]

[profiles.work]
dependencies = ["nvim", "git"]

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

[profiles.work.prompts]
WORK_TOKEN = "Enter your work VPN token"

Other files DotR creates

CLI Reference

dotr [OPTIONS] [COMMAND]

Global options

dotr init

Initialize a dotfiles repository in the working directory: writes config.toml, creates dotfiles/, and writes a .gitignore. Safe to re-run — if config.toml already exists, it’s left untouched.

dotr import <PATH>

Copy a file or directory into the repository and register it as a package.

dotr deploy

Deploy packages from the repository to their destinations.

dotr update

Copy changes from deployed files back into the repository.

Templated packages are skipped by update — see Templating.

dotr diff

Show a colored, line-by-line diff between the repository and what’s currently deployed.

dotr remove [PACKAGES]...

Remove one or more managed packages: deletes their config.toml entry and their files under dotfiles/. Equivalent to dotr packages remove.

dotr print-vars

Print every variable resolved for the given (or default) profile — see Variables.

dotr packages

Groups package-scoped commands under one namespace. Each behaves the same as its top-level equivalent, plus list:

dotr packages list [-v|--verbose]
dotr packages import <IMPORT_PATH> [-s|--symlink] [-n|--name <NAME>] [-p|--profile <NAME>]
dotr packages deploy [same flags as `dotr deploy`]
dotr packages update [same flags as `dotr update`]
dotr packages diff   [same flags as `dotr diff`]
dotr packages remove [same flags as `dotr remove`]

dotr packages itself also accepts -P, --profile <NAME> as context for its subcommands. packages list --verbose additionally prints each package’s src, dest, dependencies, and other fields.

dotr profiles

Manage profiles — see Profiles.

dotr profiles list [-v|--verbose]
dotr profiles add <PROFILE_NAME> [--set-as-current]
dotr profiles remove <PROFILE_NAME> [--dry-run] [--remove-orphans]

• add --set-as-current writes DOTR_PROFILE into .uservariables.toml, making the new profile the implicit default on this machine.
• remove cannot remove the default profile. --remove-orphans also removes packages that were only referenced by the removed profile.