← Back

tidydots — Cross-Platform Dotfile Manager

2024 – Present Repository
Go Bubble Tea SQLite YAML

Problem

Managing dotfiles across multiple machines with different operating systems is tedious and error-prone. Existing tools either lack cross-platform support, can’t handle platform-specific configurations, or fail to preserve local modifications when syncing changes. I needed a solution that worked seamlessly on both Linux and Windows while allowing templated configs and smart conflict resolution.

Approach

Built a symlink-based dotfile manager in Go that treats a Git repository as the single source of truth. Instead of copying files, tidydots creates symlinks from system config locations to the repo, ensuring changes are immediately trackable. Added Go template support with platform variables (.OS, .Distro, .HasDisplay, .IsWSL) to handle OS-specific paths and settings in a single file. Implemented a 3-way merge algorithm using SQLite state storage to detect conflicts between repo updates and local modifications.

Technical Details

  • Template Engine: Go text templates with sprout functions, automatic .tmpl suffix detection for dynamic configs
  • Conflict Resolution: SQLite-backed 3-way merge (last-known state vs. current repo vs. current system) preserves user edits during restore operations
  • Package Management: Unified interface for pacman, yay, apt, dnf, brew, winget, scoop, choco, and git repos with lazy loading for ~50x performance improvement
  • Interactive TUI: Bubble Tea-powered interface with multi-selection, fuzzy search filtering, file picker, and progress bars for adopt/restore workflows
  • Cross-Platform: Handles Windows vs. Unix path differences, symlink permissions, and OS-specific default locations
  • Two-Level Config: App config (user preferences) + repo config (dotfile mappings) using YAML v3 schema with validation

LLM-Augmented Development

Developed using Claude Code and GitHub Copilot throughout the project lifecycle:

  • Architecture: LLM-assisted design of the 3-way merge algorithm and cross-platform path resolution strategy
  • Testing: Scaffolded table-driven tests and edge case discovery for template rendering across OS variants
  • Edge Cases: Used LLMs to systematically explore symlink permission differences, WSL path translation, and package manager quirks across 10+ backends

Results

  • Manages configurations across Linux (Arch, Ubuntu) and Windows (WSL) from a single repository
  • Dry-run mode and interactive diff viewer (nvim/tmux) prevent accidental overwrites
  • Adopt workflow automates migrating existing configs into the repo
  • Template system eliminates per-machine config files — one template handles all platforms
  • Documentation site at tidydots.io built with MkDocs