Documentation

Installation

Dotman is built with Nim and can be installed via several methods.

Install the binary (fastest method)

curl -fsSL gabrielcapilla.github.io/install | bash -s dotman

Install via Nimble

Requirements: Nim 2.2.6 or later

nimble install https://github.com/gabrielcapilla/dotman.git@#head

Install from Source

Clone the repository and build the binary:

git clone https://github.com/gabrielcapilla/dotman.git
cd dotman
nimble build
nimble install

Quick Start

Once installed, initialize dotman and start managing your configuration files in minutes.

# Initialize dotman (creates ~/.dotfiles/main)
dotman init

# Add your nvim config (moves file and creates symlink)

dotman set ~/.config/nvim

# Check status of your configs

dotman status

Directory Structure

By default, dotman uses ~/.dotfiles as the root directory. The structure is organized by categories that map to specific system locations:

~/.dotfiles/
└── main/ # Default profile
├── config/
├── share/
├── home/
└── bin/

Categories

Dotman automatically categorizes files based on their destination path. Each category maps to a specific system location:

  • home/ → ~/
  • config/ → ~/.config/
  • bin/ → ~/.local/bin/
  • share/ → ~/.local/share/

When adding files, dotman automatically links them in the correct path. For example:

# config/nvim → ~/.config/nvim
dotman add nvim

# share/fonts → ~/.local/share/fonts

dotman add fonts

Profiles

Profiles allow you to manage different configurations for different environments (e.g., experimental, laptop, main). The main profile is created by default and cannot be deleted.

# Create a new profile
dotman make experimental

# Clone an existing profile

dotman clone main laptop

# List all profiles

dotman list

# Delete a profile (main cannot be deleted)

dotman --delete-profile experimental

Validation

Dotman automatically validates symlinks before creating them to prevent conflicts and data loss:

  • Checks for existing files at the target location
  • Detects conflicts with other profiles
  • Validates directory structure
  • Reports broken or orphaned symlinks

Profile Commands

init

Initialize dotman directory structure in ~/.dotfiles.

dotman init
dotman -i

make

Create a new profile with the specified name.

dotman make <name>
dotman -m <name>

clone

Clone an existing profile to create a new one.

dotman clone <source> <destination>
dotman -c <source> <destination>

list

List all available profiles.

dotman list
dotman -l

Manage Commands

set

Move a file or directory from the system to the current profile and create a symlink in its place.

dotman set <file>
dotman -s <file>

set vs add: Use set to move existing files from your system into dotman management. Use add when files already exist in the profile and you just want to create symlinks.

unset

Remove a symlink and restore the original file or directory from the profile back to its system location.

dotman unset <file>
dotman -u <file>

Status Commands

status

Display the status of all files in the current main profile.

dotman status

Options:

  • --category <cat> - Filter by category (config, share, home, local, bin)
  • --linked - Show only linked files
  • --not-linked - Show only unlinked files
  • --conflicts - Show only conflicting files
  • --other - Show other profile files
  • --verbose, -v - Show detailed information
  • --profile <name> - Use specific profile
  • --ascii - Use ASCII characters in table
dotman status --category config
dotman status --linked --verbose
dotman status --conflicts
dotman status --profile work --ascii

Sync Commands

push

Link all files from the profile to the system.

dotman push <profile>

pull

Remove all symbolic links from the selected profile.

dotman pull <profile>

Tips & Best Practices

Use Git with Dotman

Version control your dotfiles with Git by initializing a repository in ~/.dotfiles:

cd ~/.dotfiles
git init
git add .
git commit -m "Initial commit"

Handle Conflicts

If dotman detects a conflict, resolve it by:

  • Moving or deleting the conflicting file manually
  • Using --conflicts flag to identify issues
  • Checking which profile manages the file with --other flag

Push/Pull Workflows

Switching configurations cleanly:

# Clone your main profile and create an experimental profile
dotman clone main experimental

# Remove all symbolic links from the main profile

dotman pull main

# Link all files from the experimental profile to the system

dotman push experimental

Examples

Neovim Configuration

# Move nvim config to profile and link it
dotman set ~/.config/nvim

# Check status of config category

dotman status --category config

# View detailed breakdown by subdirectory

dotman status --verbose

Multi-Profile Workflow

# Create profiles for different environments
dotman make exp
dotman make laptop

# Add experimental-specific config to experimental profile

dotman --profile exp set ~/.config/alacritty

# Check experimental profile status

dotman status --profile exp

# Remove a symlink and restore the original file or directory

dotman --profile exp unset alacritty