Work with monorepos

The graft map supports one repo with many packages, submodules, nested clones, and folders of separate repos.

A monorepo with one .git

A pnpm-workspace.yaml/package.json workspaces, or per-package go.mod/pyproject.toml/Cargo.toml. No flags needed:

trail build

trail build discovers each sub-project as a ranking scope. ask/map rank every scope on its own terms and fuse the results, so the biggest sub-project can’t drown a small one; hits carry [scope/] labels, and trail map groups its directory clusters by scope first.

A Git superproject with submodules

Submodules stay excluded by default. To fold initialized gitlinks into one graph:

trail build --follow-submodules

Child paths are prefixed (for example, deps/parser/src/index.ts), and each submodule’s own Git ignore rules are honored. Visible untracked files are included too; uninitialized submodules remain absent until git submodule update --init checks them out.

The choice is saved in .graft/config.json, so later no-flag builds and MCP automatic refreshes behave the same way. To restore and persist the default boundary:

trail build --no-follow-submodules

A git repo with other repos cloned inside it

No gitlink, no index entry: the shape multi-repo manifest tools like west, repo, gclient and tsrc check dependencies out into, and the shape you get by cloning an upstream into the tree to patch it locally. --follow-submodules cannot reach these: they have no 160000 index entry to follow. Instead:

trail build --follow-nested-repos

Child paths are prefixed (for example, external/parser/src/index.ts), and each clone’s own Git ignore rules are honored. A clone at a git-ignored path stays absent, since Git never reports it.

The choice is saved in .graft/config.json and is independent of --follow-submodules; neither flag implies the other. To restore and persist the default boundary:

trail build --no-follow-nested-repos

Tip

Prefer this over the multi-repo split below when the nested repos import from each other and you want those edges in one graph; prefer the split when you want each repo scored and refreshed on its own.

A folder of separate git repos

No .git at the top. trail build auto-splits: each child gets its own (git-ignored) graft/, and the parent gets a graft/workspace.json index. Queries from the parent federate across every child, always labeled <child>/. Run trail build inside a child to work on just that repo.

trail init at the parent of a multi-repo folder wires every child repo too, not just the parent. An agent session opens at a repo root and reads its instruction files from there, so each child needs its own. A session started in the parent gets the federated view; one started in a child sees that repo alone.

Narrow to one sub-project

In every layout, narrow to one sub-project once you know where you’re working:

trail ask "<task>" --in <scope>/

Run from a subdirectory

Commands also find the graph from a subdirectory: with no [dir] argument they walk up to the nearest graft/, so trail ask works from src/deep/inside/ without a cd to the repo root.