Skip to content

Projects & repos

A project is one piece of work, like “My feature”: a directory under ~/.local-review/projects/<slug>/ with a project.yaml in it. It spans one or more repos, and for each one names a commit range: from the merge-base with a base up to a branch head. Those commits are split into PR stacks, and each commit is reviewed as a PR.

~/.local-review/projects/my-feature/project.yaml
title: My feature
repos:
- path: ~/code/my-service
branch: me/my-feature # the range ends at this branch's head
base: origin/main # and starts (exclusive) at its merge-base with this
- path: ~/code/my-client # a second repo, with its own range and stacks
branch: me/my-feature

local-review init my-feature creates the file from a commented example. Every field is on project.yaml.

  • The directory name is the project’s slug, used in URLs: /<slug> is the project page, /<slug>/<repo>/stacks/<ref> a stack page, and /<slug>/<repo>/<sha> one of its PRs.
  • The header shows the project’s title, with a project switcher (its first item, All projects, is the root page). A project whose PRs have all landed is archived automatically, into a collapsed Archived section at the bottom of the switcher and of the root page.
  • An optional after: <slug> makes it a linked project: it builds on that one, and a repo they share starts where that project’s range ends.
  • An optional description: is the project intro: one or two paragraphs of context that go at the top of every full PR body. See Editing PR titles & descriptions.
  • / is the root page: every project as a card, most recently active first.

Each repo is a local clone, which Local Review only ever reads (read-only guarantee).

  • The end is branch: (its head) or to: (a sha or ref, inclusive).
  • The start is merge-base(base, end), exclusive, with base: defaulting to origin/HEAD, else main, else master; or from:, the first commit included.
  • The name (name:, default the directory name) is used in URLs and as the directory name for the repo’s prs and comment files.

Each commit is diffed against its first parent with rename detection (-M), so a base that has moved on doesn’t matter: you see each commit’s own change. (Landed PRs are diffed differently.)

Nothing needs a restart:

  • each repo’s branches (its range end, its base and every other branch) are polled every 2 seconds, so a new commit, an amend, a rebase, the base moving or a new branch shows up on its own. The poll is cheap: it looks at the files git keeps refs in (HEAD, packed-refs, refs/, and reftable/ if the repo uses it) and only runs git when one of them has changed (and every 10 minutes regardless, as a safety net), so an idle repo costs no git processes at all. It only runs while a browser has a page open; with none, a request checks for itself;
  • every file under ~/.local-review/projects/ is watched, and edits push a refresh to the browser. What the server works out from them is kept only while the files are unchanged, so the next request always reads an edit.

A missing repo or branch shows as an error in the sidebar (a missing branch isn’t one in a repo with landed PRs), and stack problems as a warning. See Errors and warnings.

A change that touches an API, its client and the infra is one piece of work, reviewed in one place: list each repo in the project, each with its own branch and stacks. The sidebar has a collapsible section per repo, j/k walk every PR across all of them, and the stack picture can draw the whole project.

The sidebar sections for three repos (orchard-sdk, orchard-web and orchard-infra), each headed by its branch, each with its own coloured stacks
One project, several repos: each has its own section in the sidebar, its own branch and its own stacks. (The repos are from the fictional demo project.)