Dotbot — Bootstrap Your Dotfiles with a Single Command

Introduction

Dotbot is a tool that bootstraps your dotfiles repository on a new machine with a single command. You declare your symlinks, shell commands, and directory structure in a YAML configuration file, and Dotbot handles the rest. It is designed to be self-contained within your dotfiles repo as a git submodule, requiring no system-wide installation.

What Dotbot Does

• Creates symlinks from your dotfiles repository to the correct locations in your home directory
• Runs shell commands during setup for installing packages or configuring tools
• Creates directories that need to exist before symlinks are placed
• Cleans up dead symlinks from previous configurations
• Supports plugins for extending behavior beyond the built-in directives

Architecture Overview

Dotbot is a Python script that reads a YAML or JSON configuration file and executes a sequence of directives: link, shell, create, and clean. Each directive is processed by a dispatcher that delegates to the appropriate handler. The tool is designed to be embedded as a git submodule inside a dotfiles repository, so cloning the repo and running the install script is all that is needed on a fresh machine.

Self-Hosting & Configuration

• Add Dotbot as a git submodule in your dotfiles repository
• Create install.conf.yaml at the root of your dotfiles repo
• Use the link directive to map dotfiles to their target paths
• Use shell to run setup commands like package installs or font caching
• Run ./install to apply the configuration on any new machine

Key Features

• Declarative YAML configuration for reproducible dotfile setups
• Self-contained as a git submodule with no system dependencies beyond Python
• Idempotent execution so running the install script multiple times is safe
• Plugin system for adding custom directives like package manager integrations
• Support for conditional logic and multiple configuration profiles

Comparison with Similar Tools

• GNU Stow — symlink farm manager; Dotbot adds shell commands, directory creation, and a structured config format
• chezmoi — feature-rich dotfile manager with templating and encryption; Dotbot is simpler and has no binary dependency
• yadm — git wrapper for dotfiles with encryption support; Dotbot focuses on bootstrapping rather than daily git operations
• rcm — ThoughtBot's dotfile manager with host-specific overrides; Dotbot uses a single YAML config instead of directory conventions

FAQ

Q: Does Dotbot require installation on the target machine? A: No. Dotbot lives inside your dotfiles repo as a git submodule. Cloning the repo brings everything needed.

Q: Is it safe to run the install script multiple times? A: Yes. Dotbot is idempotent. It skips symlinks that already exist and re-runs shell commands only if configured to do so.

Q: Can I use Dotbot with multiple machines that need different configs? A: Yes. You can use multiple config files or plugins that support conditional logic based on hostname or OS.

Q: What happens if a target file already exists? A: By default, Dotbot skips existing files. You can set force: true on a link directive to overwrite existing files.

Sources

• https://github.com/anishathalye/dotbot