dotman

Package-oriented dotfile manager with planning, diff review, and two-way sync.

Inspiration

dotman is inspired by tools like pacman and yay, especially in its CLI ergonomics, selection flows, and review-oriented workflow.

Why

Modern development workflows are encoded in dotfiles, editor state, helper scripts, and selected system configuration.

dotman is for deploying that workflow reproducibly across machines by treating it as a packageable, reviewable, and synchronizable configuration graph.

Design philosophy

Intuition over configuration.

First principles over convention.

Declarative over imperative.

Platform support

dotman follows XDG-style paths and UNIX-like filesystem and process conventions. It is currently intended for UNIX-like systems.

Install

Required

• uv for installation
• git for diff review

Install command

uv tool install git+https://github.com/ewgdg/dotman.git

Optional dependencies

• fzf for long interactive selector lists
• less for paged diff review fallback
• nvim for review and reconciliation flows; set VISUAL=nvim or EDITOR=nvim to use it
• sudo for managing protected system paths

Diagnose setup

dotman doctor

This checks manager config, repo paths, tracked package state files, and external dependencies such as git, with optional dependency hints for tools like fzf.

Quick start

The install command above installs the CLI. Clone the repo separately if you want to use the bundled example repo under examples/repo/:

git clone https://github.com/ewgdg/dotman.git ~/projects/dotman
mkdir -p ~/.config/dotman
cat > ~/.config/dotman/config.toml <<'EOF'
[repos.example]
path = "~/projects/dotman/examples/repo"
order = 10
EOF

Track and push one simple package from the example repo. This writes the example note to ~/.config/dotman-example/note.txt:

dotman track example:note@basic
dotman push --dry-run
dotman push

For a larger real-world example repo, see ewgdg/dotfiles.

Documentation

• CLI behavior: docs/cli.md
• User config: docs/config.md
• Repository layout: docs/repository.md
• Template targets: docs/templates.md

Features

Modular package system

Group dotfiles and system files into reusable packages.

Tracked packages with track and untrack

Persist or remove tracked packages so repeated push and pull runs can reuse the same selections.

Example:

dotman track example:git@basic
dotman untrack example:git@basic

Package scaffolding and authoring

Use add to propose or extend package target definitions from live paths. Use edit to open repo-side package or target sources in your editor.

Example:

dotman add ~/.gitconfig example:git
dotman edit package example:git
dotman edit target example:git.gitconfig

Two-way sync

• push applies managed changes from the repo to the live system
• pull updates the repo from the live system

Example:

dotman push
dotman pull

Interactive selection and review workflow

Support partial selector matching, interactive disambiguation, combined selection flows, and diff review before execution, with a workflow inspired by yay for a more familiar terminal experience.

Snapshots and rollback

Create snapshots before real push runs and restore managed paths with rollback.

Example:

dotman rollback latest

Flexible template support

Support custom render and capture functions per target.

Reconcile editor

Support editor-backed reconciliation during pull flows.

First-class system files support

Manage user dotfiles and system files alike; dotman escalates privileges automatically when needed.