dotfiles-manager

A thin, open-source wrapper around git's bare-repo dotfiles pattern. It reduces the cognitive load of git plumbing without hiding it. Your files stay where they are, tracked in standard git repos — no new abstractions, no proprietary formats, no lock-in.

If you stop using this tool tomorrow, your dotfiles and their full history are still right there in git. You can drop to raw git commands at any time via dot git, or walk away entirely with nothing to unwind.

See Alternatives for a detailed comparison with the manual bare-repo approach and chezmoi.

Why

• One command to back up: dot sync commits and pushes everything
• One command to set up a new machine: dot remote setup + dot sync
• Full version history: Roll back any file with dot git log
• No new mental model: It's git. If you know git, you know everything
• Works without GitHub: Local-only mode until you're ready to push
• Multiple stores: Manage independent repos from one CLI with --store
• Safety First: Dangerous commands require explicit store confirmation
• AI-agent friendly: MCP server lets Claude or other assistants manage your dotfiles

Architecture

All business logic lives in the SDK (dotgit/sdk/). The CLI and MCP server are thin interface layers — they parse arguments, call SDK functions, and format output. No business logic in CLI or MCP.

dotgit/
  sdk/       ← all logic: tracking, syncing, remote setup, hooks, stores
  cli/       ← thin CLI wrapper (calls SDK, formats for terminal)
  mcp/       ← thin MCP wrapper (calls SDK, exposes as tool schema)

See CONTRIBUTING.md for architecture and testing details.

Install

pipx install git+https://github.com/krisrowe/dotfiles-manager.git

This gives you two commands: dot (CLI) and dot-mcp (MCP server).

User Journeys

First machine: start tracking dotfiles

# Set the active store for the current machine
dot default personal

# Track files (requires explicit --store for safety)
dot --store=personal track ~/.bashrc
dot --store=personal track ~/.config/myapp/

# Setup remote and sync (can use active store implicitly)
dot remote setup --repo-name my-dotfiles
dot sync

Each dot track commits immediately to a local bare repo (e.g. ~/.dotfiles-personal). dot remote setup creates a private GitHub repo and sets a dotfiles-personal topic for discovery. dot sync pushes.

New machine: discover and set up existing stores

# Discover available dotfiles on your GitHub account
dot remote available

# Setup a discovered store
dot --store=personal remote setup --repo-name my-dotfiles
dot default personal
dot sync

remote setup attaches to the existing repo. sync pulls everything down and checks out tracked files to their original paths.

Day-to-day: back up changes

dot sync

Commits any changes, pulls from GitHub, pushes to GitHub. Uses the active store configured for the current machine.

Multiple stores: separate repos for different purposes

# Create a second store
dot stores create work

# Track files scoped to the store (REQUIRED flag)
dot --store=work track ~/.config/work-app/settings.conf

# Sync specifically for the work store
dot --store=work sync

# Or switch your active store and sync normally
dot default work
dot sync

Commands

Day-to-day

Command	Description
dot track <path>	Start tracking (Requires --store)
dot untrack <path>	Stop tracking (Requires --store)
dot list	List all tracked files in active store
dot status	Show modified files in active store
dot sync	Commit + pull + push active store
dot default [NAME]	View or set the machine's active store

Exclude patterns

Control what gets ignored inside tracked directories.

Command	Description
dot exclude add <pattern>	Add a gitignore-format pattern
dot exclude remove <pattern>	Remove a pattern
dot exclude list	Show current patterns

Remote management

Command	Description
dot remote setup [--repo-name NAME]	Create/verify private GitHub repo
dot remote show	Show remote URL of active store
dot remote available	Discover available stores on GitHub

Git hooks

Your global git hooks run on dotfile commits by default. If they interfere:

Command	Description
dot hooks disable	Disable hooks on current store (persistent)
dot hooks reset	Restore global hooks
dot hooks show	Show current hooks state

Stores

Command	Description
dot stores create <name>	Create a new store at ~/.dotfiles-<name>
dot stores list	Show all stores (* = active)

Pass-through git

Command	Description
dot git <args>	Run git commands (Requires --store)

dot --store=work git log --oneline -10
dot --store=personal git diff HEAD~1

Multiple Stores

Manage independent bare repos from one CLI with --store. Each store gets its own tracking, hooks configuration, git remote, and backup strategy.

--store is a top-level option. When omitted, the active store configured via dot default is used for safe commands (sync, status), while risky commands (track, git) will require an explicit flag to prevent accidental cross-contamination.

MCP Server

The MCP server exposes the same SDK functions as the CLI. All MCP tools accept an optional store parameter.

Register with Claude Code

dot mcp install claude

Lay of the Land (Discovery Journey)

Managing a home directory as a work tree can be overwhelming. dotgit provides a structured journey to help you get a lay of the land without the noise.

1. What am I already backing up?

Start with dot list to see exactly which files and directories are currently tracked in your active store.

dot list

2. What needs to be synced?

Use dot status to see local modifications to your tracked files. This is your primary "to-do" list before running dot sync.

dot status

3. What dotfiles am I missing?

dot status also automatically surfaces hidden files and folders (.*) in your home directory that aren't tracked in any of your registered stores. This is the fastest way to discover new configuration files that should be backed up.

4. How do I verify my ignore rules?

If you want to see which hidden files or folders you have intentionally excluded via your ~/.config/git/ignore rules, use the --ignored flag:

dot status --ignored

This is useful for auditing your "black boxes"—ensuring that directories you once chose to forget (like .npm/ or .cache/) are still correctly excluded.

Pro-Tip: Visibility & "Explicit Siblings" If a directory appears in the Ignored list but also contains files that are Tracked (dot list), Modified (dot status), or Discovered (Untracked), it is a "Partially Open Box." This happens when you ignore a parent directory but explicitly track or add an exception (!) for a specific child.

The Visibility Risk: Ignoring a parent directory creates a blackout. If new, valuable files are added to that folder later, Git will silently swallow them, and you will never be prompted to make a conscious choice about tracking them.

The Strategy: For low-noise directories that contain valuable settings (like .gemini/), we recommend ignoring explicit siblings (the specific files and/or sub-folders you don't want) instead of the parent. This keeps the parent "open" so that any new, important files will surface in dot status for your review.

How It Works

...

License

MIT