repo¶

Register repositories, schedule their analysis, and manage the shared repository cache: list cached repos, clear a clone, clear a stuck lock, and maintain per-project overrides.

repo
  Manage the shared repository cache (clones, coverage, locks, per-repo config)

Subcommand	Description
`repo add <url>`	Register a repo — a worker clones it and discovers its Go projects
`repo show <url>`	Show registration status and discovered projects
`repo analyze <url>`	Schedule analysis — all projects, or one with `--project`
`repo check-updates`	Probe registered repos for new commits; rescan the ones that moved
`repo list`	List cached repos with commit, coverage profiles, and lock state
`repo delete <url>`	Wipe a repo's clone and coverage profiles (force a fresh clone)
`repo unlock <url>`	Inspect a lock; clear it if the owner is dead
`repo config set <url>`	Set per-project overrides
`repo config get <url>`	Show per-project overrides
`repo config rm <url>`	Remove per-project overrides

repo add¶

Register a repository for analysis. The command returns as soon as the repo is recorded with status registering; a worker then clones it, discovers its Go projects, and flips the status to ready (or error, with the reason visible via repo show).

go-crap-tracker repo add https://github.com/org/monorepo
# registered https://github.com/org/monorepo (status=registering); a worker will clone it and discover its Go projects

Local filesystem paths are accepted and keep their case, so case-sensitive checkouts work:

go-crap-tracker repo add /home/me/src/github.com/org/MyRepo

repo show¶

Show a registered repo's status, commit, and discovered projects.

go-crap-tracker repo show https://github.com/org/monorepo
# repo:      https://github.com/org/monorepo
# status:    ready
# reason:
# commit:    d55453cffcdd
# profiled:  2026-08-21T14:00:00-03:00
# projects:  tools, tsc

# as JSON
go-crap-tracker repo show https://github.com/org/monorepo --json

Flag	Description
`--json`	Emit the repo record as JSON (includes `Profile.projects`, `Profile.has_go_work`, …).

repo analyze¶

Schedule analysis of a registered repo — one scan task per discovered project, or a single project with --project.

# all projects (default)
go-crap-tracker repo analyze https://github.com/org/monorepo
# queued task task-… project=tools ref=""
# queued task task-… project=tsc ref=""

# one project only
go-crap-tracker repo analyze https://github.com/org/monorepo --project tsc

Flag	Description
`--project`	Analyze only this project (subdirectory); default is all discovered projects.

repo check-updates¶

Check every registered repo (status ready) for new commits and schedule a rescan for the ones that moved. Intended to be run periodically from cron so the published reports track upstream without manual repo analyze calls.

The check is deliberately cheap and read-only with respect to the shared cache: it runs one git ls-remote per tracked ref (no clone, no fetch, no lock) and compares the live commit against the commit of the project's latest successful analysis. A scan that failed at the new commit does not count as analyzed, so the repo stays eligible for another attempt. Unchanged repos cost one lightweight request per ref and touch nothing on disk.

# report only, schedule nothing
go-crap-tracker repo check-updates
# REPO                   PROJECT  REF   REMOTE       ANALYZED     RESULT
# github.com/org/monorepo (root)  main   bbb222…      aaa111…      OUTDATED
# github.com/org/monorepo tsc     main   bbb222…      bbb222…      up to date
#
# 1 moved, 1 up to date, 0 skipped

# report + schedule rescans for repos that moved
go-crap-tracker repo check-updates --schedule

# as JSON (one object per project)
go-crap-tracker repo check-updates --json

Behavior details:

Per-project refs are honored. Each project is probed with its own tracked ref (project config ref, falling back to the repo-root ref, mirroring repo analyze), and distinct refs are probed once each. A project pinned to a stable ref does not trigger rescans on its own.
A rescan is whole-repo. When any project of a repo moved, the repo is scheduled through the normal analyzer (one task per project). Projects whose ref did not move are rescanned at the same commit, which is cheap — their coverage profile is reused and go test is skipped.
Probe failures skip, never abort. A repo whose ls-remote fails (network blip, ref gone) is reported as SKIP … and left alone; the run continues with the other repos.

Run it from cron, e.g. every 30 minutes:

*/30 * * * * cd /path/to/go-crap-tracker && go-crap-tracker repo check-updates --schedule >> /var/log/go-crap-tracker-rescan.log 2>&1

Flag	Description
`--schedule`	Schedule a rescan for repos that moved (default: report only).
`--json`	Emit the per-project outcomes as JSON.

repo list¶

List every repo known to the system — the union of the Postgres repos, repo_configs, repo_locks tables and the on-disk cache.

go-crap-tracker repo list
# or as JSON
go-crap-tracker repo list --json

Flag	Description
`--json`	Emit the rows as JSON instead of a table.

The table columns are ID, REPO, COMMIT, PROFILES, CONFIG (ref/test/crap/submodules/timeout/go_flags), and LOCK (free, owner@host (remaining), or EXPIRED).

repo delete¶

Remove a repository's clone and all of its coverage profiles from the shared cache. The next scan of that repo performs a fresh clone. Requires --yes.

go-crap-tracker repo delete https://github.com/org/repo --yes

Flag	Description
`--yes`	Confirm the destructive action (refused without it).

repo unlock¶

Inspect a repo lock and, if the owning worker is dead, clear it.

# inspect (no change)
go-crap-tracker repo unlock https://github.com/org/repo

# clear the lock
go-crap-tracker repo unlock https://github.com/org/repo --yes

The first run prints the owner, host, acquired and expiry times and the active/expired state. Re-run with --yes to force-clear.

Flag	Description
`--yes`	Clear the lock (without it the command only inspects).

repo config¶

Per-project overrides are stored in Postgres (keyed by repo + project) and applied to every scan of that repo — or, with --subdir, of just one of its projects. set is a partial upsert: only flags you pass are changed, the rest keep their stored value.

repo config set¶

# repo-root override
go-crap-tracker repo config set https://github.com/org/repo \
  --ref release \
  --test-args "-race ./pkg/..." \
  --crap-args "--exclude,legacy/.*" \
  --submodules \
  --timeout 30m \
  --go-flags "-p=1 -parallel=2"

# scoped to one project of a multi-module repo
go-crap-tracker repo config set https://github.com/org/monorepo --subdir tsc --ref release

Flag	Description
`--ref`	Branch/tag to track (git ref).
`--test-args`	Args after `go test` (e.g. `"-race ./pkg/..."`).
`--crap-args`	Extra `go-crap` flags, comma-separated (e.g. `"--exclude,pb/.*"`). Empty string clears.
`--submodules`	Clone/update with git submodules.
`--timeout`	`go test` timeout (e.g. `"30m"`); `"0"` falls back to the global default.
`--git-timeout`	`git` operation timeout (e.g. `"30m"`); `"0"` falls back to the global default.
`--go-flags`	`GOFLAGS` for the repo's `go test` / `go-crap` subprocesses (e.g. `"-p=1 -parallel=2"`); bounds memory on constrained hardware. Empty clears. See Constrained Environments.
`--subdir`	Project (subdirectory) the override applies to, e.g. `tsc`; empty = repo root.

At least one flag is required. A project's ref falls back to the repo-root config's ref when the project has none.

repo config get¶

go-crap-tracker repo config get https://github.com/org/repo
go-crap-tracker repo config get https://github.com/org/repo --subdir tsc
go-crap-tracker repo config get https://github.com/org/repo --json

Prints the stored ref, test args, crap args, subdir, submodules, timeout, go flags, and last-updated time. --json emits it as JSON.

repo config rm¶

go-crap-tracker repo config rm https://github.com/org/repo
go-crap-tracker repo config rm https://github.com/org/repo --subdir tsc

Deletes the override (for the given project, or the repo root) so scans fall back to defaults.

Repo Cache — how cloning, coverage reuse, and locking work.
Constrained Environments — when and why to set --go-flags on memory-limited hardware.
HTTP API — POST/GET/DELETE /api/repo-config expose the same overrides over REST.