<!-- skill-index: generated by scripts/skill-index.py; make check-skill-index -->

Find it fast

sed -n '<from>,<to>p' SKILL.md one section rather than reading the file; ./mxcli syntax <topic> answers how do I write this for a fraction of either.

lines	section
35-41	The rule: let Studio Pro do version control when it can
42-55	Branches: create them on the server
56-78	Commit from the agent
79-93	Push the branch and the notes together, and soon
94-106	Never rewrite or merge model history with git
107-117	Reading what Studio Pro recorded
118-126	Checklist

<!-- /skill-index -->

Working with Git on a Mendix Team Server Project

A Mendix project in git is more than its files. Studio Pro keeps four things in step that plain git does not, and a commit that skips them makes Studio Pro report conflicts nobody can see, crash on open, or refuse to deploy a revision.

What	Where	What breaks without it
Model units	mprcontents/**/*.mxunit	— (git handles these)
Unit index	the .mpr Unit table, ContentsHash per unit	Studio Pro's change detection; it shows changes the files do not have
Commit metadata	a git note per commit under refs/notes/mx_metadata	version check and package build for that revision; the history shows (unknown)
Branches	on the Team Server	Studio Pro 11.13 crashes opening a branch that has no upstream

The rule: let Studio Pro do version control when it can

If the user has the project open in Studio Pro, the cheapest correct commit is theirs: Version Control › Commit in Studio Pro commits, writes the note, and pushes, all in one go, even when every change in it was made with mxcli. Suggest that first. Everything below is for committing from the agent.

Branches: create them on the server

• Never git checkout -b a branch the user will open in Studio Pro. A local-only branch has no upstream, and Studio Pro 11.13 fails to open it with "Unable to find 'system' property in 'system'".
• Ask the user to create the branch in Studio Pro: Version Control › Manage Branch Lines… › New. That creates it on the Team Server. Then git fetch && git switch <branch>, and git tracks it as origin/<branch>.
• If they want the agent to do it instead, it must be pushed with an upstream straight away. That is an outward action, so ask first: git switch -c <branch> && git push -u origin <branch>.
• mxcli docker check, mxcli run --local and mxcli diag -p app.mpr warn when the checked-out branch has no upstream.

Commit from the agent

mxcli fix hashes -p app.mpr                     # unit index matches the files (exit 0)
git add App.mpr mprcontents <other source you changed>
git commit -m "<what changed for the user>"
mxcli git note -p app.mpr --write               # attach the mx_metadata note

• Stage App.mpr, mprcontents/ and the source you changed (theme/, javasource/, javascriptsource/, widgets/, mdlsource/). Never stage project-settings.user.json, *.mpr.lock, *.mpr.bak, .mendix-cache/, deployment/, theme-cache/ or .mxcli/; Mendix's .gitignore already excludes most of them.
• mxcli fix hashes matters after anything other than mxcli or Studio Pro touched a unit file: git checkout -- mprcontents/…, git restore, a merge tool. mx check does not notice a stale index. --repair fixes it.
• mxcli git note with no commit argument annotates every commit not pushed yet (@{upstream}..HEAD). It computes the change list from the commit itself, so run it after committing. It never overwrites a note Studio Pro wrote (--force does) and it does replace Studio Pro's placeholders. Without --write it only previews.

Push the branch and the notes together, and soon

git push origin <branch> refs/notes/mx_metadata

• git push alone does not push notes.
• While the project is open, Studio Pro fetches every few minutes, and its fetch force-replaces the local refs/notes/mx_metadata with the Team Server's copy. Any note not pushed yet is gone, and Studio Pro back-fills an "(unknown)" placeholder for the commit. If that happened, run mxcli git note -p app.mpr --write again; it replaces placeholders. Then push.
• Pushing goes to the user's Team Server and needs their credentials (a PAT). Only push when the user asks.

Never rewrite or merge model history with git

• No git merge, rebase or cherry-pick of model changes. The .mpr is a SQLite file; git cannot merge it, and a textual merge of mprcontents/ leaves an index that does not match the files. Studio Pro has a model-aware merge: Version Control › Merge Changes Here (Merge feature branch or Cherry Pick). Studio Pro's history on Team Server is linear for that reason.
• No --amend or force-push of a pushed commit. Before pushing, an amend is fine: the notes.rewriteRef Studio Pro puts in .git/config carries the note. Re-run mxcli git note --write anyway; it is cheap.
• Do not switch branches or write the model while <App>.mpr.lock exists, which means Studio Pro has the project open. mxcli refuses to write then.

Reading what Studio Pro recorded

git log --notes=mx_metadata --format='%h %s%n%N' -10

A note lists ModelChanges (Added | Modified | Deleted | Moved, with unit type, name and module), the ModelerVersion, and the BranchName ("" on main). A note with "HasModelerVersion":false is a placeholder Studio Pro wrote for a commit made outside it.

Checklist

• Suggested committing from Studio Pro when it is open
• On a branch that exists on the Team Server (has an upstream)
• mxcli fix hashes -p app.mpr clean
• Only project files staged
• mxcli git note -p app.mpr --write after the last commit
• Pushed <branch> and refs/notes/mx_metadata together, when the user asked to push
• No git merge, rebase, cherry-pick or force-push of model history