dotbot

To install your dotfiles on a new machine or update an existing installation, use the install shim (or install.ps1 on Windows) located in your dotfiles directory.

New Installation:

git clone <your-dotfiles-repo-url> ~/.dotfiles
cd ~/.dotfiles
./install

Update Existing Installation:

cd ~/.dotfiles
git pull
./install

If you manage your dotfiles with Git, you can bundle Dotbot as a submodule within your repository. This locks Dotbot to a specific version. After adding the submodule, copy the provided install shim to your root directory.

Steps:

1. Navigate to your dotfiles directory.
2. Initialize the repository if necessary.
3. Add the Dotbot submodule.
4. Configure Git to ignore dirty commits in the submodule.
5. Copy the installation shim.

cd ~/.dotfiles # replace with the path to your dotfiles
git init # initialize repository if needed
git submodule add https://github.com/anishathalye/dotbot
git config -f .gitmodules submodule.dotbot.ignore dirty # ignore dirty commits in the submodule
cp dotbot/tools/git-submodule/install .

To perform static type checking on the Dotbot codebase, use the following Hatch command which invokes mypy.

hatch run types:check

Dotbot uses Ruff for formatting and linting.

• To automatically apply safe fixes to your code, run hatch fmt.
• To check if files need formatting without making any modifications, run hatch fmt --check.

Dotbot supports custom directives via plugins. Plugins must be subclasses of dotbot.Plugin and implement can_handle() and handle(). To support dry-runs, they should declare supports_dry_run = True and use Context.dry_run().

Loading via Configuration: Specify an array of files or directories (containing plugins) under the plugins key. Paths are relative to the base directory.

Loading via Command Line: Use the --plugin flag. This can be used multiple times. Paths are relative to the working directory where dotbot is invoked.

# Via config
- plugins:
    - dotbot-plugins/dotbot-brew/
    - dotbot-plugins/custom_plugin.py

# Via CLI
dotbot --plugin dotbot-plugins/dotbot-brew/ --plugin dotbot-plugins/custom_plugin.py ...

If you use Mercurial, you can add Dotbot as a subrepo by creating a .hgsub file and cloning the Dotbot repository into your dotfiles directory.

cd ~/.dotfiles # replace with the path to your dotfiles
hg init # initialize repository if needed
echo "dotbot = [git]https://github.com/anishathalye/dotbot" > .hgsub
hg add .hgsub
git clone https://github.com/anishathalye/dotbot
cp dotbot/tools/hg-subrepo/install .

Dotbot uses Hatch to manage testing. You can run the full test suite on your local machine using the hatch test command.

Supported Hatch test options:

• -c: Measure test coverage.
• -a: Test against a matrix of Python versions.
• Append a specific test path (e.g., tests/test_shell.py::test_name) to run a single test.

Because Dotbot interacts with the filesystem and executes shell commands, you can run tests inside an isolated Docker container to prevent side effects on your host machine.

1. Start a Python container and mount the current directory: docker run -it --rm -v "${PWD}:/dotbot" -w /dotbot python:3.13-bookworm /bin/bash
2. Inside the container, install Hatch: pip install hatch.
3. Run the tests using hatch test.

Use Hatch to manage the packaging lifecycle:

• Build artifacts: Use hatch build to create source distributions (sdist) and built distributions (wheel).
• Publish: Use hatch publish to upload build artifacts to PyPI.

You can install Dotbot as a standalone command-line program using pip or uv. Once installed, you can invoke it using the dotbot command and specify your configuration file with the -c flag.

To install using uv:

uv tool install dotbot

To run Dotbot with a specific configuration:

dotbot -c <path to configuration file>

The create directive specifies empty directories to be created. This is useful for setting up folder structures required by applications.

Formats:

• An array of directory paths.
• A dictionary for extended configuration.

Parameters:

• mode: The file mode for the leaf directory (default: 0777). Behavior is platform-dependent and follows Python's os.mkdir logic (on Unix, it is masked by the current umask).

- create:
    - ~/downloads
    - ~/.vim/undo-history
- create:
    ~/.ssh:
      mode: 0700
    ~/projects: