Source root resolution module#

python/src/dotfiles/paths.py resolves the dotfiles repository root used by CLI commands and Sphinx helper extensions.

High-level structure#

paths.py
|-- constants
|   |-- PROJECT_MARKERS
|   |-- CONFIG_SECTION_PATHS / CONFIG_KEY_GIT_ROOT
|   `-- CHEZMOI_DOTFILES_PATH_OVERRIDE
|-- IO boundary
|   |-- SourceRootResolutionIO
|   `-- RealSourceRootResolutionIO
|-- tracing and context
|   |-- DiscoveryTrace
|   `-- ResolverContext
|-- strategy helpers
|   |-- _resolve_direct_project_root
|   |-- _resolve_from_runtime_package_path
|   |-- _config_git_root
|   `-- _resolve_from_chezmoi_source_path
`-- public API
    |-- package_config_path
    |-- set_source_root_override
    |-- resolve_project_dir_with_io
    |-- show_project_dir_discovery
    `-- resolve_project_dir

  • Keeps source-root resolution in one module used by CLI and docs helpers.

  • Separates filesystem and process access behind SourceRootResolutionIO.

  • Uses DiscoveryTrace to record and optionally stream strategy attempts.

  • Raises SourceRootResolutionError with ordered strategy output on failure.

Resolution order#

  1. --source-root (set through set_source_root_override).

  2. Runtime package path ancestry (walk up from package/config location).

  3. [paths].git_root in dotfiles-config.ini.

  4. chezmoi source-path walk-up to project markers.

  5. CHEZMOI_DOTFILES_PATH_OVERRIDE.

If --source-root is provided and invalid, resolution stops immediately and does not continue to fallback strategies.

Runtime behavior#

  • uv run --project python dotfiles ... resolves to the active checkout when the package path is inside that checkout.

  • Installed entrypoints can still resolve through configured git_root and other fallbacks when package ancestry is not a repository root.

  • Sphinx extension hooks call resolve_project_dir and reuse the same logic.

Cache and diagnostics#

  • resolve_project_dir is memoized with @lru_cache(maxsize=1).

  • set_source_root_override clears the cache so subsequent commands use the latest override.

  • show_project_dir_discovery emits each trace line for --show-source-discovery.

Relevant changelogs#