---
name: teamserver-git
description: "Commit, branch and push a Mendix project in git the way Studio Pro and Mendix Team Server expect — branches created on the server (not with git checkout -b), the mx_metadata commit note written with `mxcli git note`, and the notes ref pushed with the branch. Use before any git commit, branch, merge, rebase or push in a Mendix app repository, and when Studio Pro shows conflicts or changes that git does not, fails to open the project, or cannot deploy a revision."
---

# 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

```bash
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

```bash
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

```bash
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