Skip to content

Dotfile¶

The .bluefox YAML file tracks the project version and which files the upgrade engine manages.

Structure¶

cli_version: "0.2.0"
generated_at: "2026-03-15"
files:
  Dockerfile:
    managed: full
    hash: "sha256:abc123..."
  app/__init__.py:
    managed: sections
    markers:
      - bluefox:routers
    hash: "sha256:def456..."
  pyproject.toml:
    managed: structured

Models¶

DotBluefox¶

class DotBluefox(BaseModel):
    cli_version: str
    generated_at: str
    upgraded_at: str | None = None
    files: dict[str, TrackedFile] = {}

TrackedFile¶

class TrackedFile(BaseModel):
    managed: str  # "full", "sections", "structured"
    hash: str | None = None
    markers: list[str] | None = None

Functions¶

`create_dotfile(project_dir, cli_version, tracked_files) → DotBluefox`¶

Creates a new .bluefox dotfile, computing hashes for full and sections tracked files.

tracked = dict([
    full_tracked("Dockerfile"),
    sections_tracked("app/__init__.py", ["bluefox:routers"]),
    structured_tracked("pyproject.toml"),
])
dotfile = create_dotfile(project_dir, "0.1.0", tracked)

`load_dotfile(project_dir) → DotBluefox`¶

Loads and parses the .bluefox file from a project directory.

`save_dotfile(project_dir, dotfile)`¶

Writes the dotfile back to disk as YAML.

Convenience helpers¶

Function	Returns	Description
`full_tracked(path)`	`tuple[str, TrackedFile]`	Track entire file with hash
`sections_tracked(path, markers)`	`tuple[str, TrackedFile]`	Track specific marker sections
`structured_tracked(path)`	`tuple[str, TrackedFile]`	Track structured fields (no hash)