Plonk

The unified package and dotfile manager for developers who tinker. One command to set up your entire development environment.

# Install plonk and set up your environment
brew install --cask richhaase/tap/plonk
plonk clone user/dotfiles
# Done. Seriously.

What is Plonk?

Plonk is the missing link between dotfile managers and package managers. Born from the frustration of maintaining separate tools for configuration files and installed packages, plonk unifies both in a single, simple tool.

Why another dotfile manager? → Read the full story

After trying bash scripts, symlink farms, dotter, and chezmoi, I wanted something that:

• Manages packages as a first-class concern alongside dotfiles
• Has zero configuration complexity (no templates, no YAML manifestos)
• Adapts quickly to my constantly changing toolset
• Just works

Key innovations:

• Package Manager Manager™: One interface for 8 package managers (brew, npm, pnpm, cargo, pipx, conda, gem, uv)
• Filesystem as truth: Your dotfiles directory IS the state - no sync issues
• Copy, don't symlink: Cleaner, simpler, and more compatible
• State-based: Track what should exist, not what commands were run
• Drift detection: Know when deployed dotfiles have been modified (plonk diff)
• Extensible: Add custom package managers via YAML config in plonk.yaml
• AI-friendly: Built with and for AI coding assistants

For developers who:

• Set up new machines/VMs regularly
• Experiment with new CLI/TUI tools constantly
• Want their environment manager to keep up with their tinkering
• Value simplicity over features

Core Philosophy

Just works - Zero configuration required Unified - Packages and dotfiles together Simple - Your filesystem IS the state Fast - One command from fresh OS to ready

Quick Start

Prerequisites

1. Install Homebrew (if not already installed): Visit brew.sh for installation instructions

2. Install plonk:

   # Via Homebrew (recommended)
   brew install --cask richhaase/tap/plonk
   
   # Via Go (requires Go 1.23+)
   go install github.com/richhaase/plonk/cmd/plonk@latest

Requirements: Homebrew, Git

📖 Complete Installation Guide →

Basic Usage

# Track your existing setup
plonk add ~/.zshrc ~/.vimrc ~/.config/nvim/    # Add dotfiles
plonk install ripgrep fd bat                   # Install & track packages
# Ensure language/package managers (pnpm, cargo, etc.) are installed first
# Use `plonk doctor` for detection and install guidance

# See what plonk manages
plonk status                                   # Show all resources

# Replicate on a new machine
plonk clone your-github/dotfiles              # Clone and apply everything

The beauty is in what you don't need to do:

• No configuration files to write
• No symlinks to manage
• No separate package lists to maintain
• No complex templating languages to learn

Setting Up a New Machine

The fastest way to set up a new development machine:

# Install prerequisites (visit brew.sh for installation instructions)
# After installing Homebrew:

# Install plonk
brew install --cask richhaase/tap/plonk

# Clone existing dotfiles and set up environment
plonk clone user/dotfiles                # GitHub shorthand
plonk clone https://github.com/user/dotfiles.git

# Or start fresh - just start using plonk
plonk add ~/.zshrc                       # Start tracking your dotfiles

The clone command:

1. Clones your dotfiles repository
2. Verifies required package managers; if missing, use plonk doctor for instructions
3. Runs plonk apply to install all packages and deploy dotfiles
4. Gets your machine ready for development in minutes

Prerequisites: Homebrew and Git are required before installing plonk.

Key Commands

# Package management
plonk install ripgrep fd              # Install and track packages
plonk install pnpm cargo              # Install package managers (must be available via another manager)
plonk uninstall ripgrep               # Uninstall and stop tracking
plonk upgrade                         # Upgrade all packages to latest versions
plonk upgrade brew:ripgrep            # Upgrade specific package

# Dotfile management
plonk add ~/.vimrc ~/.zshrc           # Start tracking dotfiles
plonk add -y                          # Sync all drifted files from $HOME to $PLONK_DIR
plonk rm ~/.vimrc                     # Stop tracking (doesn't delete file)
plonk dotfiles                        # List dotfiles with state info

# System state
plonk status                          # Show all managed items (including drift)
plonk apply                           # Sync system to desired state
plonk apply ~/.vimrc ~/.zshrc         # Apply only specific dotfiles
plonk diff                            # Show differences for drifted dotfiles
plonk doctor                          # Check system health

# Configuration
plonk config show                     # View current settings
plonk config edit                     # Edit configuration

Supported Package Managers

Plonk supports 8 package managers across multiple language ecosystems:

Package Managers

• Homebrew (brew) - macOS/Linux packages and system tools
• NPM (npm) - Node.js packages (global)
• PNPM (pnpm) - Fast, disk-efficient Node.js packages (global)
• Cargo (cargo) - Rust packages
• Pipx (pipx) - Python applications in isolated environments
• Conda (conda) - Scientific computing and data science packages
• Gem (gem) - Ruby packages
• UV (uv) - Fast Python tool manager with isolated environments

Package manager prefixes:

# Install packages via specific managers
plonk install brew:wget npm:prettier pnpm:typescript cargo:ripgrep
plonk install pipx:black conda:numpy gem:rubocop
plonk install uv:ruff

Configuration

Plonk stores its data in ~/.config/plonk/:

• plonk.lock - Automatically maintained list of packages
• plonk.yaml - Optional configuration (only create if needed)
• Dotfiles - Stored directly in the config directory (e.g., zshrc, vimrc)

The lock file is automatically updated when you:

• Install/uninstall packages via plonk

Dotfiles are managed by the filesystem itself - files in $PLONK_DIR are your tracked dotfiles

Share your plonk.lock file (e.g., in a dotfiles repo) to replicate your environment on other machines.

Output Formats

All commands support multiple output formats:

plonk status --output json       # JSON output for scripts/tools
plonk status --output yaml       # YAML output
plonk status --output table      # Human-readable table (default)

Output

Plonk uses minimal colorization for status indicators:

• Green: Success/managed/available states
• Red: Error/missing/failed states
• Yellow: Warning/unmanaged states
• Blue: Informational annotations

Respects the standard NO_COLOR environment variable for color-free output.

Development

For contributors and developers:

# Clone and set up development environment
git clone https://github.com/richhaase/plonk
cd plonk
just dev-setup          # Install dependencies and tools

# Run tests
go test ./...           # Unit tests

# Build and install locally
just install

Documentation

Core Documentation

• Why Plonk? - The journey that led to plonk and what makes it different
• Architecture - Technical design, state model, and implementation details

Command Documentation

• Clone - Clone and set up existing dotfiles
• Apply - Sync your system to desired state
• Status - View managed packages and dotfiles
• Package Management - install, uninstall, upgrade
• Upgrade - Upgrade packages to latest versions
• Dotfile Management - add, rm
• Config - Manage plonk configuration
• Doctor - Check system health

Requirements

• Homebrew (required prerequisite)
• Git (for cloning repositories)
• Go 1.23+ (only if installing via go install)
• macOS, Linux, or Windows (WSL)

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

See the codebase for examples and patterns.