Skip to content

detection.md

Latest commit

 

History

History
248 lines (179 loc) · 5.3 KB

detection.md

File metadata and controls

248 lines (179 loc) · 5.3 KB
Raw

Understanding Dotbak Modes

Complete guide to snapshot and symlink modes.

The Two Modes

dotbak offers two fundamentally different approaches to managing your dotfiles.

📸 Snapshot Mode (Default)

Concept: Your files stay in their original locations. You manually create timestamped backups when ready.

How It Works

# Add files to snapshot tracking
$ dotbak add --snapshot ~/.zshrc
✓ Added to snapshot tracking

# File structure:
~/.zshrc  ← Your actual file (NOT a symlink)

# Nothing backed up yet!

# Create snapshot when ready
$ dotbak snapshot
✓ Snapshot created: 2025-12-01-164520

# Backup structure:
~/.dotbak/snapshots/2025-12-01-164520/.zshrc  ← Copy

What Gets Tracked

In snapshot.toml:

[[files]]
original = "~/.zshrc"
type = "file"
added = "2025-12-01T15:38:03Z"

File behavior:

  • ✅ Original file stays in place
  • ✅ No symlinks created
  • ✅ You control when to backup
  • ✅ Multiple versions kept (timestamped)

When to Use Snapshot Mode

Perfect for:

  • Experimenting with configs
  • Keeping version history
  • Testing before committing
  • Peace of mind (restore any version)
  • Files you edit frequently

Example workflow:

# Morning: Create snapshot
dotbak snapshot

# Edit configs all day
vim ~/.zshrc ~/.vimrc ~/.bashrc

# Evening: Create another snapshot
dotbak snapshot

# Oops, broke something!
dotbak snapshot restore 2025-12-01-090000

🔗 Symlink Mode

Concept: Files are symlinked to backup location. Every change is immediately backed up.

How It Works

# Add file to symlink tracking
$ dotbak add --symlink ~/.tmux.conf

File structure:
~/.tmux.conf → ~/.dotbak/symlinks/.tmux.conf (symlink)

# In symlink.toml:
[[files]]
original = "~/.tmux.conf"
backup = "symlinks/.tmux.conf"
type = "file"

Directory Options in Symlink Mode

When adding a directory with --symlink, you get two choices:

[D] Directory Symlink - Whole directory

~/.config/nvim → ~/.dotbak/symlinks/.config/nvim/  (single symlink)

# ALL files inside are automatically backed up
# New files are auto-synced (no detection needed)

[F] Individual File Symlinks - Per-file

~/.config/nvim/            (real directory, NOT symlinked)
├── init.lua → ~/.dotbak/symlinks/.config/nvim/init.lua
└── plugins.lua → ~/.dotbak/symlinks/.config/nvim/plugins.lua

# Only tracked files are symlinked
# New files are DETECTED and require action

When to Use Symlink Mode

Perfect for:

  • Configs that rarely change
  • Files you want always backed up
  • Simple, set-and-forget approach
  • When you don't need version history

Example workflow:

# Add once
dotbak add --symlink ~/.tmux.conf

# Edit anytime
vim ~/.tmux.conf

# Changes automatically saved to backup!
# No need to run any commands

🔍 New File Detection (Symlink Mode Only)

Detection ONLY applies to symlink mode with individual file symlinks ([F] option).

When Detection Happens

$ dotbak symlink-sync
# OR
$ dotbak sync  (alias)

What Gets Detected

If you tracked:

[[files]]
original = "~/.config/nvim/init.lua"
type = "file"

[[files]]
original = "~/.config/nvim/plugins.lua"
type = "file"

Directory to scan:

~/.config/nvim/  ← Only this directory

Detection result:

$ touch ~/.config/nvim/new-plugin.lua

$ dotbak symlink-sync

Found 1 new file:
~/.config/nvim/new-plugin.lua
  [A]dd / [I]gnore now / i[G]nore always / [Q]uit?

Detection Rules

  • ✅ Scans only directories containing symlink-tracked files
  • ✅ Only with individual file symlinks ([F] mode)
  • ❌ Does NOT scan if directory symlink ([D] mode) - auto-synced already
  • ❌ Does NOT scan snapshot-tracked directories
  • ❌ Does NOT scan HOME directory (~/) - too noisy
  • ❌ Does NOT scan sibling directories

📊 Comparison Table

Feature Snapshot Mode Symlink Mode
File location Original location Symlinked to backup
Backup timing Manual (on demand) Automatic (every change)
Version history ✅ Timestamped snapshots ❌ Single version only
Time-travel ✅ Restore any version ❌ Only current backup
Experimentation ✅ Perfect ⚠️ Risky
New file detection ❌ Not needed ✅ For [F] mode only
Overhead Low (copies when needed) None (live sync)
Best for Configs you edit often Configs you rarely touch

🎯 Recommended Strategy

Use both modes together!

Snapshot for:

  • Shell configs (.zshrc, .bashrc, .profile)
  • Editor configs (.vimrc, init.lua)
  • App configs you experiment with
  • Any file you want version history

Symlink for:

  • Stable configs (.tmux.conf, .gitconfig)
  • Large directories you don't edit often
  • Files you want always backed up

Example setup:

# Snapshot mode (editing frequently)
dotbak add --snapshot ~/.zshrc
dotbak add --snapshot ~/.vimrc
dotbak add --snapshot ~/.config/nvim

# Symlink mode (rarely change)
dotbak add --symlink ~/.tmux.conf
dotbak add --symlink ~/.gitconfig
dotbak add --symlink ~/.ssh/config

# Create first snapshot
dotbak snapshot

# Check everything
dotbak status
dotbak list

For practical examples, see Common Workflows.