# How to Set Up a Dotfiles Bootstrapping Script with Dotbot

> Automate your dev environment setup with a dotfiles bootstrapping script. Learn how to clone your repo symlink files and run commands easily with Dotbot.

- Repository: [Ivan Smirnov/dotfiles](https://github.com/issmirnov/dotfiles)
- Tags: how-to-guide
- Published: 2026-03-04

---

**A dotfiles bootstrapping script automates the deployment of your development environment by cloning your repository, creating symlinks, and running setup commands with a single command.**

Setting up a new machine typically involves hours of manual configuration. A well-crafted dotfiles bootstrapping script eliminates this friction by declaratively defining your entire environment. The `issmirnov/dotfiles` repository demonstrates a production-ready approach using Dotbot, a lightweight Python-based tool that turns complex setup procedures into reproducible, idempotent operations.

## What Is a Dotfiles Bootstrapping Script?

A dotfiles bootstrapping script is an executable entry point that orchestrates the installation of your configuration files, shell environments, and development tools. Rather than manually copying files or creating symlinks by hand, the script automates:

- **Symlink creation** linking files from your repository to your home directory (e.g., `~/.zshrc` → `zsh/zshrc`)
- **Dependency installation** such as shell plugins, font caches, or utility binaries
- **OS-specific customization** applying different configurations for Linux versus macOS
- **Directory creation** for organizing logs, caches, or custom binaries

The `issmirnov/dotfiles` repository implements this through a top-level `install` script that wraps Dotbot, providing a declarative YAML-based configuration system.

## How the Dotfiles Bootstrapping Script Works

### The Bootstrap Workflow

The bootstrapping process in `issmirnov/dotfiles` follows a deterministic four-step workflow:

1. **Clone the repository** with submodules to obtain the dotfiles, Dotbot engine, and helper scripts
2. **Execute the `install` script** which updates the `dotbot` submodule and invokes the engine
3. **Dotbot processes configurations** reading [`default.conf.yaml`](https://github.com/issmirnov/dotfiles/blob/main/default.conf.yaml) and optionally OS-specific files ([`ubuntu.conf.yaml`](https://github.com/issmirnov/dotfiles/blob/main/ubuntu.conf.yaml) or [`osx.conf.yaml`](https://github.com/issmirnov/dotfiles/blob/main/osx.conf.yaml))
4. **Apply changes** including symlink creation, shell command execution, and directory setup

### Key Components of the Bootstrapping System

| Component | Purpose | Location |
|-----------|---------|----------|
| `install` | Main entry point that initializes Dotbot and selects OS-specific configs | [`install`](https://github.com/issmirnov/dotfiles/blob/master/install) |
| `minstall` | Minimal installer for Zsh-only environments | [`minstall`](https://github.com/issmirnov/dotfiles/blob/master/minstall) |
| `dotbot` | Python-based engine submodule that executes YAML configurations | [`dotbot/`](https://github.com/issmirnov/dotfiles/tree/master/dotbot) |
| [`default.conf.yaml`](https://github.com/issmirnov/dotfiles/blob/main/default.conf.yaml) | Core configuration defining universal links and shell commands | [[`default.conf.yaml`](https://github.com/issmirnov/dotfiles/blob/main/default.conf.yaml)](https://github.com/issmirnov/dotfiles/blob/master/default.conf.yaml) |
| [`ubuntu.conf.yaml`](https://github.com/issmirnov/dotfiles/blob/main/ubuntu.conf.yaml) | Linux-specific extensions for Ubuntu systems | [[`ubuntu.conf.yaml`](https://github.com/issmirnov/dotfiles/blob/main/ubuntu.conf.yaml)](https://github.com/issmirnov/dotfiles/blob/master/ubuntu.conf.yaml) |
| [`osx.conf.yaml`](https://github.com/issmirnov/dotfiles/blob/main/osx.conf.yaml) | macOS-specific configuration additions | [[`osx.conf.yaml`](https://github.com/issmirnov/dotfiles/blob/main/osx.conf.yaml)](https://github.com/issmirnov/dotfiles/blob/master/osx.conf.yaml) |
| [`minimal.conf.yaml`](https://github.com/issmirnov/dotfiles/blob/main/minimal.conf.yaml) | Stripped-down config for Zsh-only bootstrapping | [[`minimal.conf.yaml`](https://github.com/issmirnov/dotfiles/blob/main/minimal.conf.yaml)](https://github.com/issmirnov/dotfiles/blob/master/minimal.conf.yaml) |
| `zsh/setup` | Helper script ensuring Zsh installation and default shell configuration | [`zsh/setup`](https://github.com/issmirnov/dotfiles/blob/master/zsh/setup) |

## Setting Up Your Own Dotfiles Bootstrapping Script

### Step 1: Clone the Repository

Begin by cloning the repository recursively to include the Dotbot submodule:

```bash
git clone --recursive https://github.com/issmirnov/dotfiles.git ~/.dotfiles
cd ~/.dotfiles

```

The `--recursive` flag ensures the `dotbot` directory is populated with the actual tool rather than an empty reference.

### Step 2: Run the Full Bootstrap

Execute the main bootstrapping script to deploy the complete environment:

```bash
./install

```

This script performs several operations:

1. Updates the `dotbot` submodule to the latest version
2. Invokes Dotbot with [`default.conf.yaml`](https://github.com/issmirnov/dotfiles/blob/main/default.conf.yaml) to create symlinks for Vim, Zsh, tmux, and Git configurations
3. Detects your operating system and applies [`ubuntu.conf.yaml`](https://github.com/issmirnov/dotfiles/blob/main/ubuntu.conf.yaml) for Linux or [`osx.conf.yaml`](https://github.com/issmirnov/dotfiles/blob/main/osx.conf.yaml) for macOS
4. Runs shell commands to install plugins, build caches, and configure the Zsh environment via `zsh/setup`

### Step 3: Run the Minimal Zsh-Only Bootstrap

For servers or containers where you only need the Zsh shell configuration without additional tools:

```bash
./minstall

```

This executes Dotbot with [`minimal.conf.yaml`](https://github.com/issmirnov/dotfiles/blob/main/minimal.conf.yaml), creating only the essential symlinks:

- `~/.zshrc` pointing to `zsh/zshrc`
- Git hook templates in `.git/hooks/`

## Customizing the Dotfiles Bootstrapping Configuration

### Adding New Symlinks

To extend your bootstrapping script with new configuration files, edit the appropriate YAML configuration (typically [`default.conf.yaml`](https://github.com/issmirnov/dotfiles/blob/main/default.conf.yaml)) and add entries to the `link` section:

```yaml
- link:
    ~/.config/nvim:
      path: config/nvim
      create: true
    ~/.bin/custom-script:
      path: scripts/custom-script.sh
      create: true

```

The `create: true` directive ensures parent directories exist before creating the symlink. After modifying the configuration, run `./install` to apply changes.

### Running Manual Dotbot Commands

For debugging or testing specific configurations without running the full bootstrap:

```bash

# Re-apply only the Ubuntu-specific configuration

./dotbot/bin/dotbot -d "$(pwd)" -c "ubuntu.conf.yaml"

```

This invokes the Dotbot binary directly with the `-d` flag specifying the base directory and `-c` specifying the configuration file. Use this approach when developing new OS-specific extensions or troubleshooting symlink issues.

## Summary

- **Dotbot powers the bootstrapping script** in `issmirnov/dotfiles`, providing a declarative YAML interface for managing symlinks and shell commands.
- **The `install` script** serves as the universal entry point, detecting your operating system and applying both default and OS-specific configurations automatically.
- **Idempotent execution** ensures you can run the bootstrapping script multiple times safely, with Dotbot's `relink` and `force` options handling existing files gracefully.
- **Modular configuration files** ([`default.conf.yaml`](https://github.com/issmirnov/dotfiles/blob/main/default.conf.yaml), [`ubuntu.conf.yaml`](https://github.com/issmirnov/dotfiles/blob/main/ubuntu.conf.yaml), [`osx.conf.yaml`](https://github.com/issmirnov/dotfiles/blob/main/osx.conf.yaml), [`minimal.conf.yaml`](https://github.com/issmirnov/dotfiles/blob/main/minimal.conf.yaml)) allow you to maintain platform-specific customizations without duplicating common settings.

## Frequently Asked Questions

### What is Dotbot and why use it for dotfiles bootstrapping?

Dotbot is a lightweight Python tool designed specifically for bootstrapping dotfiles repositories. It reads YAML configuration files and executes commands to create symlinks, run shell commands, and clean stale files. Using Dotbot for your bootstrapping script eliminates the need to write complex shell logic for file linking, handles edge cases like existing files automatically, and provides a declarative format that makes your configuration self-documenting and easy to maintain.

### How do I make the dotfiles bootstrapping script work on both Linux and macOS?

The `issmirnov/dotfiles` repository handles cross-platform support through OS detection in the main `install` script. The script checks the `$OSTYPE` environment variable to determine the platform: if it contains `linux-gnu`, it applies [`ubuntu.conf.yaml`](https://github.com/issmirnov/dotfiles/blob/main/ubuntu.conf.yaml); if it matches `darwin*`, it applies [`osx.conf.yaml`](https://github.com/issmirnov/dotfiles/blob/main/osx.conf.yaml). To implement this in your own bootstrapping script, structure your configurations into a default file for universal settings and separate OS-specific YAML files for platform-dependent links or commands, then use conditional logic in your install script to invoke Dotbot with the appropriate configuration files.

### Can I run the dotfiles bootstrapping script multiple times safely?

Yes, the bootstrapping script is designed to be idempotent and safe to run repeatedly. Dotbot supports this through configuration options like `relink: true` and `force: true` in the YAML defaults section. When `relink` is enabled, Dotbot will remove existing symlinks that point to the wrong location and recreate them correctly. The `force` option allows overwriting existing files if necessary. Additionally, the `clean` directive in the configuration removes stale symlinks from previous runs, ensuring your environment converges to the desired state regardless of how many times you execute the script.

### How do I add a new configuration file to the bootstrapping process?

To add a new dotfile to your bootstrapping script, edit the appropriate YAML configuration file (typically [`default.conf.yaml`](https://github.com/issmirnov/dotfiles/blob/main/default.conf.yaml) for universal files or an OS-specific file for platform-dependent configurations). Add an entry to the `link` section specifying the target path in your home directory and the source path relative to the repository root. For example, to link a new Neovim configuration, you would add `~/.config/nvim: config/nvim` to the links section. If the parent directory might not exist, include `create: true` to ensure Dotbot creates the necessary directory structure. After saving the configuration, run `./install` to apply the changes and create the new symlink.