What is dot-man?

dot-man stores your dotfiles in a git repository and uses branches as configuration profiles. Each branch is a complete, deployable snapshot of your environment.

Your Machine                  dot-man Repo               Any Machine
──────────────                ────────────               ───────────
~/.bashrc      ──── save ──►  branch: main  ── deploy ──►  ~/.bashrc
~/.config/nvim ──── save ──►  branch: work  ── deploy ──►  ~/.config/nvim
~/.gitconfig   ──── save ──►  branch: server               ~/.gitconfig

Secrets are never committed. API keys, tokens and passwords are automatically detected, encrypted locally in a vault, and replaced with hashes in the repository before any commit.

Features

Installation

From PyPI (recommended)

pip install dotman-git

Shell completions are installed automatically on first run.

With pipx (isolated)

pipx install dotman-git

From source

git clone https://github.com/BeshoyEhab/dot-man.git
cd dot-man
pip install .

Verify

dot-man --version

Quick Start

# 1. Initialize — runs an interactive wizard that auto-detects your dotfiles
dot-man init

# 2. Add files manually if needed
dot-man add ~/.bashrc
dot-man add ~/.config/nvim

# 3. Create a "work" profile (branch)
dot-man navigate work

# 4. Edit your work-specific configs, then switch back — changes are saved automatically
dot-man navigate main

# 5. See what's changed
dot-man status
dot-man diff

How Branching Works

Each branch is an independent configuration. Switching branches runs three phases automatically:

dot-man navigate work
        │
        ├─► Phase 1: Save   — copies your files into the repo and commits
        ├─► Phase 2: Switch — git checkout work
        └─► Phase 3: Deploy — copies repo files back to your home directory

Commands

Global Flags

These apply to every command and come before the subcommand:

Navigation

Files & Tracking

History & Tags

Security

Import / Export / Discovery

Sync & Remote

Diagnostics

Deprecated

These still work and print a warning, but are hidden from help and removed in v2.0. Use the canonical command on the right.

Configuration

Configuration lives in ~/.config/dot-man/repo/dot-man.toml and is tracked per branch — different branches can track different files.

TOML (default)

# Simple file tracking
[bashrc]
paths = ["~/.bashrc"]
post_deploy = "shell_reload"

# Directory with exclusions
[nvim]
paths = ["~/.config/nvim"]
exclude = ["*.log", "plugin/packer_compiled.lua"]
post_deploy = "nvim_sync"

# SSH config with secret filtering
[ssh-config]
paths = ["~/.ssh/config"]
secrets_filter = true
update_strategy = "rename_old"

# Hyprland with notification on deploy
[hyprland]
paths = ["~/.config/hypr"]
post_deploy = "hyprland_reload"

YAML (also supported)

bashrc:
  paths:
    - ~/.bashrc
  post_deploy: shell_reload

nvim:
  paths:
    - ~/.config/nvim
  exclude:
    - "*.log"
  post_deploy: nvim_sync

Hook Aliases

Instead of writing full shell commands, use built-in aliases:

Update Strategies

Templates & Inheritance

# Define reusable templates
[templates.linux-desktop]
post_deploy = "notify-send 'Config updated'"
update_strategy = "rename_old"

# Inherit in sections
[hyprland]
paths = ["~/.config/hypr"]
inherits = ["linux-desktop"]

[waybar]
paths = ["~/.config/waybar"]
inherits = ["linux-desktop"]

Environment Variable Expansion

[work-files]
paths = ["$WORK_DIR/config", "~/$USER/.config/app"]

Secret Detection

Before any file enters the repository, dot-man scans it for secrets. Detected values are encrypted locally and replaced with a hash placeholder in the repo.

repo file:   api_key = "***REDACTED:e3b0c44298...***"
vault:       { encrypted: "gAAAAABk..." }   ← Fernet AES-128
system file: api_key = "sk-abc123..."       ← restored on deploy

Run dot-man audit to scan at any time. Use dot-man audit --strict in CI/CD pipelines.

Custom Secret Patterns

You can define custom regular expressions to match sensitive patterns, either globally in ~/.config/dot-man/global.toml or for a specific repository in dot-man.toml.

Global custom secrets (global.toml)

[security]
use_default_patterns = true # Set to false to disable built-in patterns

[[security.patterns]]
name = "My Custom API Token"
pattern = 'my_api_key_[a-zA-Z0-9]{32}'
severity = "HIGH"
description = "Internal service API key"

Repository custom secrets (dot-man.toml)

[secrets]
use_default_patterns = true # Set to false to disable built-in patterns
patterns = [
  { name = "Special Repo Key", pattern = 'special_[0-9]+', severity = "CRITICAL" }
]

Multi-Machine Profiles

Profiles let you auto-select the right branch based on hostname:

dot-man profile create work-laptop -h work-laptop -h thinkpad
dot-man profile set-branch work-laptop work
dot-man profile detect   # auto-switches to the right profile

Template Variables

Use {{VARIABLE}} placeholders in your dotfiles that get substituted on deploy:

dot-man template set EMAIL john@work.com
dot-man template set HOSTNAME work-laptop

Then in your ~/.gitconfig:

[user]
    email = {{EMAIL}}
    name  = John Doe

System variables ({{HOSTNAME}}, {{USER}}, {{SHELL}}, etc.) are auto-populated.

Project Status

Development

git clone https://github.com/BeshoyEhab/dot-man.git
cd dot-man
uv sync --extra dev
pre-commit install

# Run tests
uv run pytest tests/ -v

# Run full quality gate
uv run black dot_man/ tests/
uv run ruff check dot_man/ tests/
uv run mypy dot_man/ --ignore-missing-imports
uv run pytest tests/ --cov=dot_man --cov-report=term-missing

See CONTRIBUTING.md and DEVELOPMENT.md for full guides.

Roadmap

• 90%+ test coverage (every module)
• Full documentation site (mkdocs)
• Symlink mode
• dot-man watch — auto-sync on file change
• Deploy rollback (transaction-style)
• Plugin system

See docs/roadmap.md for the full roadmap.

Contributing

Pull requests are welcome. Please read CONTRIBUTING.md first.

All contributions must pass the pre-push quality checklist: black, ruff, mypy, and all tests.

License

MIT © Bishoy Ehab & ZVAXEROWS