marshal-branch-manager 4.0.0__tar.gz

marshal_branch_manager-4.0.0/.cache/pip/http-v2/3/a/9/0/a/3a90a4636ff8a0016bbb5ae63eff66f7ed5689db21aa1584b5f7036f.body

@@ -0,0 +1,355 @@
+Metadata-Version: 2.4
+Name: uv
+Version: 0.13.7
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Software Development :: Libraries
+License-File: LICENSE-APACHE
+License-File: LICENSE-MIT
+Summary: An extremely fast Python package and project manager, written in Rust.
+Keywords: uv,requirements,packaging
+Home-Page: https://pypi.org/project/uv/
+Author-email: "Astral Software Inc." <hey@astral.sh>
+License-Expression: MIT OR Apache-2.0
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Changelog, https://github.com/astral-sh/uv/blob/main/CHANGELOG.md
+Project-URL: Discord, https://discord.gg/astral-sh
+Project-URL: Documentation, https://docs.astral.sh/uv
+Project-URL: Releases, https://github.com/astral-sh/uv/releases
+Project-URL: Repository, https://github.com/astral-sh/uv
+
+# uv
+
+An extremely fast Python package and project manager, written in Rust.
+
+<p align="center">
+  <img alt="Shows a bar chart with benchmark results." src="https://github.com/astral-sh/uv/assets/1309177/629e59c0-9c6e-4013-9ad4-adb2bcf5080d">
+</p>
+
+<p align="center">
+  <i>Installing <a href="https://trio.readthedocs.io/">Trio</a>'s dependencies with a warm cache.</i>
+</p>
+
+## Highlights
+
+- A single tool to replace `pip`, `pip-tools`, `pipx`, `poetry`, `pyenv`, `twine`, `virtualenv`, and
+  more.
+- [10-100x faster](https://github.com/astral-sh/uv/blob/main/BENCHMARKS.md) than `pip`.
+- Provides [comprehensive project management](https://github.com/astral-sh/uv/blob/0.13.7/README.md#projects), with a
+  [universal lockfile](https://docs.astral.sh/uv/concepts/projects/layout#the-lockfile).
+- [Runs scripts](https://github.com/astral-sh/uv/blob/0.13.7/README.md#scripts), with support for
+  [inline dependency metadata](https://docs.astral.sh/uv/guides/scripts#declaring-script-dependencies).
+- [Installs and manages](https://github.com/astral-sh/uv/blob/0.13.7/README.md#python-versions) Python versions.
+- [Runs and installs](https://github.com/astral-sh/uv/blob/0.13.7/README.md#tools) tools published as Python packages.
+- Includes a [pip-compatible interface](https://github.com/astral-sh/uv/blob/0.13.7/README.md#the-pip-interface) for a performance boost with a familiar
+  CLI.
+- Supports Cargo-style [workspaces](https://docs.astral.sh/uv/concepts/projects/workspaces) for
+  scalable projects.
+- Disk-space efficient, with a [global cache](https://docs.astral.sh/uv/concepts/cache) for
+  dependency deduplication.
+- Installable without Rust or Python via `curl` or `pip`.
+- Supports macOS, Linux, and Windows.
+
+uv is backed by [Astral](https://astral.sh), the creators of
+[Ruff](https://github.com/astral-sh/ruff) and [ty](https://github.com/astral-sh/ty).
+
+## Installation
+
+Install uv with our standalone installers:
+
+```bash
+# On macOS and Linux.
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+```bash
+# On Windows.
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+Or, from [PyPI](https://pypi.org/project/uv/):
+
+```bash
+# With pip.
+pip install uv
+```
+
+```bash
+# Or pipx.
+pipx install uv
+```
+
+If installed via the standalone installer, uv can update itself to the latest version:
+
+```bash
+uv self update
+```
+
+See the [installation documentation](https://docs.astral.sh/uv/getting-started/installation/) for
+details and alternative installation methods.
+
+## Documentation
+
+uv's documentation is available at [docs.astral.sh/uv](https://docs.astral.sh/uv).
+
+Additionally, the command line reference documentation can be viewed with `uv help`.
+
+## Features
+
+### Projects
+
+uv manages project dependencies and environments, with support for lockfiles, workspaces, and more,
+similar to `rye` or `poetry`:
+
+```console
+$ uv init example
+Initialized project `example` at `/home/user/example`
+
+$ cd example
+
+$ uv add ruff
+Creating virtual environment at: .venv
+Resolved 2 packages in 170ms
+   Built example @ file:///home/user/example
+Prepared 2 packages in 627ms
+Installed 2 packages in 1ms
+ + example==0.1.0 (from file:///home/user/example)
+ + ruff==0.5.0
+
+$ uv run ruff check
+All checks passed!
+
+$ uv lock
+Resolved 2 packages in 0.33ms
+
+$ uv sync
+Resolved 2 packages in 0.70ms
+Checked 1 package in 0.02ms
+```
+
+See the [project documentation](https://docs.astral.sh/uv/guides/projects/) to get started.
+
+uv also supports building and publishing projects, even if they're not managed with uv. See the
+[publish guide](https://docs.astral.sh/uv/guides/publish/) to learn more.
+
+### Scripts
+
+uv manages dependencies and environments for single-file scripts.
+
+Create a new script and add inline metadata declaring its dependencies:
+
+```console
+$ echo 'import requests; print(requests.get("https://astral.sh"))' > example.py
+
+$ uv add --script example.py requests
+Updated `example.py`
+```
+
+Then, run the script in an isolated virtual environment:
+
+```console
+$ uv run example.py
+Reading inline script metadata from: example.py
+Installed 5 packages in 12ms
+<Response [200]>
+```
+
+See the [scripts documentation](https://docs.astral.sh/uv/guides/scripts/) to get started.
+
+### Tools
+
+uv executes and installs command-line tools provided by Python packages, similar to `pipx`.
+
+Run a tool in an ephemeral environment using `uvx` (an alias for `uv tool run`):
+
+```console
+$ uvx pycowsay 'hello world!'
+Resolved 1 package in 167ms
+Installed 1 package in 9ms
+ + pycowsay==0.0.0.2
+  """
+
+  ------------
+< hello world! >
+  ------------
+   \   ^__^
+    \  (oo)\_______
+       (__)\       )\/\
+           ||----w |
+           ||     ||
+```
+
+Install a tool with `uv tool install`:
+
+```console
+$ uv tool install ruff
+Resolved 1 package in 6ms
+Installed 1 package in 2ms
+ + ruff==0.5.0
+Installed 1 executable: ruff
+
+$ ruff --version
+ruff 0.5.0
+```
+
+See the [tools documentation](https://docs.astral.sh/uv/guides/tools/) to get started.
+
+### Python versions
+
+uv installs Python and allows quickly switching between versions.
+
+Install multiple Python versions:
+
+```console
+$ uv python install 3.12 3.13 3.14
+Installed 3 versions in 972ms
+ + cpython-3.12.12-macos-aarch64-none (python3.12)
+ + cpython-3.13.9-macos-aarch64-none (python3.13)
+ + cpython-3.14.0-macos-aarch64-none (python3.14)
+
+```
+
+Download Python versions as needed:
+
+```console
+$ uv venv --python 3.12.0
+Using Python 3.12.0
+Creating virtual environment at: .venv
+Activate with: source .venv/bin/activate
+
+$ uv run --python pypy@3.8 -- python --version
+Python 3.8.16 (a9dbdca6fc3286b0addd2240f11d97d8e8de187a, Dec 29 2022, 11:45:30)
+[PyPy 7.3.11 with GCC Apple LLVM 13.1.6 (clang-1316.0.21.2.5)] on darwin
+Type "help", "copyright", "credits" or "license" for more information.
+>>>>
+```
+
+Use a specific Python version in the current directory:
+
+```console
+$ uv python pin 3.11
+Pinned `.python-version` to `3.11`
+```
+
+See the [Python installation documentation](https://docs.astral.sh/uv/guides/install-python/) to get
+started.
+
+### The pip interface
+
+uv provides a drop-in replacement for common `pip`, `pip-tools`, and `virtualenv` commands.
+
+uv extends their interfaces with advanced features, such as dependency version overrides,
+platform-independent resolutions, reproducible resolutions, alternative resolution strategies, and
+more.
+
+Migrate to uv without changing your existing workflows — and experience a 10-100x speedup — with the
+`uv pip` interface.
+
+Compile requirements into a platform-independent requirements file:
+
+```console
+$ uv pip compile requirements.in \
+   --universal \
+   --output-file requirements.txt
+Resolved 43 packages in 12ms
+```
+
+Create a virtual environment:
+
+```console
+$ uv venv
+Using Python 3.12.3
+Creating virtual environment at: .venv
+Activate with: source .venv/bin/activate
+```
+
+Install the locked requirements:
+
+```console
+$ uv pip sync requirements.txt
+Resolved 43 packages in 11ms
+Installed 43 packages in 208ms
+ + babel==2.15.0
+ + black==24.4.2
+ + certifi==2024.7.4
+ ...
+```
+
+See the [pip interface documentation](https://docs.astral.sh/uv/pip/index/) to get started.
+
+## Contributing
+
+We are passionate about supporting contributors of all levels of experience and would love to see
+you get involved in the project. See the
+[contributing guide](https://github.com/astral-sh/uv?tab=contributing-ov-file#contributing) to get
+started.
+
+## FAQ
+
+#### How do you pronounce uv?
+
+It's pronounced as "you - vee" ([`/juː viː/`](https://en.wikipedia.org/wiki/Help:IPA/English#Key))
+
+#### How should I stylize uv?
+
+Just "uv", please. See the [style guide](https://github.com/astral-sh/uv/blob/0.13.7/STYLE.md#styling-uv) for details.
+
+#### What platforms does uv support?
+
+See uv's [platform support](https://docs.astral.sh/uv/reference/platforms/) document.
+
+#### Is uv ready for production?
+
+Yes, uv is stable and widely used in production. See uv's
+[versioning policy](https://docs.astral.sh/uv/reference/versioning/) document for details.
+
+## Acknowledgements
+
+uv's dependency resolver uses [PubGrub](https://github.com/pubgrub-rs/pubgrub) under the hood. We're
+grateful to the PubGrub maintainers, especially [Jacob Finkelman](https://github.com/Eh2406), for
+their support.
+
+uv's Git implementation is based on [Cargo](https://github.com/rust-lang/cargo).
+
+Some of uv's optimizations are inspired by the great work we've seen in [pnpm](https://pnpm.io/),
+[Orogene](https://github.com/orogene/orogene), and [Bun](https://github.com/oven-sh/bun). We've also
+learned a lot from Nathaniel J. Smith's [Posy](https://github.com/njsmith/posy) and adapted its
+[trampoline](https://github.com/njsmith/posy/tree/main/src/trampolines/windows-trampolines/posy-trampoline)
+for Windows support.
+
+## License
+
+uv is licensed under either of
+
+- Apache License, Version 2.0, ([LICENSE-APACHE](https://github.com/astral-sh/uv/blob/0.13.7/LICENSE-APACHE) or
+  <https://www.apache.org/licenses/LICENSE-2.0>)
+- MIT license ([LICENSE-MIT](https://github.com/astral-sh/uv/blob/0.13.7/LICENSE-MIT) or <https://opensource.org/licenses/MIT>)
+
+at your option.
+
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in uv
+by you, as defined in the Apache-2.0 license, shall be dually licensed as above, without any
+additional terms or conditions.
+
+<div align="center">
+  <a target="_blank" href="https://astral.sh" style="background:none">
+    <img src="https://raw.githubusercontent.com/astral-sh/uv/main/assets/svg/Astral.svg" alt="Made by Astral">
+  </a>
+</div>
+

marshal_branch_manager-4.0.0/.cache/pip/selfcheck/fe300af6f7d708c14827daac3afc81fbb8306b73de8dd6e3f1f8ea3b

@@ -0,0 +1 @@
+{"key":"/usr/local","last_check":"2026-11-04T01:42:15.732142+00:00","pypi_version":"26.3"}

marshal_branch_manager-4.0.0/.gitignore

@@ -0,0 +1,25 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Testing
+.coverage
+coverage.xml
+.pytest_cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# uv
+uv.lock
+src/marshal_branch_manager/_version.py

marshal_branch_manager-4.0.0/.gitlab-ci.yml

@@ -0,0 +1,61 @@
+image: python:3.11-slim
+
+variables:
+  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
+  GIT_DEPTH: 0  # Fetch full git history including tags for hatch-vcs
+
+cache:
+  key: pip
+  paths:
+    - .cache/pip
+
+stages:
+  - lint
+  - test
+  - build
+  - deploy
+
+before_script:
+  - apt-get update -qq && apt-get install -y -qq git  # Required for hatch-vcs
+  - pip install 'uv>=0.8.18'
+  - git fetch --tags  # Ensure tags are available for hatch-vcs
+  - uv sync
+
+lint:
+  stage: lint
+  script:
+    - uv run ruff check .
+    - uv run ruff format --check .
+    - uv run mypy src/marshal_branch_manager
+
+test:
+  stage: test
+  script:
+    - uv run pytest tests/ -v --cov=marshal_branch_manager --cov-report=xml --cov-report=term
+  coverage: '/TOTAL\s+\d+\s+\d+\s+(\d+)%/'
+  artifacts:
+    reports:
+      coverage_report:
+        coverage_format: cobertura
+        path: coverage.xml
+
+build:
+  stage: build
+  script:
+    - uv build
+  artifacts:
+    paths:
+      - dist/*.whl
+      - dist/*.tar.gz
+
+deploy:
+  stage: deploy
+  dependencies:
+    - build
+  rules:
+    - if: '$CI_COMMIT_TAG && $CI_COMMIT_REF_PROTECTED == "true"'
+  id_tokens:
+    PYPI_ID_TOKEN:
+      aud: pypi
+  script:
+    - uv publish --trusted-publishing always

marshal_branch_manager-4.0.0/.pre-commit-config.yaml

@@ -0,0 +1,25 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v2.3.1
+    hooks:
+      - id: mypy
+        additional_dependencies: [pydantic>=2.0, cyclopts>=3.0, tomli-w>=1.0]
+        args: [--strict]
+        exclude: ^tests/
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-json
+      - id: check-toml
+      - id: check-merge-conflict

marshal_branch_manager-4.0.0/.python-version

@@ -0,0 +1 @@
+3.11

marshal_branch_manager-4.0.0/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## Unreleased
+
+- Renamed the project to `marshal-branch-manager` and the Python module to `marshal_branch_manager`. The `mbm` command, `mbm.toml` configuration, and `MBM` trailers are unchanged.
+- The new distribution does not provide the `micropython-branch-manager` command. Use `mbm` instead.

marshal_branch_manager-4.0.0/CLAUDE.md

@@ -0,0 +1,186 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+`marshal-branch-manager` (command: `mbm`, module: `marshal_branch_manager`) is a Python CLI tool that automates maintaining a fork with multiple feature branches integrated on top of upstream. It manages rebasing integration branches with preserved merge commits, adding PRs, tracking branch metadata in TOML config, and generating GitLab MR URLs.
+
+## Development Commands
+
+### Setup
+```bash
+uv sync
+```
+
+### Running the tool locally
+```bash
+uv run mbm --help
+uv run mbm init --submodule ./micropython
+uv run mbm rebase                 # target: --target, config 'target', upstream/HEAD, upstream/master
+uv run mbm add-pr 12345
+uv run mbm sync <gh-username>
+uv run mbm config
+```
+
+### Testing
+```bash
+# Run all tests with coverage
+uv run pytest tests/ -v --cov=marshal_branch_manager --cov-report=xml --cov-report=term
+
+# Run specific test file
+uv run pytest tests/test_specific.py -v
+```
+
+### Linting and Type Checking
+```bash
+# Run all lint/type checks and formatting (recommended)
+uv run pre-commit run --all-files
+
+# Run ruff linter
+uv run ruff check .
+
+# Auto-fix ruff issues
+uv run ruff check . --fix
+
+# Format code
+uv run ruff format .
+
+# Type check with mypy
+uv run mypy src/marshal_branch_manager
+```
+
+### Pre-commit Hooks
+```bash
+# Install hooks
+uv run pre-commit install
+
+# Run on all files
+uv run pre-commit run --all-files
+```
+
+### Building
+```bash
+# Build wheel and sdist
+uv build
+```
+
+## Architecture
+
+### Core Workflow Model
+
+The tool supports two modes:
+
+1. **Config mode** - `mbm.toml` (usually in the parent repo root) holds one `[[submodules]]` entry per managed repo, each with a `path` relative to the config. The legacy flat format (top-level `path`/`submodule_path` and `[[branches]]`) still loads. User commits the config file manually.
+2. **Standalone mode** — No config file. Branch metadata is derived from git trailers in merge commit messages.
+
+Key concepts:
+- **Integration branch** — A branch (typically `main`) containing merge commits of feature branches on top of upstream
+- **Feature branches** — Individual branches from upstream PRs or local development
+- **Update branches** — Temporary branches created during rebase operations for GitLab MR creation
+- **Branch metadata** — Stored as git trailers (`MBM-PR`, `MBM-URL`, `MBM-Author`) in merge commit messages, and optionally in TOML config
+
+### Module Responsibilities
+
+- **cli.py** - CLI using cyclopts. Resolves config path (`--config` flag or `find_config()` walk-up) and the submodule (`--submodule`/`-s` selector or CWD). Resolves the rebase target.
+- **config.py** - Pydantic models (`MBMConfig`, `SubmoduleConfig`, `BranchConfig`). TOML serialization via `tomllib`/`tomli-w`. Config discovery via `find_config()`.
+- **git.py** - Git operations wrapper (`GitRepo` class). Includes conflict detection, rerere support (`configure_rerere`, `is_rerere_enabled`), worktree management, auto-continue rebase, upstream repo/default-branch detection (`upstream_github_repo`, `default_target`) and push remote resolution (`resolve_push_remote`).
+- **trailers.py** — Git trailer support. `format_merge_message()` builds commit messages with MBM trailers. `parse_trailers_from_message()` and `extract_branches_with_metadata()` parse them back.
+- **branch_sync.py** — Branch detection from merge commit subjects. Synchronizes config with detected branches.
+- **rebase.py** — Orchestrates rebase workflow via `RebaseManager`. Trains rerere before rebuilding, uses trailers in merge messages, resolves remotes at runtime.
+- **pr.py** — PR addition workflow via `PRManager`. Fetches PR from upstream, merges with trailers, updates config.
+- **rerere.py** — `RerereTrainer` class. Trains git rerere from an existing integration branch by replaying merges in a temporary worktree.
+- **github.py** — GitHub API wrapper using `gh` CLI for PR metadata lookup.
+- **update_branch.py** — Update branch creation and GitLab MR URL generation.
+- **exceptions.py** — Custom exceptions for git conflicts, divergence, and errors.
+
+### Git Operations Flow
+
+**Rebase workflow:**
+1. Load config, resolve target (`--target`, config `target`, `upstream/HEAD`, `upstream/master`)
+2. Fetch from remotes (unless `--local`)
+3. Skip branches whose PR is merged (GitHub repo from the `upstream` remote, default `micropython/micropython`); fill missing `author` from the PR
+4. Train rerere from existing integration branch (if rerere enabled)
+5. Create update branch from target
+6. For each branch: fetch PR, rebase onto target (`--onto target <upstream default>` when target is behind upstream's default branch), merge into update branch with trailers
+7. Unless `update_feature_branches` is off: move feature branch refs, set tracking and push them to the head owner's fork
+8. Push update branch to GitLab and print the MR URL
+9. With `--apply`, reset the integration branch to the update branch
+
+**PR addition workflow:**
+1. Parse PR identifier (number, URL, or branch name)
+2. Fetch PR metadata using `gh` CLI
+3. Create update branch from integration branch
+4. Fetch PR branch from upstream
+5. Merge PR branch with trailers in commit message
+6. Update TOML config with new branch entry
+7. Generate GitLab MR URL
+
+### Rerere Integration
+
+Git rerere is configured automatically by `mbm init`. Before each rebase:
+1. A temporary worktree is created at the upstream base
+2. Each branch is merged in order, with conflicts resolved using the existing integration branch's tree
+3. rerere records each conflict resolution
+4. During the actual rebase, rerere auto-applies known resolutions
+5. If all conflicts in a step are resolved, the rebase auto-continues
+
+### Push Strategy
+
+- **Feature branches** - Pushed to the remote matching the branch `author` (fork owner), or the `pr_url` owner when that URL is a fork. Never `upstream` or a remote for the upstream repo; skipped with a warning when no remote matches.
+- **Integration/update branches** — Pushed to GitLab (remote detected by URL pattern)
+
+### Error Handling
+
+- `RebaseConflictError` — Raised when rebase encounters unresolvable conflicts (after rerere attempt)
+- `MergeConflictError` — Raised when PR merge encounters conflicts
+- `RemoteDivergenceError` — Raised when remote branch has diverged from local
+- `WorkingTreeDirtyError` — Raised when working tree has uncommitted changes
+
+Conflict detection uses `git status --porcelain` to identify files with conflict markers (`UU`, `AA`, `DD` prefixes).
+
+## Configuration File
+
+`mbm.toml` structure:
+```toml
+# marshal-branch-manager (mbm)
+# Install: pip install marshal-branch-manager
+#          or: uv tool install marshal-branch-manager
+# Usage:   mbm --help
+
+[[submodules]]
+path = "src/micropython"
+integration_branch = "main"
+target = "v1.27.0"               # optional
+update_feature_branches = true   # optional
+
+[[submodules.branches]]
+name = "feature-branch-1"
+pr_url = "https://github.com/micropython/micropython/pull/12345"
+pr_number = 12345
+title = "Add feature X"
+author = "andrewleech"
+```
+
+## Merge Commit Trailer Format
+
+```
+Merge branch 'feature-x'
+
+Add feature X
+
+MBM-PR: 12345
+MBM-URL: https://github.com/micropython/micropython/pull/12345
+MBM-Author: username
+```
+
+## Dependencies
+
+- **pydantic** — Config models with validation
+- **cyclopts** — CLI framework
+- **tomli-w** — TOML writing
+- **GitHub CLI (`gh`)** — PR metadata lookup (optional)
+
+## Testing Notes
+
+Test files are in `tests/`. The project uses pytest with coverage reporting configured in `pyproject.toml`.