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
- Takes the changes your branch made to one model file.
- Applies them on top of the latest version of that file, for example on
develop. - 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
- PASS: the merge builds and every requirement that passed before still passes. Safe to merge.
- CONFLICT: both branches changed the same thing to different values, for example the same parameter. Pick one by hand.
- REJECT: the edits merge, but the merged part breaks a requirement. Fix the model first.
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
--file: the model file to check.--base: the commit your branch started from.git merge-base origin/develop my-branchprints it.--head: the latest version you want to merge into.--yours: your branch, or a folder that contains your edited copy of the file.--out(optional): where to write the merged model. Written only on PASS.--json(optional): print the full report as JSON.
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.