# Dotbot — Bootstrap Your Dotfiles with a Single Command

> A tool for bootstrapping and managing dotfiles using a declarative YAML configuration that creates symlinks, runs shell commands, and handles setup automatically.

## Install

Save as a script file and run:

# Dotbot — Bootstrap Your Dotfiles with a Single Command

## Quick Use
```bash
git clone https://github.com/your-username/dotfiles.git
cd dotfiles
# Add dotbot as a submodule
git submodule add https://github.com/anishathalye/dotbot
# Create install.conf.yaml and run:
./install
```

## 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

---
Source: https://tokrepo.com/en/workflows/asset-54e9de01
Author: Script Depot