Skip to content

plowman: Dotfile farm manager

build lint tests license codecov readthedocs pypi downloads

plowman is a dotfile management tool that uses an agricultural metaphor to manage your configuration files. It deploys dotfiles from central repositories (called "granaries") to your home directory (where they become "crops"), tracking them in an "estate" file to manage their lifecycle.

Features

  • Template rendering: Use Jinja2 templates with custom variables for dynamic configurations
  • State tracking: Automatically track which files are managed via estate files
  • Smart updates: Skip unchanged files using SHA256 hashing for efficient deployments
  • Automatic cleanup: Remove orphaned files that are no longer in your configuration
  • Bidirectional sync: Deploy with sow, collect changes back with harvest
  • Dry-run mode: Preview changes before applying them with --dry-run
  • Colored diffs: See exactly what changed with syntax-highlighted diff output
  • Multiple granaries: Manage dotfiles from multiple source directories with different variables

Quick Start

Install plowman using uv:

$ uv tool install plowman

Create a basic configuration at ~/.config/plowman/config.yaml:

estates:
    ~/dotfiles:
        granaries: ["bash", "nvim"]
        variables:
            username: myuser
            hostname: myhost

Deploy your dotfiles:

$ plm sow

Collect changes back from your home directory:

$ plm harvest -v

The Agricultural Metaphor

plowman uses an agricultural metaphor for managing dotfiles:

  • Granaries: Source directories containing your dotfile templates and files
  • Seeds: Individual source files in granaries (templates or plain files)
  • Crops: Deployed files in your home directory
  • Estate: State tracking file that records which crops are managed
  • Harvest: Collecting changed crops back to the granary

This metaphor represents the full lifecycle: planting (deploying with sow) configuration files from source granaries to your home directory where they grow into usable configuration files, and harvesting (collecting with harvest) changes back when you edit them manually.

Next Steps