dots

A cross-platform dotfiles manager for macOS and Linux. Sync configs across machines with profile-based organization, automatic discovery, and remote deployment.

Features

• Cross-platform - Separate paths per platform (macOS/Linux)
• Profile-based - Organize configs into minimal, dev, and full profiles
• Interactive CLI - Menu-driven interface with prompts
• Remote deployment - Deploy to remote machines via SSH + rsync
• Preferences sync - Backup and restore system preferences (macOS defaults, Linux gsettings)
• Auto-discovery - Scan for 210+ known config file patterns
• Brewfile sync - Generate Brewfile from installed Homebrew packages
• Conflict resolution - Detect and handle conflicts during deployment

Installation

Requires Bun.

git clone https://github.com/yourusername/dots.git
cd dots
bun install

Add to your PATH or create an alias:

alias dots='bun /path/to/dots/src/index.ts'

Quick Start

# Interactive menu
dots

# Initialize dots configuration
dots init

# Backup configs from system to repo
dots backup

# Deploy configs to local machine
dots deploy

# Deploy to a remote machine
dots remote

Flows

Initialize (dots init)

Set up your dotfiles repository for the first time:

1. Choose repository location (default: ~/dotfiles)
2. Configure Brewfile sync preference
3. Initialize git repository
4. Optionally push to GitHub

dots init                # Interactive setup wizard
dots init -f             # Force reinitialize

Backup Flow (dots backup)

Backup configuration files from your system to the repository:

1. Check for manifest (prompts init if missing)
2. Optionally discover new configs to track
3. Backup all tracked configs to repo
4. Optionally backup system preferences
5. Git commit and push

dots backup              # Interactive backup
dots backup -a           # Non-interactive: sync all, commit, push
dots backup -n           # Dry run - preview changes
dots backup -y           # Auto-confirm prompts

Modes:

• Interactive (default): Prompts for discovery, prefs backup, commit message
• Non-interactive (-a): Syncs all tracked configs, auto-commits with default message, pushes

Deploy Flow (dots deploy)

Deploy configs from repository to local machine:

1. Git checks (warn uncommitted changes, offer to pull)
2. Select deployment profile
3. Select configs to deploy (shows diff preview)
4. Select packages to install from Brewfile (macOS)
5. Select preference categories to apply
6. Resolve any conflicts
7. Execute: packages → configs → prefs
8. SSH key setup guidance
9. Post-setup instructions

dots deploy              # Interactive deployment
dots deploy -p minimal   # Deploy specific profile
dots deploy -f           # Force deploy, skip confirmations
dots deploy -n           # Dry run - preview changes

Conflict Resolution: When local files differ from repo versions:

• Overwrite - Replace local with repo version
• Keep - Skip this config
• Backup then overwrite - Save local as .backup, then deploy

Remote Deploy (dots remote)

Deploy configs to a remote machine via SSH:

1. Enter SSH credentials (host, username)
2. Test connection and detect remote platform
3. Select deployment profile
4. Select configs to deploy
5. Select packages to install (if macOS remote)
6. Select preferences to apply
7. Execute deployment via rsync
8. Post-setup instructions

dots remote              # Interactive SSH deployment
dots remote -p dev       # Deploy dev profile to remote
dots remote -n           # Dry run - preview changes

Features:

• Auto-detects remote platform (macOS/Linux)
• Uses rsync for efficient file transfer
• Base64-encoded Brewfile transfer (prevents shell injection)
• Applies remote preferences via SSH

Discovery (dots discover)

Scan system for untracked configuration files:

dots discover            # Interactive discovery

Features:

• Recognizes 210+ known config patterns
• Smart profile suggestions based on config category
• Scans configurable paths
• Respects ignore patterns

Brewfile Sync (dots brewfile)

Sync Brewfile from installed Homebrew packages (macOS only):

dots brewfile            # Generate/update Brewfile
dots brewfile -n         # Dry run

Runs brew bundle dump --all and saves to your dotfiles directory.

Edit Manifest (dots edit)

Manage configs, profiles, and settings:

dots edit                # Interactive editor

Options:

• Add/remove/edit config entries
• Manage profiles
• Configure discovery settings

CLI Options

Usage: dots [command] [options]

Commands:
  (none)      Interactive menu
  init        Initialize dots configuration
  backup      Backup flow (discover, backup, prefs)
  deploy      Deploy flow (packages, configs, prefs)
  edit        Edit manifest (configs, profiles)
  remote      Deploy to remote machine via SSH
  brewfile    Sync Brewfile from installed packages
  discover    Scan for new configuration files

Options:
  -h, --help      Show help message
  -v, --version   Show version
  -p, --profile   Use specific profile (minimal, dev, full)
  -f, --force     Skip confirmation prompts
  -n, --dry-run   Preview changes without applying
  -a, --all       Backup all tracked configs (non-interactive)
  -y, --yes       Auto-confirm prompts

Configuration

Configuration is stored at ~/.config/dots/config.json.

Basic Structure

{
  "version": 1,
  "syncBrewfile": true,
  "configs": [...],
  "profiles": [...],
  "discovery": {...},
  "defaults": {...}
}

Config Entry

Each config entry defines a file or directory to sync:

{
  "id": "zshrc",
  "name": "Zsh Config",
  "source": {
    "darwin": "~/.zshrc",
    "linux": "~/.zshrc"
  },
  "dest": ".zshrc",
  "type": "file",
  "profiles": ["minimal", "dev", "full"],
  "exclude": ["*.cache"],
  "secret": false,
  "description": "Zsh shell configuration"
}

Field	Required	Description
id	Yes	Unique identifier
name	Yes	Display name
source	Yes	Platform-specific source paths
dest	Yes	Destination path in dotfiles dir
type	Yes	file or directory
profiles	No	Which profiles include this config
exclude	No	Glob patterns to exclude (directories only)
secret	No	Mark as sensitive
description	No	Human-readable description

Profiles

Profiles group configs for different use cases:

{
  "profiles": [
    {
      "name": "minimal",
      "description": "Essential configs only",
      "includes": ["zshrc", "zshenv", "gitconfig"]
    },
    {
      "name": "dev",
      "description": "Development setup",
      "extends": ["minimal"],
      "includes": ["neovim", "lazygit", "bat"]
    },
    {
      "name": "full",
      "description": "All configs",
      "extends": ["dev"],
      "includes": ["*"]
    }
  ]
}

• includes - Array of config IDs, or ["*"] for all
• extends - Inherit configs from other profiles (with cycle detection)

Discovery Settings

Configure where to scan for configs:

{
  "discovery": {
    "scanPaths": {
      "darwin": ["~/.config", "~/Library/Application Support", "~"],
      "linux": ["~/.config", "~/.local/share", "~"]
    },
    "ignore": ["*.log", "*.cache", "node_modules", ".git"]
  }
}

Saved Preferences

Platform preferences are stored in the manifest:

{
  "defaults": {
    "darwin": {
      "dock": {
        "com.apple.dock": {
          "autohide": true,
          "tilesize": 48
        }
      }
    },
    "linux": {
      "gnome": {
        "org.gnome.desktop.interface": {
          "color-scheme": "prefer-dark"
        }
      }
    }
  }
}

File Structure

~/.config/dots/
├── config.json         # Main configuration manifest
└── dotfiles/           # Synced configuration files
    ├── .zshrc
    ├── .gitconfig
    ├── .config/
    │   ├── nvim/
    │   ├── starship.toml
    │   └── ...
    └── Brewfile

Known Config Patterns

Discovery recognizes 210+ configurations including:

• Shells: zsh, bash, fish, nushell
• Editors: neovim, vim, vscode, cursor, emacs
• Terminals: alacritty, kitty, wezterm, ghostty, iterm2
• Multiplexers: tmux, zellij
• Git: gitconfig, gh, lazygit
• CLI tools: starship, bat, ripgrep, fzf, zoxide, atuin
• File managers: yazi, ranger, lf
• Window managers: i3, sway, hyprland, aerospace, yabai
• DevOps: aws, gcloud, kubectl, terraform, docker
• AI tools: claude, aider, continue, copilot

Platform Preferences

macOS (via defaults)

• Dock: autohide, tile size, magnification, position
• Finder: sidebar, status bar, path bar, extensions
• Keyboard: repeat rate, key delay
• Trackpad: tap to click, three-finger drag
• Screenshots: location, format, shadow
• Menu bar: clock format

Linux (via gsettings)

• GNOME interface: color scheme, themes, fonts
• Window manager: button layout, focus mode
• Keyboard settings

Security

• Path traversal protection: Validates paths stay within allowed directories
• Shell injection prevention: Uses base64 encoding for remote file transfer
• Cycle detection: Prevents infinite loops in profile inheritance
• Manifest validation: Validates schema before saving

License

MIT