Reference projects
A reference project is another project that Tracemoor has already analyzed and that is attached to the current exploration for lookup. You can search it, follow its call chains, open its files and read its projectdocs and specs. You cannot change it. Everything you write goes to the active project.
Example: Weatherreport is a desktop app that fetches forecasts from the service
WeatherIngest. With WeatherIngest attached as a reference, the assistant can
answer "which endpoint serves fetchModelForecast, and what does it call?"
from the index of both projects, and a bug report in Weatherreport can be
anchored to the server function that causes the bug.
Purpose
Each reference has a purpose:
| Purpose | Meaning |
|---|---|
| Lookup | The assistant and the editor can look things up in the reference. This is the default. |
| Linked (calls each other) | The projects call each other across a process or network boundary. Tracemoor connects the HTTP calls, messages, commands and IPC calls between them. See Calls between linked projects. |
Declaration and binding
A reference has two parts:
| Part | Content | Stored in |
|---|---|---|
| Declaration | Short name (slug), display name, remote URL, purpose | config.json of the exploration, shared |
| Binding | Path on this machine, git access, the state that is read | local.json, this machine only |
Everyone who shares the exploration shares the list of references. Each machine decides where the referenced repositories are checked out. Credentials in the remote URL are removed before the declaration is saved.
A reference that is declared but not checked out on this machine is shown as missing. It is not an error. See Set up a missing reference.
Which state is read
A reference reads one state of its repository:
- the working copy, the folder where the project is checked out, or
- a snapshot, a separate git worktree on a fixed tag or commit, or on a remote branch that it follows.
A snapshot has its own index. The working copy of the referenced repository is not touched. Snapshots are kept in the app data folder and are shared by all explorations on this machine that reference the same repository.
A reference set stores which state every reference reads under a name, for
example "Customer X production" with the server at v4.4 and the web app at
v4.4. Applying the set switches all references at once. See
Compare states and reference sets.
Where references show up
| Place | What you see |
|---|---|
| Project Settings, Reference Projects (read-only) | Each reference with its state, purpose and git access. See Attach and manage references. |
| Status bar | 🔗 2 refs. When references need attention, · ⚠ N follows; the tooltip lists the state of each one. |
| Code editor | Files of a reference open read-only with a chip in the reference's colour: name, state, read-only. The status bar shows no language-server badge for them. |
| Graph | Nodes of a reference carry a chip with its name. Boundary edges are dashed orange and labelled with the interface key. |
| Anchors | projectdocs entries and specs can anchor symbols of a reference. See Anchors. |
| Chat | Each reference has its own read-only tool server. See References and the assistant. |