Tracemoor

Share an exploration

An exploration is a folder next to the project. It can be its own git repository with its own remote, separate from the source repository. Sharing it gives the team the same projectdocs, specs, docs and project hints. Each machine keeps its own analysis cache and rebuilds it with an analysis.

What is shared

Shared (committed)Local only (ignored)
projectdocs/, specs/, docs/, notes/, README.md.codeexplorer/analysis/ (index, call graph, embeddings)
.codeexplorer/config.json (display name, declared reference projects).codeexplorer/sessions/ (chat sessions) and attachments/
.codeexplorer/project_hints.md.codeexplorer/local.json (absolute paths, reference bindings)
.codeexplorer/ui_state.json, exclusions/, work_packages.json
specs/_drafts/ (unaccepted reverse-spec drafts)

Tracemoor writes this split as .gitignore when it creates the exploration.

Open the sync dialog

Use one of:

  • Git › Sync Exploration…
  • In the projectdocs dashboard toolbar, Sync exploration over git.

The dialog shows the branch of the exploration and the number of uncommitted files.

Set up sharing the first time

  1. Open Sync exploration.
  2. If the exploration is not a git repository yet, click Initialise git.
  3. Under Remote (origin), enter the URL of an empty repository, for example git@github.com:acme/weatherreport-exploration.git, and click Save.
  4. Under Commit message, keep or change the text and click Commit.
  5. Click Push.

When the remote is saved, Tracemoor also writes .codeexplorer/exploration-remote.json into the source project. Commit that file in the source repository. A teammate who clones the source project with Tracemoor finds the exploration through it. If the file is missing, the dialog offers Write recovery pointer.

Get changes from the team

  1. Open Sync exploration.
  2. Click Pull.

Uncommitted local changes are committed first. Then Tracemoor merges the remote state. Changes to different files merge without a question.

Resolve conflicts

If the same file was changed on both sides, the dialog lists it under Resolve merge conflicts. For each file:

  • Mine keeps your version.
  • Theirs takes the incoming version.
  • Resolved marks a file you edited yourself, for example in the editor.

When all files are handled, click Finish merge. Abort merge returns to your local state before the pull.

Send your changes

  1. Open Sync exploration.
  2. Enter a commit message and click Commit.
  3. Click Push.

Limits

  • After a pull, anchors that others added appear in the dashboard and the gutter only after the local anchor index is rebuilt. See Anchors.
  • The analysis cache is not shared. Each teammate runs an analysis after the first clone.
  • The AI can run the same steps with exploration_status, exploration_commit, exploration_pull, exploration_push and exploration_set_remote.