Build and install standalone#

This runbook explains how to install stable and editable dotfiles CLI entrypoints.

Repo installer entrypoint#

Install orchestration is repo-only and is not exposed as a dotfiles subcommand.

  • Preferred entrypoints are make install and make install-dev.

  • The underlying script is python/scripts/install_tool.py.

  • This avoids self-reinstall behavior from an already-installed dotfiles executable.

Build artifacts#

Run from repository root:

$ uv build --project python

This writes artifacts to python/dist/:

  • dotfiles-<version>.tar.gz

  • dotfiles-<version>-py3-none-any.whl

Install stable entrypoint#

Run from repository root on master with a clean worktree:

$ make install

This installs dotfiles via uv tool install ..

The following should work from any directory after this:

$ dotfiles --help

Install editable dev entrypoint#

Run from repository root on our current branch:

$ make install-dev

This installs editable dotfiles via uv tool install . --editable into isolated uv tool directories and sets up a wrapper script at ~/.local/bin/dotfiles-dev.

The following should work from any directory after this:

$ dotfiles-dev --help

This should reflect changes in the code without needing to re-install --dev.

Install mode behavior#

  • default mode requires clean worktree on branch master

  • default mode uses --dry-run unless --no-dry-run

  • --dev skips clean-worktree and branch checks

  • --dev defaults to --no-dry-run

Custom install path isolation#

When the repo installer uses a custom non-default install path (with --dirty-install-path), the tool install also uses an isolated uv data directory.

That uv data directory is derived from a short SHA digest of the normalized install path, so each custom install path gets a stable, unique uv tool home and does not overwrite the default ~/.local/share/uv/tools environment.

Relevant changelogs#