DotR

---

A dotfiles manager that is as dear as a daughter.

[!WARNING] This is still in beta. The schema is evolving, performance is sub-par. Use it with caution.

Documentation

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

Features

📦 Package Management

• Import dotfiles from any location into your repository
• Deploy dotfiles to their target locations
• Update changes back to your repository
• 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.)
• 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
• 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
• Selective package deployment and updates
• Profile-based deployments for different machines/environments
• Directory structure preservation

Quick Start

1. Initialize a dotfiles repository:

dotr init

2. Import your existing dotfiles:

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

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

3. 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

4. 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

5. 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

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

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
dotr update --dry-run --clean

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 files (when using --clean)

Installation

Homebrew (macOS and Linux)

Supports both Apple Silicon and Intel Macs.

brew tap uroybd/tap
brew install dotr

Cargo

cargo install dotr-dear

From Source

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

Pre-built Binaries

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

• Apple Silicon (M1/M2/M3): dotr-aarch64-apple-darwin.tar.gz
• Intel Mac: dotr-x86_64-apple-darwin.tar.gz
• Linux (x86_64): dotr-x86_64-unknown-linux-gnu.tar.gz

Extract and move the binary to your PATH:

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

Usage

Usage: dotr [OPTIONS] [COMMAND]

Commands:
  init        Intialize dotfiles repository.
  import      Import dotfile and update configuration.
  deploy      Deploy dotfiles from repository.
  update      Update dotfiles from deployed versions.
  diff        Show differences between dotfiles.
  print-vars  Print all user variables.
  packages    List all managed packages.
  profiles
  help        Print this message or the help of the given subcommand(s)

Options:
  -w, --working-dir <WORKING_DIR>
  -h, --help                       Print help
  -V, --version                    Print version

TODO

• Import configs
• Copy configs
• Update configs
• Variables (with nested structures)
• Templating (Tera engine)
• Actions (pre/post hooks)
• Profiles (environment-specific configs)
• Diff command (preview changes)
• Granular copying and backups
• Interactive prompts (config/package/profile level)
• Dry run mode (preview deploy/update without changes)
• Symlinking config