Concepts

MetaCroc logo

Concepts #

This page explains how branches work internally. UI actions are described on the other pages in this section.

Branch and system scope #

A branch is a named, independently evolving copy of the metadata model inside one system. All branches share the same element identities; each branch keeps its own versions.

  • Every system has exactly one main branch. Existing systems were migrated so that all their history belongs to main.
  • main cannot be renamed or deleted.
  • Branches form an unlimited hierarchy: each non-main branch has a source (parent) branch.
  • The branch you work in is chosen in the project tree (see Editing on a branch).

Baseline version per element #

When a branch is created, MetaCroc records for every element of the source branch which version the new branch starts from. This is the element’s baseline on the branch. No metadata is copied.

For each element on a branch MetaCroc keeps two pointers:

PointerMeaning
BaselineVersion the branch started from (the parent’s version at creation time, or after the last rebase)
Own versionLatest version pushed on this branch, if any

The element content shown on a branch is the own version if it exists, otherwise the baseline.

flowchart LR mainV["main: CUSTOMER main-42"] featBase["feature/A baseline = main-42"] featOwn["feature/A own version feature/A-1"] mainNew["main: CUSTOMER main-43"] mainV --> featBase featBase -->|"Edit + Push on feature/A"| featOwn mainV -->|"later push on main"| mainNew

Consequences:

  • A child branch does not see later pushes on its parent automatically. Use Rebase from parent to move the baselines to the parent’s current state.
  • The baseline is the common ancestor used for three-way comparison in merge requests and rebase, so MetaCroc can tell “changed only here” from “changed on both sides”.
  • Elements created on a branch exist only on that branch (and branches created from it later) until merged.
  • Deleting an element on a branch marks it deleted on that branch only.

Version labels #

Each push creates a version labelled {branch-name}-{number}, for example main-42 or feature/A-1.

  • The number continues on the branch where the previous version was pushed. The first push of an element on a new branch starts at 1.
  • Existing history was migrated to main-{N}.
  • Renaming a branch does not rewrite existing labels; new pushes use the new name.

Working data and locks #

Edit drafts (working data) and edit locks are stored per branch and element. The same element can be edited on two branches at the same time by different users. Switching branches keeps your draft on the previous branch.

Branch status #

StatusUI labelWhat it means in practice
ACTIVEOpenedNormal working state
LOCKEDLockedFrozen: rebase and cherry-pick into it are blocked, relations cannot be changed. Element edit and push are not blocked yet.
ARCHIVEDArchivedHidden by the default tree filter; definition cannot be edited; can be restored from archive
DELETEDDeletedSoft-deleted; content of the branch is removed; cannot be restored from the UI

The Opened tree filter shows Active and Locked branches.

Branch flags #

FlagBehaviour
ProtectedPush directly on the branch is rejected (“use a merge request instead”). Rebase and cherry-pick into the branch are blocked. Merge requests into a protected branch work.
Confidential (restrict to explicit permissions)Shown as a badge. Only enforced when the branch is the source of a cherry-pick: users without VIEW on the system do not see it. Not hidden elsewhere.
Required approvalsQuorum for merge requests into the branch, 0–10. 0 means merge requests without conflicts are approved immediately.
Self-approval allowedWhen off (default), the MR author cannot approve their own MR.
Require explicit merge actionWhen on, the user who executes a merge holds a merge lock on the target branch while the merge runs. Merging itself is always triggered manually.

The system parameter Minimum number of approvers (system Overview, 0–10, default 0) is the lower bound for required approvals when a branch is created or edited.