DotR

A dotfiles manager that is as dear as a daughter.

Documentation

For detailed documentation, guides, and examples, visit the DotR Wiki.

Features

📦 Package Management

Import dotfiles from any location into your repository
Import with symlinks - use --symlink flag to deploy as symlinks instead of copies
Deploy dotfiles to their target locations
Update changes back to your repository
Remove packages - clean up managed packages with dotr packages remove
Support for both files and directories
Profile-based deployment for different environments (work, home, server)
Profile dependencies to automatically deploy required packages
Package targets to override destinations per profile

🎭 Profiles

Environment-specific configurations (work, home, server, laptop, etc.)
Add profiles - create new profiles with dotr profiles add
Remove profiles - delete profiles with dotr profiles remove
List profiles - view all available profiles with dotr profiles list
Profile variables that override package and config variables
Package dependencies per profile for automatic deployment
Target overrides to deploy same package to different locations per profile
Switch profiles with --profile flag on deploy, import, and update commands

🔧 Variables

Environment variables automatically available in all templates
Custom user variables defined in config.toml
Package-level variables for package-specific configurations
Profile variables that override other variables when a profile is active
Nested variable structures with TOML tables and arrays
Print variables command to view all available variables
Variable priority: User variables > Profile variables > Package variables > Config variables > Environment variables
Secret uservariables.toml file to save secrets you don't want to share in VCS

💬 Interactive Prompts

Config-level prompts - Global prompts for values used across all packages
Package-level prompts - Package-specific prompts for sensitive configuration
Profile-level prompts - Environment-specific prompts (work credentials, personal tokens, etc.)
Smart prompting - Only prompts once, saves answers to .uservariables.toml
Skip existing values - Won't prompt for variables already defined
Prompts are displayed during deploy, update, and diff commands

📝 Templating (Tera)

Full Tera template engine support
Use {{ variable }} for variable substitution
Use {% if condition %} for conditional logic
Use {# comment #} for template comments
Automatic template detection - no configuration needed
Templates are compiled during deployment with live variables
Templated files are never backed up (source of truth stays in templates)

⚡ Actions (Pre/Post Hooks)

Pre-deployment actions run before package deployment
Post-deployment actions run after package deployment
Execute shell commands with full variable interpolation
Multiple actions per package, executed in order
Perfect for: installing dependencies, reloading services, setting permissions, etc.

🎯 Smart Workflows

Templated and regular files can coexist in the same repository
Symlink support - deploy as symlinks for live-editing workflows
Granular file deployment - only deploys files when content has changed
Granular backups - creates per-file backups (.dotrbak) instead of directory backups
Diff command to preview changes before deployment
Dry run mode - preview deploy and update operations without making any changes
Remove orphans - clean up packages/profiles and their orphaned dependencies
Selective package deployment and updates
Profile-based deployments for different machines/environments
Directory structure preservation

🧹 Clean Mode

Clean by default - automatically removes files in destination that don't exist in source
Keeps your deployed configurations synchronized with your repository
Package-level control - disable cleaning per package with clean = false in config
CLI override - use --clean=false to skip cleaning for a single operation
Perfect for maintaining tidy config directories without manual cleanup
Respects ignore patterns - won't remove files matching your ignore rules

Quick Start

Initialize a dotfiles repository:

dotr init

Import your existing dotfiles:

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

# Import with symlink (deploy as symlink instead of copy)
dotr import ~/.config/nvim/ --symlink

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

Deploy dotfiles to a new machine:

# Deploy all packages
dotr deploy

# Deploy with a specific profile
dotr deploy --profile work

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

# Dry run to preview what would be deployed without making changes
dotr deploy --dry-run

Check differences before deploying:

# See what would change if you deployed
dotr diff

# Diff specific packages
dotr diff --packages nvim,bashrc

# Diff with a profile
dotr diff --profile work

Update after making changes:

dotr update

# Update with a profile
dotr update --profile work

# Dry run to preview what would be updated without making changes
dotr update --dry-run

Manage packages and profiles:

# List all packages
dotr packages list

# List packages with verbose details
dotr packages list --verbose

# Remove a package
dotr packages remove nvim

# Remove package and its orphaned dependencies
dotr packages remove nvim --remove-orphans

# List all profiles
dotr profiles list

# List profiles with verbose details
dotr profiles list --verbose

# Add a new profile
dotr profiles add laptop

# Remove a profile
dotr profiles remove work

# Remove profile and orphaned packages
dotr profiles remove work --remove-orphans

Variables Example

[variables]
EDITOR = "nvim"

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

Use in templates: {{ EDITOR }} and {{ git.email }}

📖 Learn more about Variables

Templating Example

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

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

📖 Learn more about Templating

Actions Example

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

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

Actions support variable interpolation and run before/after deployment.

📖 Learn more about Actions

Prompts Example

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

Prompts are asked once on first deploy, saved to .uservariables.toml (gitignored).

📖 Learn more about Prompts

Profiles Example

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

Deploy with: dotr deploy --profile work

📖 Learn more about Profiles

Symlink Support

Import and deploy dotfiles as symlinks instead of copies for live-editing workflows:

# Import with symlink
dotr import ~/.config/nvim/ --symlink

# Files are deployed to a 'deployed' directory and symlinked to their destinations
# Edit files at ~/.config/nvim/ and changes immediately reflect in the repository

How it works:

Files are copied from source to dotfiles/nvim/ (your repository)
During deployment, files are copied to deployed/nvim/
A symlink is created from ~/.config/nvim/ → deployed/nvim/
Edit at the symlink location, changes are immediately in deployed/, ready to update back to dotfiles/

Configuration:

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

📖 Learn more about Symlinks

Diff Command

# Preview changes before deployment
dotr diff

# Diff specific packages
dotr diff --packages bashrc,nvim

# Diff with profile
dotr diff --profile work

Shows line-by-line differences with color coding (+ green for additions, - red for deletions).

📖 Learn more about Diff

Dry Run Mode

# Preview deploy without making any changes
dotr deploy --dry-run

# Preview update without making any changes
dotr update --dry-run

# Combine with other options
dotr deploy --dry-run --profile work --packages nvim,bashrc

# Preview deploy without cleaning extra files
dotr deploy --dry-run --clean=false

Dry run mode shows what would happen during deploy or update operations without:

Creating or modifying any files
Creating backups
Executing pre/post actions
Removing extra files (clean operations run by default)

Clean Mode

By default, DotR cleans up destination directories by removing files that don't exist in your dotfiles repository. This keeps your configurations synchronized.

# Deploy with cleaning (default behavior)
dotr deploy

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

# Update with cleaning (default)
dotr update

# Update without cleaning
dotr update --clean=false

Package-level configuration:

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