Skip to main content

marshal-branch-manager

mbm keeps a fork of a GitHub project up to date when you're carrying a stack of unmerged PRs and local feature branches on top of upstream. It was written for MicroPython but works with any GitHub-hosted project.

The idea is simple. Your fork has an integration branch (say main or mimxrt) which is basically upstream plus one merge commit per feature branch. When upstream moves, mbm rebase throws that branch away and rebuilds it: each feature branch is rebased onto the new upstream on its own, then merged in, in the order listed in mbm.toml. You get a clean, readable history where every feature is still an isolated branch you can push back to its PR.

On top of that it:

  • adds new PRs by number, URL or branch name, creating a remote for the PR author's fork if needed
  • skips PRs that GitHub says have already been merged upstream
  • pushes rebased feature branches back to their owner's fork (never to upstream), and checks they haven't changed on the remote first
  • trains git rerere from your previous integration branch, except in fully offline mode, so conflicts you've already resolved can be resolved again automatically
  • builds the result on a timestamped update branch and, if you use GitLab, gives you a pre-filled merge request link to review it

Install

mbm requires Git 2.38 or later for git rebase --no-update-refs.

For a direct migration from an existing uv tool installation, remove the old tool before installing the new package:

uv tool uninstall micropython-branch-manager
uv tool install marshal-branch-manager

The marshal-branch-manager distribution provides the mbm command, not the former micropython-branch-manager command. Update scripts to use mbm.

You'll also want the GitHub CLI (gh) installed and logged in (gh auth login). It's used for PR lookups; without it mbm still works but can't skip merged PRs or fill in PR details.

Quick start

mbm expects your remotes to look like this:

  • upstream: the GitHub project you're tracking, e.g. https://github.com/micropython/micropython.git
  • one remote per fork you push to, e.g. andrewleech or origin pointing at git@github.com:andrewleech/micropython.git
  • optionally a GitLab remote, if you review integration updates as GitLab MRs

If MicroPython is a submodule of your project, run init from the project root. It writes mbm.toml there (commit it with the project) and finds the submodule at src/micropython or micropython:

cd my-project
mbm init --submodule src/micropython --integration-branch main

If you're working directly in a fork clone, point it at the repo itself:

cd my-fork
mbm init --submodule . --integration-branch main

Then add some PRs and rebuild whenever upstream moves:

mbm add-pr 18333                  # by PR number
mbm add-pr https://github.com/micropython/micropython/pull/18229
mbm rebase                        # rebuild on the latest upstream

add-pr and rebase create a new <integration>_update-YYYYMMDDTHHMMSSZ branch, with the timestamp in UTC. They check out the update branch after publication and leave the integration branch alone unless rebase --apply is explicitly requested. A destination that already exists is never overwritten, including when two runs start in the same second. Review and test the exact update branch, then deliberately force-push it to the integration branch, for example git push origin +main_update-20261118T120000Z:main.

Generated merge commits include a Generated-by: marshal-branch-manager footer and MBM-PR and MBM-URL trailers when that metadata is available. add-pr also writes MBM-Author when available; rebase may omit it. Git adds the committer's Signed-off-by trailer last. For example, an add-pr merge commit can contain:

main: Merge branch 'feature-x'.

Add feature X

MBM-PR: 12345
MBM-URL: https://github.com/micropython/micropython/pull/12345
MBM-Author: username
Generated-by: marshal-branch-manager
Signed-off-by: Example User <user@example.com>

Existing merge commits with MBM trailers remain readable.

Commands

mbm init

Creates mbm.toml in the current directory (or the --config path) and adds a submodule entry to it. If you don't pass --integration-branch it uses whatever branch the repo has checked out. It also turns on git rerere in that repo. Running it again with a different --submodule adds another entry, so one config can manage several submodules; the other commands pick one with --submodule/-s, or work it out from your current directory.

mbm add-pr <pr>

Adds a PR to the integration branch as a merge commit. The PR can be a number, a branch name or a full URL (it has to be a PR against the upstream repo).

It looks the PR up on GitHub, fetches it, merges it into a new timestamped update branch and adds it to mbm.toml, including the PR author so later pushes go to the right fork. If a GitLab remote exists the update branch is pushed there and you get an MR link.

$ mbm add-pr 18333
Fetching PR info for: 18333
Found PR #18333: ports/mimxrt: Update nxp_driver to MCUX_2.16.100.
Branch: mcux_sdk_2.16
State: OPEN

Fetching PR #18333 from upstream...
Building update branch from mimxrt...
Merging mcux_sdk_2.16 into mimxrt_update-20261118T120000Z...
Merge completed successfully

Updating config...

Pushing mimxrt_update-20261118T120000Z to gitlab...

=== PR ADDED SUCCESSFULLY ===
PR #18333: ports/mimxrt: Update nxp_driver to MCUX_2.16.100.
Branch: mcux_sdk_2.16

Create MR: https://gitlab.example.com/.../merge_requests/new?...

To queue another PR, select the existing update explicitly: mbm add-pr 12345 --from-update mimxrt_update-20261118T120000Z. The selected ref must descend from the integration branch and contain only recognized configured merge commits since that branch. MBM builds a new timestamped branch from it and leaves the selected ref unchanged. Without --from-update, the integration branch is the base. Publication creates the new destination only if it does not already exist.

MBM warns if the selected base lacks configured branches. The MR description lists configured branches found in the update branch's first-parent merge history and identifies configured branches not found there. Review the warning before integrating the update.

mbm rebase

Rebuilds the integration branch on top of a new upstream:

mbm rebase                        # onto the default target
mbm rebase --target v1.27.0       # onto a particular ref, e.g. a release tag

The target is picked in this order: --target, then target in mbm.toml, then upstream's default branch (upstream/HEAD, which mbm sets up with git remote set-head upstream --auto if it's missing), and finally upstream/master. With --local-sources or --offline, mbm uses the existing upstream/HEAD without contacting the remote, or falls back to upstream/master.

Rebuilding onto a release tag works too. If the target is older than upstream's default branch, each PR branch (which is usually based on the latest upstream) is rebased with git rebase --onto <target> <upstream default>, so only the PR's own commits get moved onto the tag, not everything upstream did since.

Before rebuilding, mbm asks GitHub for the state of each PR and skips any that are merged, printing which ones. They stay in mbm.toml until you remove them. --local-sources and --offline skip these checks.

rebase builds a new timestamped update branch from the target. It uses private work refs while rebuilding, and atomically creates the destination and a publication marker. A concurrent destination is never overwritten. Runs that push also refuse an existing remote destination and use an expected-absent lease. If a push is interrupted before its success is recorded, resume preserves an existing remote branch instead of assuming the run created it. Resume uses the destination saved when the run started.

Options:

  • --local skips the initial fetch and all pushes, but still fetches PR and fork sources and checks PR state on GitHub.
  • --local-sources skips all fetches and GitHub PR state checks, and uses only the configured local branch refs. It snapshots their object IDs for the run and resume. A missing local branch is an error; there is no remote fallback. Feature branch updates require --local with this option. To allow an update branch push without updating feature branches, combine it with --no-update-branches.
  • --offline combines --local and --local-sources: it skips network access and uses local source branches. It does not change the feature branch update policy or imply --apply.
  • --dry-run shows what it'd do without changing anything
  • --apply moves the integration branch to this run's update branch after a clean run, provided its ref has not changed and it is not checked out in another worktree. This does not apply an update branch from an earlier run; for a reviewed branch, force-push that specific ref instead.
  • --no-update-branches only builds the update branch; your feature branch refs aren't moved, tracked or pushed. Useful if you've got feature branches checked out in other worktrees or just don't want them touched. --update-branches forces the opposite, and the default comes from update_feature_branches in the config.
  • --force-push pushes even if a feature branch on the remote has moved since you last fetched it (careful, you'll lose whatever's there)
  • --resume carries on after you've fixed a conflict (see below). It uses the saved local source and feature branch update settings, even if the options differ on the resume command. A run started with --local or --offline also remains no-push on resume. --offline --resume requires a run started with --offline or both --local and --local-sources, so the saved ref retention and network policies remain unchanged. A run started with --create-only in a development build cannot be resumed with --apply.

For an offline run that leaves feature branches and the integration branch unchanged, set update_feature_branches = false in the config or pass --no-update-branches, and run mbm rebase --offline without --apply. The target and all configured source branches must already exist locally. A run started with --offline or both --local and --local-sources does not delete refs with git update-ref -d: after a successful run, it retains the private mbm-run-<id> branch, its mbm-run-<id>-rebase-<index> branches and the refs/mbm/mbm-run-<id>/published marker. The progress state file is removed on success. For other modes, MBM removes owned temporary refs using their expected object IDs. Inspect retained refs and confirm they are no longer needed before removing them manually.

With --offline or both --local and --local-sources, MBM skips rerere training even when rerere is enabled. It leaves the existing rerere configuration unchanged, so Git can still use recorded resolutions.

Here's what a rebuilt branch looks like, every feature is its own branch off the target, merged in order:

*   c1c523ebd7 - Merge branch 'mimxrt1176-alt11-pwm' (HEAD -> mimxrt_update-20261118T120000Z)
|\
| * e16d226353 - mimxrt: Add ALT11 pin mode support for MIMXRT1176. (mimxrt1176-alt11-pwm)
* |   a288f37e95 - Merge branch 'adc'
|\ \
| * | 30aa89db5e - mimxrt/machine_adc: rt117x: Support channel groups. (adc)
| * | b045f8ae4f - mimxrt/machine_adc: rt117x: Initialize LPADC2.
* | |   6f84252a13 - Merge branch 'mimx_sdcard_timeouts'
|\ \ \
| * | | 623409093a - mimxrt/sdcard: Improve robustness of sdcard driver. (mimx_sdcard_timeouts)
| * | | 5dd59d4e07 - mimxrt/sdcard: Fix deadlock in sdcard_power_off.
* | | |   62c3ccf986 - Merge branch 'mimx_Flash_doc'
|\ \ \ \
| * | | | cad3bd124a - docs/mimxrt: Add docs for mimxrt.Flash. (mimx_Flash_doc)
| |/ / /
* | | |   864c580cfa - Merge branch 'dp83867-phy-driver'
|\ \ \ \
| * | | | 76fcf3ce95 - mimxrt/eth: Improve Dual Ethernet configuration. (dp83867-phy-driver)
| * | | | 7ad3bbaff7 - mimxrt/boards/MIMXRT1170_EVK: Remove obsolete pin defines.
| * | | | 6a70a07795 - mimxrt/eth: Add DP83867 PHY driver support.
| |/ / /
* | | |   03163eaaeb - Merge branch 'phyboard-rt1170'
|\ \ \ \
| * | | | 99d763bffb - mimxrt: Add PHYBOARD-RT1170 board support. (phyboard-rt1170)
| |/ / /
* | | |   345a5419a3 - Merge branch 'manifest_c_module'
|\ \ \ \
| * | | | 12b45387e5 - tools/ci: Add c_module() testing for RP2 and STM32. (manifest_c_module)
| * | | | ... (more commits)
* | | | |   b61786d615 - Merge branch 'mcux_sdk_2.16'
|\ \ \ \ \
| * | | | | 66be1ee6a8 - mimxrt/fsl_lpuart: Use wrapper for IRQ Idle support. (mcux_sdk_2.16)
| * | | | | 8c34a2df96 - ports/mimxrt: Update nxp_driver to MCUX_2.16.100.
|/ / / / /
* / / / / 78ff170de9 - all: Bump version to 1.27.0. (upstream/master, mimxrt)

mbm sync <github-user>

Brings mbm.toml back in line with what's actually on the integration branch. It reads the merge commits, adds any branches that are missing, and fills in PR number, URL, title and author by looking up PRs from <github-user> (plus any branch it can find a PR for). It's the easy way to start using mbm on a fork you've been maintaining by hand, or to backfill author in an older config.

If a PR in the config has been merged upstream, sync tells you but leaves the entry alone; take it out yourself when you're ready (sometimes you want to keep it pinned for a while).

mbm config

Prints the integration branch, configured branches and remotes.

Configuration

mbm.toml is written by init, add-pr and sync, but it's plain TOML and fine to edit by hand. Branch order matters, it's the merge order.

[[submodules]]
path = "src/micropython"
integration_branch = "main"
# target = "v1.27.0"
# update_feature_branches = false

[[submodules.branches]]
name = "mcux_sdk_2.16"
pr_url = "https://github.com/micropython/micropython/pull/18333"
pr_number = 18333
title = "ports/mimxrt: Update nxp_driver to MCUX_2.16.100."
author = "andrewleech"

[[submodules.branches]]
name = "my-local-hack"   # no PR, lives in your fork or just locally
author = "andrewleech"

Per submodule:

  • path: the repo, relative to mbm.toml
  • integration_branch: the branch mbm rebuilds
  • target: default rebase target, if you don't want upstream's default branch
  • update_feature_branches: set to false to leave feature branch refs alone during rebase (default true)

Per branch:

  • name: local branch name, the only required field
  • pr_url, pr_number, title: the PR it belongs to, if any
  • author: GitHub owner of the fork the branch lives in, used to decide where to push it

By default, branches with a pr_number are fetched fresh from the PR on upstream. Ones without are fetched from the author's fork remote, and rebase uses whichever of that and your local branch is newer, so a stale local checkout doesn't matter (and unpushed local commits aren't lost). If the two have diverged it stops and asks you to sort it out first. With no fork remote, or the branch not pushed yet, it just uses the local branch. --local-sources and --offline instead require and use the configured local branch for every entry.

For remote sources, rebase resolves the advertised ref to an object ID with git ls-remote and fetches that object without writing FETCH_HEAD or creating a source ref.

Older configs with everything at the top level (no [[submodules]]) still load fine.

The GitHub repo used for PR lookups comes from the upstream remote. If there isn't a GitHub upstream remote it assumes micropython/micropython.

Pushing

With a normal (non --local) run, rebase pushes:

  • each feature branch to its owner's fork. That's the remote whose URL matches the branch's author; if author isn't set yet it's taken from the PR on GitHub, or from pr_url when that points at a fork. It'll never push to upstream or any other remote for the upstream repo. No matching remote means the branch is skipped with a warning.
  • the update branch to your GitLab remote, if you have one, along with an MR link that has the title and description filled in:

__omp_shell("GitLab MR Example")

Before force-pushing a feature branch it checks whether the remote copy has commits you don't have (someone else pushed, or you pushed from another machine). If so that branch is skipped and reported at the end, the rest still go.

When pushing is enabled and a GitLab remote exists, MBM checks that the update branch is absent before rebuilding. Its push uses an expected-absent lease so it cannot overwrite a branch created concurrently.

Conflicts

If a rebase hits a conflict rerere can't fix, mbm stops, identifies the branch and saves its progress in the worktree's Git directory:

Conflict while rebasing feature-branch.
Resolve conflicts manually, then run:
  cd /path/to/micropython
  git rebase --continue
  mbm rebase --resume

Fix it, git rebase --continue, then mbm rebase --resume and it picks up where it left off. rerere remembers your fix, so next time it'll be applied automatically.

If you abandon a run, or --resume reports legacy state or cannot safely identify a completed rebase, inspect the state before removing it. Version 1 state cannot be resumed because MBM cannot prove ownership of its refs; handle it manually. Run these commands from the same worktree where the run started:

git rev-parse --git-path mbm-rebase-state.json
git status
git worktree list

Open the state file at the printed path and inspect its saved branches and refs, including run_branch, rebase_branch, source_ref and publication_marker when present. Inspect their contents and any work you want to keep before removing anything. If a Git rebase is active, abort it only after confirming that it belongs to this MBM run. For a current state file, compare rebase_branch with the active rebase's head-name in the worktree's Git directory. Do not abort an unrelated rebase or delete refs whose ownership is uncertain.

When the private rebase branch still matches its saved source commit and no Git rebase is active, MBM cannot distinguish an aborted rebase from an externally completed no-op rebase and refuses to resume. Resolve that run manually.

After preserving the work you need and resolving any owned Git operation, remove the state file at the path printed above to allow a new run. Remove private run refs only if you have confirmed that they belong to the abandoned run and are no longer needed. Do not delete integration, update, feature, or other user refs as part of cleanup.

Development

git clone https://gitlab.com/alelec/marshal-branch-manager.git
cd marshal-branch-manager
uv sync
uv run pytest
uv run pre-commit install        # ruff + mypy on commit
uv run pre-commit run --all-files

Versions come from git tags via hatch-vcs. Protected tag pipelines build the package and publish it to PyPI. GitLab CI/CD is configured as a trusted publisher on PyPI, using .gitlab-ci.yml as the pipeline file.

License

MIT

Metadata

Release files for marshal-branch-manager 5.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for marshal-branch-manager 5.0.1
File Size Uploaded Provenance Actions
marshal_branch_manager-5.0.1.tar.gz 205.7 kB Without provenance Details for marshal_branch_manager-5.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for marshal-branch-manager 5.0.1
File Interpreter ABI Platform Actions
marshal_branch_manager-5.0.1-py3-none-any.whl Python 3 none any Details for marshal_branch_manager-5.0.1-py3-none-any.whl

Total release size: 249.2 kB

Release files / marshal_branch_manager-5.0.1.tar.gz

Download URL marshal_branch_manager-5.0.1.tar.gz
Size 205.7 kB
Tags Source
SHA-256 checksum
How to use checksums
a02d5708641cc1c5ecf5f3a6b503700522b5ab8b6979c4844596c6fb71989921
BLAKE2b-256 checksum
How to use checksums
62836228a8a163540eebf9929c4d0738767a039bff0843d2f4bf5fb370c778ec
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / marshal_branch_manager-5.0.1-py3-none-any.whl

Download URL marshal_branch_manager-5.0.1-py3-none-any.whl
Size 43.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0aca20a95d059441ecc3f61349cfdb29a4cb95482ce0bc3c26aaf9936d462cbb
BLAKE2b-256 checksum
How to use checksums
20b0e4a6c1a0ff8dc9d6d6b87150d86228b51e398f56fa8a517ac9e7f635e4e8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for marshal-branch-manager 5.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page