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

1. Initialize a dotfiles repository:

dotr init

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

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

6. 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:

1. Files are copied from source to dotfiles/nvim/ (your repository)
2. During deployment, files are copied to deployed/nvim/
3. A symlink is created from ~/.config/nvim/ → deployed/nvim/
4. 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

How it works:

• Files in destination that aren't in source are removed during deploy/update
• Backup files (.dotrbak extension) are never removed
• Files matching ignore patterns are preserved
• CLI --clean flag overrides package-level settings
• Use --clean=false to keep extra files in destination

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

• Linux (aarch64): dotr-aarch64-unknown-linux-gnu.tar.gz

• Linux Muslc (x86_64): dotr-x86_64-unknown-linux-musl.tar.gz

• Linux Muslc (aarch64): dotr-aarch64-unknown-linux-musl.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        Initialize 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    Manage packages (list, import, deploy, update, remove, diff).
  profiles    Manage profiles (list, add, remove).
  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

Package Commands

# List packages
dotr packages list [OPTIONS]
  --verbose          # Show detailed package information

# Remove packages
dotr packages remove <PACKAGE>... [OPTIONS]
  --force            # Force removal without confirmation
  --remove-orphans   # Remove orphaned dependencies
  --dry-run          # Preview what would be removed

Profile Commands

# List profiles
dotr profiles list [OPTIONS]
  --verbose          # Show detailed profile information

# Add a profile
dotr profiles add <PROFILE_NAME>

# Remove a profile
dotr profiles remove <PROFILE_NAME> [OPTIONS]
  --remove-orphans   # Remove packages only used by this profile
  --dry-run          # Preview what would be removed

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 (import and deploy with symlinks)
• Package management (list, remove with orphan cleanup)
• Profile management (add, remove with orphan cleanup)