Anchors
An anchor links a projectdocs entry to a code symbol (a function, a class,
a type) or to a git commit. A bug report anchored to fetch_tile shows up when
you work on fetch_tile. The commit anchor of the same report opens the diff of
the fix.
Anchor the central symbols an entry is about, usually one to six. You do not need to anchor every symbol the text mentions.
Anchor a symbol
- Open the entry.
- In the Code anchors row, click + anchor.
- Optional: in the project selector next to the input, choose a reference project instead of This project.
- Type the exact symbol name, for example
fetch_tile. - Click the matching file in the list.
The picker searches the reference WeatherIngest. The hit get_tile becomes an anchor in the reference's colour.
For This project, the list shows files whose text contains the name. The anchor is built from the file you click and the name you typed, so the typed name must be the symbol name. For a reference, the list shows symbols, and the name comes from the hit.
You can also type <file>::<name> and press Enter, for example
src-tauri/src/tiles.rs::fetch_tile. Tracemoor checks the symbol against the
index and rejects names it does not know.
To remove an anchor, click × on its chip and confirm.
Read the anchor chips
| Chip | Meaning |
|---|---|
name and kind, e.g. fetch_tile function | The symbol was found. Click to open the file at the symbol. |
| moved | The symbol was found under its old name in a different file, for example after a file rename. Check the entry and set the anchor again on the new file. |
| stale | The symbol no longer exists. Remove the anchor or anchor the replacement. |
| reference name in a coloured badge | An anchor into a reference project. Click to open the file read-only. |
| not in this state | The symbol does not exist in the state the reference currently reads, for example another tag. |
| missing | The reference project is not available on this machine. Click to open the reference settings. |
The collapse arrow in front of Code anchors hides the row. The number in brackets counts the anchors.
Anchor a commit
- Open the entry.
- In the Commit anchors row, click + commit.
- Type part of the commit subject or the hash.
- Click the commit in the list.
The chip shows the short hash and the subject. Click it to open the commit in the Git view. A commit that is not in the repository, for example on a branch you have not fetched, is marked as not found.
From the code to the entry
In the source editor, a line that carries an anchored symbol has a blue doc mark in the gutter. Click it. The peek Doc anchored on this line lists the entries with their titles. Open entry opens the entry in the dashboard. See Gutter and anchors.
The AI uses the same link in the other direction: before it changes a symbol, it asks which entries are anchored to it. See projectdocs and the AI.
How anchors are stored
Anchors are stored in the frontmatter of the entry and travel with it through git:
anchors: ["/Users/…/Weatherreport/src-tauri/src/tiles.rs::fetch_tile", "ref:weatheringest:app/routers/tiles.py::get_tile"]
commit_anchors: ["4f42052…"]
An anchor names the file and the symbol, not a line. Tracemoor resolves it against the current index. Line changes and edits inside the symbol do not affect it.
Limits
- Anchors into this project are stored with the absolute file path of the machine that created them. On a clone in another folder they resolve by name only: the chip shows moved and the gutter shows no mark. Anchors into reference projects are stored relative and are not affected.
- After a pull with Sync exploration, anchors added by
others appear once the local anchor index is rebuilt. Ask the AI to run
projectdocs_sync_anchors.