docs / collaboration

Check a model merge before you merge it

Two people, or two AI agents, edit the same .kcad.ts model on separate Git branches. Git can merge the text cleanly and still hand you a part whose bolt holes no longer line up. kernelcad collab check catches that before you merge.

What it does

  1. Takes the changes your branch made to one model file.
  2. Applies them on top of the latest version of that file, for example on develop.
  3. Rebuilds the merged model and re-runs every require(...) check that passes on the latest version.

If something that worked before the merge breaks after it, the check fails and tells you which requirement and by how much.

The three answers

The command exits with 0 on PASS and 1 otherwise, so you can use it in a script or CI step.

Run it

From the folder that holds the model, inside your Git repository:

cd examples/collab
kernelcad collab check \
  --file  bracket-and-motor-plate.kcad.ts \
  --base  BASE_REF \
  --head  origin/develop \
  --yours my-branch \
  --out   merged.kcad.ts

Example

The example model is a bracket bolted to a motor plate. One requirement, hole-pattern, says their bolt holes must line up within 0.5 mm.

A branch that only rounds the bracket edges passes:

collab check: PASS (rebased: no)

A branch that moves one bracket hole is rejected, because the holes are now 2 mm apart:

collab check: REJECT
  collab.gate.requirement-failed:
    name: hole-pattern, measured: 2, limit: 0.5

Two branches that set the same hole position to different values (15 and 16) conflict:

collab check: CONFLICT
  collab.conflict.param:
    name: bracketHoleX
    base: 12, head: 15, yours: 16

What it is not

It is a local gate: it runs on your machine and only reports. It does not merge anything on GitHub, and it is not live co-editing; it does not provide hosted concurrent collaboration.

Browse agent workflow demos