dotbak - Simple Dotfiles Manager

A minimal, user-friendly dotfiles backup manager that keeps your configurations safe and portable.

---

Features

• Dual Mode — Snapshot (versioned backups) or Symlink (live-sync), per file
• Versioned Snapshots — Timestamped backups with history, diff, and restore
• Live Symlinks — Auto-synced files with new-file detection (symlink-sync)
• Portable Archives — Export your entire ~/.dotbak as a zip for machine migration
• Interactive — Mode selection, multi-select removal, file detection prompts
• Safe — Dry-run mode, confirmations, atomic installs, SHA256-verified updates
• Well-Tested — 148 tests (unit + integration) via bats-core

---

Quick Start

# Install
curl -fsSL https://raw.githubusercontent.com/darshithedpara/dotbak/main/install.sh | bash -s -- --yes

# Initialize
dotbak init

# Start backing up your dotfiles
dotbak add ~/.zshrc              # Prompts for mode (default: snapshot)
dotbak add ~/.config/nvim        # Choose: directory or individual files

# Create a snapshot
dotbak snapshot

# Check status
dotbak status

Or install from source:

git clone --recurse-submodules https://github.com/darshithedpara/dotbak
cd dotbak
./build.sh          # native binary (requires gcc + shc)
./build.sh --script # portable script (no compiler needed)
./install.sh

Prerequisites: Bash 4.0+, standard Unix utilities (ln, cp, mv, grep, find, zip), curl (for self-update). gcc is optional (for native binary build; falls back to script mode).

---

Key Concepts

Two Tracking Modes

When you add files, you choose the tracking mode:

Snapshot Mode (default) — Versioned backups

# Files stay in original locations
~/.zshrc  (original file, not a symlink)

# Backups stored in timestamped snapshots
~/.dotbak/snapshots/2025-12-01-153803/.zshrc
~/.dotbak/snapshots/2025-12-01-164520/.zshrc

• Files stay in place (no symlinks)
• Create versioned backups on demand
• Restore from any snapshot (time-travel)

Symlink Mode — Live sync

# Files are symlinked to backup
~/.tmux.conf -> ~/.dotbak/symlinks/.tmux.conf

# For directories, choose whole-dir or per-file:
~/.config/nvim -> ~/.dotbak/symlinks/.config/nvim/       (whole dir)
~/.config/nvim/init.lua -> ~/.dotbak/symlinks/.config/nvim/init.lua  (per file)

• Changes auto-saved to backup
• Detect new files with dotbak symlink-sync
• Individual or directory-level symlinks

Snapshot Workflow

# Add files to snapshot tracking
$ dotbak add --snapshot ~/.zshrc
# Edit your files, then create a timestamped backup
$ dotbak snapshot

# See all your snapshots
$ dotbak snapshot list
  2025-12-01-164520 (latest) - 1 hour ago
  2025-12-01-153803 - 2 hours ago

# Restore from any point
$ dotbak snapshot restore 2025-12-01-153803

Symlink Detection

# New file appears in a symlink-tracked directory
$ 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? a

Learn more about detection modes ->

---

Commands

# Core
dotbak init [path]            # Initialize (default: ~/.dotbak)
dotbak add <path>             # Add to tracking (prompts for mode)
dotbak add --snapshot <path>  # Add to snapshot tracking
dotbak add --symlink <path>   # Add to symlink tracking
dotbak list                   # Show tracked files by mode
dotbak status                 # Show status for both modes
dotbak remove [path]          # Remove (interactive if no path)

# Snapshots
dotbak snapshot               # Create timestamped backup
dotbak snapshot list          # Show all snapshots
dotbak snapshot restore <ts>  # Restore from snapshot
dotbak snapshot diff          # Compare with current
dotbak snapshot clean         # Remove old snapshots

# Symlinks
dotbak symlink-sync           # Detect new files (alias: sync)

# Portability
dotbak archive [name]         # Create portable backup
dotbak deploy [--all]         # Deploy on new machine (alias: restore)

# Utilities
dotbak ignored                # Show ignore patterns
dotbak version                # Show version info
dotbak update [version]       # Self-update from GitHub

# Global flags
--dry-run                     # Preview without changes
--yes / -y                    # Skip confirmations
--quiet / -q                  # Minimal output
--help                        # Show help

Full Commands Reference ->

---

Common Workflows

Setting up a new machine:

# On old machine: create portable archive
dotbak archive moving-to-new-machine

# Copy the zip to new machine, extract to ~/.dotbak, then:
dotbak deploy --all --backup

Daily workflow:

vim ~/.zshrc ~/.vimrc          # Edit your configs
dotbak snapshot                # Backup when ready
dotbak symlink-sync            # Detect new files in symlink dirs
dotbak status                  # Check everything

Before risky changes:

dotbak snapshot                # Snapshot current state
# Make changes...
# If something breaks:
dotbak snapshot restore <timestamp>

More Workflows ->

---

Configuration

~/.dotbak/
├── config.toml         # Global settings
├── snapshot.toml       # Snapshot-tracked files
├── symlink.toml        # Symlink-tracked files
├── .dotbakignore       # Ignore patterns
├── snapshots/          # Versioned backups
├── symlinks/           # Live-synced files
└── archives/           # Zip exports

Configuration Details ->

---

Documentation

• Commands Reference — Detailed guide for all commands
• Shell Completions — Tab completion for bash, zsh, fish
• Common Workflows — Practical examples
• Configuration — Settings and ignore patterns
• Development Guide — Building, testing, releasing
• Sandbox Testing — Safe testing with Docker, VMs, and local sandboxes

---

Uninstall

# Removes executable + completions, keeps your data in ~/.dotbak/
./uninstall.sh

To also remove your data: rm -rf ~/.dotbak

---

Contributing

Contributions welcome! See CONTRIBUTING.md for dev setup, coding conventions, and the PR workflow.

Development Guide -> | Security Policy ->

---

License

MIT License — see LICENSE for details.

Author: Darshit Hedpara (darshithedpara@gmail.com)