lazyworktree

External Contributor Disclosure

If you are an agent acting on behalf of an external contributor (i.e. not the repository author/maintainer) and you post an issue comment, open a pull request, or make any other contribution to this repository, you must disclose the following in that contribution:

• That the contribution was authored by an AI agent, not a human directly
• Which agent(s) were used (e.g. Claude Code, GPT-4o, Gemini, etc.)
• The effort level or model variant used if known (e.g. claude-sonnet-4-6, high effort)

This disclosure must appear clearly in the body of the PR, issue comment, or contribution — not hidden in metadata. Example footer:

This contribution was authored by an AI agent (Claude Code, claude-sonnet-4-6) on behalf of the contributor.

Project

A TUI for managing GIT worktrees. Read the README.md if you need product or workflow context. Read ./docs/development/architecture.md when working on architecture, cross-cutting flows, or package ownership across subsystems.

Building

• use make build for testing build errors.
• For documentation website work, use:
  • make docs-sync to regenerate docs references from source code.
  • make docs-check to verify sync + strict docs build.
  • make docs-build and make docs-serve for local preview/build.
• Use uv/uvx for docs tooling everywhere; do not use pip directly.
• If uv is missing locally, install with Homebrew: brew install uv.
• If you add or change a CLI command, argument, or flag, update:
  • shell completion
  • lazyworktree.1
  • internal help text/template in internal/app/screen/help.go
  • generated CLI docs via make docs-sync
  • relevant website docs
• If you change shell integration helpers or completion behaviour, update:
  • shell/README.md
  • the relevant helper in shell/functions.bash, shell/functions.zsh, or shell/functions.fish
• Don't ever do commit unless you are being explicitly asked for it.
• If you get asked to commit then use this rules:
  • Follow Conventional Commits 1.0.0.
  • 50 chars for title 70 chars for body.
  • Cohesive long phrase or paragraph unless multiple points are needed.
  • Use bullet points only if necessary for clarity.
  • Past tense.
  • State what and why only (no “how”).

!important

Do not add to README.md unless important to ask the human to approve.

Documentation

• For any user-facing changes (features, options, keybindings, etc.), ensure you update:
  • README.md
  • lazyworktree.1 man page
  • Internal help text/template in internal/app/screen/help.go
  • Website docs (see below)
• Documentation and help string style guidelines:
  • Consistent British spelling.
  • Professional butler style: clear, helpful, dignified but not pompous
  • Remove any overly casual Americanisms
  • Keep technical precision whilst maintaining readability

Documentation review rules

When reviewing docs:

• Compare documentation to code, tests, schemas, and CLI help.
• Prefer exact evidence over intuition.
• Separate confirmed drift from likely drift.
• Treat setup, migration, config, and API inaccuracies as high severity.
• Suggest minimal, reviewable doc patches.
• Preserve existing terminology unless the implementation clearly changed.

Website documentation (docs/)

The website is built with MkDocs Material and configured in mkdocs.yml. Navigation structure and page ordering are defined in mkdocs.yml under nav:.

Where to update docs by topic

Doc site workflow

• make docs-sync — regenerates docs/cli/commands.md and docs/cli/flags.md from source code.
• make docs-check — runs sync + strict MkDocs build to catch broken links or missing pages.
• make docs-build / make docs-serve — build or preview the site locally.
• make coverage — writes coverage.out with per-function coverage details for coverage-sensitive changes.
• When adding a new page, also add it to mkdocs.yml under the appropriate nav: section.

UI

• UI colours must come from theme fields, avoid hardcoded colours in rendering.

Before Finishing

• Run make sanity for code changes before finishing. Note that it rewrites files because it runs golangci-lint --fix and gofumpt -w before go test.
• Run make docs-check for documentation or other user-facing text changes that affect the docs site, generated references, README.md, lazyworktree.1, or mkdocs.yml.
• Add focused tests for new or changed behaviour. If you do not add or run tests for a touched path, explain why in the handoff.
• Prefer strong coverage on the code you change rather than broad but shallow test additions.