From 2356b907b967eb7c4195dcaaddc3bc0b55bbf8ce Mon Sep 17 00:00:00 2001 From: azizur100389 Date: Thu, 23 Apr 2026 00:54:54 +0100 Subject: [PATCH] docs: add Multi-user / multi-workstation guide to README (#357) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Issue #357 asked how the graph works when a repo is cloned on multiple workstations and multiple contributors add code: > Would it be the code graph being committed to the repository also, > or would it be only at workstations, and then the graph being > rebuild when pulling latest changes? The behaviour is correct ("it's a per-machine cache, don't commit it, let each contributor build their own once and let `update` keep it fresh") but the README never spelled it out, so users are left to reverse-engineer it from the source. This adds a ``Multi-user / multi-workstation workflow`` collapsible section to the Usage area. Sits between the CLI reference and the multi-repo daemon section, matching the existing collapsible-details layout the README already uses. What it explains ---------------- 1. Why the graph isn't shared — graph.db references source files by absolute path (verified by reading rows from a freshly-built DB on Windows: ``'C:\Users\...\app.py'``). Sharing the file would break every lookup as soon as paths differ between machines. 2. The two layers of automatic .gitignore protection that keep the graph out of commits without contributor effort: - top-level ``.gitignore`` gets ``.code-review-graph/`` appended by ``install`` via ``ensure_repo_gitignore_excludes_crg`` - inner ``.code-review-graph/.gitignore`` contains ``*`` so any side-files (WAL/SHM, embeddings, wiki output) are ignored too 3. Recommended per-contributor workflow: clone -> install -> build once, then ``update`` after each ``git pull`` (or let the editor hook do it). 4. Pre-commit and CI patterns: - The git pre-commit hook (installed by default for claude / qoder / all targets via ``install_git_hook``) runs ``update`` followed by ``detect-changes --brief`` and *appends* to any existing hook rather than overwriting. - CI: build cold once, ``detect-changes --base origin/main`` for each PR. Workspace-cache reuse via ``CRG_DATA_DIR``. 5. The ``CRG_DATA_DIR`` and ``CRG_REPO_ROOT`` environment variables — neither was previously documented in the README despite being real product surface (verified in ``code_review_graph/incremental.py``). 6. Per-editor MCP config files are local environment, not repo state — so contributors using Cursor / Zed / Codex don't need any extra coordination. Verification ------------ Every concrete claim in the new section was checked against the running code, not the spec: - ``ensure_repo_gitignore_excludes_crg`` (incremental.py:244) — confirmed it appends to existing .gitignore and creates one if missing. - Inner ``*\n`` ignore (incremental.py:208) — verified by calling ``get_data_dir`` on a temp dir and reading the resulting ``.gitignore``. - Absolute paths in graph.db — verified by parsing a temp file and selecting ``file_path`` rows directly from the SQLite DB. - Pre-commit hook content (skills.py:552-) — confirmed the script runs ``code-review-graph update || true`` then ``code-review-graph detect-changes --brief || true``. - Pre-commit installation default — confirmed via ``cli.py:269-276`` that it runs for target ``claude``, ``qoder``, ``all`` whenever ``--no-hooks`` is not set. - Pre-commit appending behaviour — confirmed via the docstring and body of ``install_git_hook`` (skills.py:552). - ``CRG_DATA_DIR`` and ``CRG_REPO_ROOT`` env-var handling — confirmed in ``get_data_dir`` (incremental.py:189) and ``find_project_root`` (incremental.py:166). - ``--base`` flag on ``update`` and ``detect-changes`` — confirmed via the ``Usage`` block at the top of ``cli.py`` and via argparse setup at ``cli.py:420``. No code changes — pure docs. Files changed ------------- README.md — +93 lines. No deletions. --- README.md | 101 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 101 insertions(+) diff --git a/README.md b/README.md index 07249031..2d35104b 100644 --- a/README.md +++ b/README.md @@ -267,6 +267,107 @@ code-review-graph serve # Start MCP server +
+Multi-user / multi-workstation workflow +
+ +**Short version:** the graph is a **per-machine cache**. Don't commit it; let each +contributor build their own once and let `update` keep it fresh from `git pull`. + +> Closes #357. + +### Why the graph isn't shared +`code-review-graph` stores its database in `/.code-review-graph/graph.db` and +the rows reference your source files by **absolute path** (e.g. `/Users/alice/work/myrepo/src/foo.ts` +on macOS, `C:\Users\bob\repos\myrepo\src\foo.ts` on Windows). Sharing the file +between machines would break every lookup the moment the path differs by one +character. There is no portable on-disk format today — the SQLite file is a +local cache, not a shipping artefact. + +The CLI knows this and does the right thing automatically: + +- `code-review-graph install` (and any first build) appends `.code-review-graph/` + to your repo's top-level `.gitignore`. If `.gitignore` doesn't exist yet, it + creates one. So a contributor running `git status` after their first build + sees no untracked graph files. +- The `.code-review-graph/` directory itself contains an inner `.gitignore` + with `*` so any side-files (WAL / SHM, embeddings cache, wiki output) are + also ignored even if a future change moves the data dir. + +### Recommended workflow for a team +For each contributor, on each workstation: + +1. Clone the repo and install once: + ```bash + git clone + cd + code-review-graph install # writes MCP config + adds .code-review-graph/ to .gitignore + code-review-graph build # one-time full parse — minutes, not seconds + ``` +2. Day-to-day, after `git pull`: + ```bash + code-review-graph update # incremental: only re-parses files changed since the last build + ``` + (or let your editor's hook do it — `install` configures one for Claude Code, + Cursor, etc. so most users never run `update` by hand.) +3. After a force-push or major rebase, optionally do a full rebuild: + ```bash + code-review-graph build + ``` + +### Pre-commit and CI +For Claude Code / Qoder / `all` targets, `install` writes a **git pre-commit +hook** at `.git/hooks/pre-commit` that runs `code-review-graph update` (so the +graph stays current with the working tree) followed by +`code-review-graph detect-changes --brief` (a quick risk summary so contributors +see the blast-radius of their change before pushing). It is installed by default +and respects any existing hook by **appending** rather than overwriting. Opt +out with `code-review-graph install --no-hooks`. + +For **CI**, build the graph fresh in each job — it's fast on a warm cache +because `update` only re-parses changed files. A common pattern: + +```yaml +- run: pip install code-review-graph +- run: code-review-graph build # cold build on first CI run of the branch +- run: code-review-graph detect-changes --base origin/main +``` + +If your CI re-uses a workspace cache between jobs (e.g. `actions/cache` keyed on +the source-tree hash), pointing `CRG_DATA_DIR` at a stable location lets you +warm-start `update` instead of rebuilding from scratch — see the next section. + +### Sharing a graph cache across builds (advanced) +The `CRG_DATA_DIR` environment variable moves the graph directory anywhere +outside the repo. Useful for: + +- **Shared CI cache** — point `CRG_DATA_DIR` at the cached path so the next CI + job does an `update` instead of a `build`. The DB is still per-machine, just + not per-job. +- **Ephemeral worktrees / Docker volumes** — keep the graph on a host volume so + rebuilding the container doesn't throw away the cache. +- **One graph per checkout of the same repo** — set `CRG_DATA_DIR` to a path + that includes the worktree name (e.g. `~/.cache/code-review-graph/`). + +```bash +export CRG_DATA_DIR=~/.cache/code-review-graph/myrepo +code-review-graph build # graph.db now lives at $CRG_DATA_DIR/graph.db +``` + +The matching `CRG_REPO_ROOT` env var lets you point the CLI at a project root +without having to `cd` first — handy for scripts and daemons that work across +multiple repos. + +### What about contributors using different editors? +Each editor's MCP config lives in different files (`.cursor/mcp.json`, +`~/.codex/config.toml`, `~/.config/zed/settings.json`, etc.) and is generally +**not shared across the team** — every contributor runs +`code-review-graph install --platform ` on their own machine after +cloning. The repo only needs to track the source code; everything else is +local environment. + +
+
Multi-repo daemon