Diff

Diff Command

The diff command shows you what changes would be made if you deployed your dotfiles, without actually modifying any files. This is useful for previewing changes, debugging templates, and verifying configurations before deployment.

For previewing operations without making changes, see also: Dry Run Mode

Overview

The diff command provides a line-by-line comparison between:

• Files in your repository (with templates compiled)
• Files currently deployed on your system

This allows you to:

• Preview changes before deploying to a new machine
• Check what you've modified locally before updating back to your repository
• Debug templating issues by seeing the compiled output
• Verify profile-specific configurations

Basic Usage

# Show differences for all packages
dotr diff

# Show differences for specific packages
dotr diff --packages bashrc nvim

# Show differences with profile variables applied
dotr diff --profile work

# Combine package and profile filters
dotr diff --packages nvim tmux --profile home

# Continue even if some packages fail
dotr diff --ignore-errors

Output Format

The diff command shows a line-by-line comparison with color coding:

• Lines starting with - (in red): Lines that exist in the deployed file but not in the repository
• Lines starting with + (in green): Lines that exist in the repository but not in the deployed file
• Lines starting with a space: Unchanged lines (for context)

Example Output

[INFO] Diff for package 'f_bashrc':
[INFO] Differences for 'dotfiles/f_bashrc' at '/home/user/.bashrc':
 # Bashrc configuration
-export EDITOR=vim
+export EDITOR=nvim
 export PATH="$HOME/.local/bin:$PATH"
+alias ll='ls -la'

In this example:

• The deployed file has EDITOR=vim (shown with -)
• The repository has EDITOR=nvim (shown with +)
• A new alias has been added to the repository (shown with +)

Command Options

dotr diff [OPTIONS]

Options:
  -p, --packages [<PACKAGES>...]   Specify which packages to diff
  -P, --profile <PROFILE>          Use a specific profile
      --ignore-errors              Continue operation even if errors occur
  -w, --working-dir <WORKING_DIR>  Specify working directory
  -h, --help                       Print help

The --ignore-errors flag is particularly useful when diffing multiple packages where some may have issues (missing files, permission errors, etc.) but you still want to see the diff for the remaining packages.

Use Cases

1. Preview Changes Before Deployment

Check what will change on a new machine before running deploy:

# See all changes
dotr diff

# Review changes, then deploy if satisfied
dotr deploy

2. Verify Template Compilation

Debug templating issues by seeing the compiled output:

# Check how templates render with current variables
dotr diff --packages nvim

# Check how templates render with profile variables
dotr diff --packages nvim --profile work

3. Profile-Specific Configuration Testing

Verify that different profiles produce the expected configurations:

# Check work profile configuration
dotr diff --profile work

# Compare with home profile
dotr diff --profile home

4. Check Local Modifications

See what you've changed locally before updating back to repository:

# See what's different in your deployed files
dotr diff

# If you want to keep the changes, update them
dotr update

5. Selective Package Verification

Check specific packages without showing all diffs:

# Only check git and bash configurations
dotr diff --packages f_gitconfig f_bashrc

# Check editor configurations
dotr diff --packages d_nvim f_vimrc

How Diff Works

1. Loads configuration from config.toml
2. Applies profile variables if --profile is specified
3. Compiles templates using Tera with all available variables
4. Respects ignore patterns - files matching ignore patterns are excluded
5. Compares files between repository and deployed locations
6. Shows differences in unified diff format

Note: Files that match ignore patterns in the package configuration are automatically excluded from the diff output.

Template Handling

For templated files, diff shows the compiled output:

Repository file (dotfiles/f_bashrc):

export EDITOR="{{ EDITOR }}"
export THEME="{{ THEME }}"

With variables:

[variables]
EDITOR = "nvim"
THEME = "tokyonight"

Diff output shows compiled result:

+export EDITOR="nvim"
+export THEME="tokyonight"

Granular Changes

DotR v0.13.0 introduced granular copying and backups, which work hand-in-hand with the diff command:

• Only changed files are deployed - if a file's content hasn't changed, it won't be copied
• Per-file backups - backups are created with .dotrbak extension (e.g., init.lua.dotrbak, .bashrc.dotrbak)
• Efficient updates - reduces unnecessary file operations and backup clutter

This means:

1. Running diff before deploy shows exactly what will be changed
2. Only files that actually differ will be deployed and backed up
3. Unchanged files are skipped entirely, making deployments faster

Workflow Examples

New Machine Setup

# Clone your dotfiles
git clone https://github.com/user/dotfiles.git ~/dotfiles
cd ~/dotfiles

# Preview what will be deployed
dotr diff

# Review changes, then deploy
dotr deploy

Testing Configuration Changes

# Make changes to your repository
vim dotfiles/f_bashrc

# Preview the changes
dotr diff --packages f_bashrc

# Deploy if satisfied
dotr deploy --packages f_bashrc

Profile Switching

# Check what would change with work profile
dotr diff --profile work

# Check what would change with home profile
dotr diff --profile home

# Deploy the one you want
dotr deploy --profile work

Before Updating Repository

# Made changes to deployed files? Check what's different
dotr diff

# Update changed files back to repository
dotr update

Combining with Other Commands

The diff command works seamlessly with other DotR commands:

# Preview changes, deploy, then check again
dotr diff
dotr deploy
dotr diff  # Should show no differences

# Check specific package with profile
dotr diff --packages nvim --profile work

# Deploy that same configuration
dotr deploy --packages nvim --profile work

# Update after local changes
dotr diff  # See what changed
dotr update  # Update repository

Troubleshooting

No Output

If dotr diff shows no output:

• Files in repository match deployed files exactly
• No packages are configured
• Package destinations don't exist yet (nothing to compare)

Diff Shows Unexpected Changes

• Check that templates are compiling correctly: dotr print-vars
• Verify profile variables are what you expect: dotr print-vars --profile name
• Ensure destination paths in config.toml are correct

Template Variables Not Rendering

• Make sure variables are defined (check with dotr print-vars)
• Check variable precedence: user > profile > package > config > environment
• Verify Tera syntax: {{ VARIABLE }} not $VARIABLE

Permission Errors

• Ensure you have read access to deployed file locations
• Check that file paths are correct in config.toml

Best Practices

1. Always diff before deploy on a new machine to see what will change
2. Use diff after making changes to verify your modifications
3. Test profile configurations with diff before switching environments
4. Review template output to ensure variables compile correctly
5. Diff specific packages when working on particular configurations
6. Use with profiles to test environment-specific setups
7. Check before updating to see what local changes you've made

Further Reading

• Configuration Guide - Learn about package configuration
• Templating Guide - Learn about variable usage in templates
• Profiles Guide - Learn about environment-specific configurations
• Home - Return to main documentation

---

Dry Run Mode

The --dry-run flag is available on deploy and update commands to preview what would happen without actually making any changes to your system.

Overview

Dry run mode allows you to:

• Preview deployments before making changes
• See what files would be updated without modifying them
• Verify actions without executing them
• Test configurations safely

Usage

# Preview what deploy would do
dotr deploy --dry-run

# Preview update operations
dotr update --dry-run

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

What Dry Run Does NOT Do

When you use --dry-run, DotR will NOT:

• ✗ Create or modify any files
• ✗ Create backup files (.dotrbak)
• ✗ Execute pre-actions or post-actions
• ✗ Remove files (even with --clean flag)
• ✗ Create directories

What Dry Run DOES Show

Dry run mode WILL:

• ✓ Show which files would be deployed/updated
• ✓ Display file paths and operations
• ✓ Indicate which actions would run (with "(Dry Run) Would execute action:" prefix)
• ✓ Show which files would be removed with --clean
• ✓ Apply all filtering (packages, profiles, ignore patterns)

Examples

Preview Deployment

$ dotr deploy --dry-run
[INFO] Package 'f_bashrc' deployed
=> Deployed dotfiles/f_bashrc -> /home/user/.bashrc
[INFO] Package 'd_nvim' deployed
=> Deployed init.lua -> /home/user/.config/nvim/init.lua
=> Deployed plugins.lua -> /home/user/.config/nvim/plugins.lua

In dry run mode, these messages indicate what would happen, but no files are actually copied.

Preview with Actions

$ dotr deploy --dry-run --packages d_nvim
(Dry Run) Would execute action: mkdir -p ~/.local/share/nvim
[INFO] Package 'd_nvim' deployed
=> Deployed init.lua -> /home/user/.config/nvim/init.lua
(Dry Run) Would execute action: nvim --headless +PluginInstall +qall

Actions are shown but not executed.

Preview Clean Operation

$ dotr deploy --dry-run --clean
[INFO] Package 'f_bashrc' deployed
=> Deployed dotfiles/f_bashrc -> /home/user/.bashrc
(Dry Run) Would remove file: /home/user/.bashrc.old
(Dry Run) Would remove directory: /home/user/.config/old_config

Shows what would be cleaned up without actually removing anything.

Preview Update

$ dotr update --dry-run
=> Backed up /home/user/.bashrc -> dotfiles/f_bashrc
[INFO] Package 'f_bashrc' updated
=> Backed up /home/user/.vimrc -> dotfiles/f_vimrc
[INFO] Package 'f_vimrc' updated

Shows what would be updated without copying files.

Dry Run vs Diff

Both commands help you preview changes, but they serve different purposes:

Feature	diff	deploy --dry-run / update --dry-run
Shows file content differences	✓	✗
Line-by-line comparison	✓	✗
Shows which files affected	✓	✓
Previews actions	✗	✓
Shows clean operations	✗	✓
Available on deploy	✗	✓
Available on update	✗	✓
Shows template compilation	✓	✗

Use diff when you want to see what changed in file contents.

Use --dry-run when you want to see what operations would execute without making changes.

Workflow Examples

Safe Deployment Workflow

# 1. Check file content differences
dotr diff

# 2. Preview the deployment operations
dotr deploy --dry-run

# 3. Deploy for real
dotr deploy

Testing Configuration Changes

# Make changes to your repository
vim dotfiles/f_bashrc

# Preview changes
dotr diff --packages f_bashrc

# Preview deployment operations
dotr deploy --dry-run --packages f_bashrc

# Deploy if satisfied
dotr deploy --packages f_bashrc

Profile Testing

# Preview what work profile would deploy
dotr deploy --dry-run --profile work

# Preview what home profile would deploy
dotr deploy --dry-run --profile home

# Choose one to deploy
dotr deploy --profile work

Testing Clean Operations

# Preview what would be removed
dotr deploy --dry-run --clean

# Review the output, then clean for real
dotr deploy --clean

Best Practices

1. Use dry run before first deployment on a new machine to verify operations
2. Test --clean flag with dry run first to avoid accidentally removing files
3. Verify actions that would execute, especially destructive ones
4. Combine with diff for complete preview (content changes + operations)
5. Test profile changes with dry run before switching environments

Further Reading

• Diff Command - Preview file content changes
• Configuration Guide - Learn about package configuration
• Actions Guide - Learn about pre/post actions
• Home - Return to main documentation