Skip to content

livery.workshop._submit

livery.workshop._submit

fm submit: get the branch onto the remote, verified, and landed.

Local gate first (the gate the CI legs run, so a red gate costs zero network calls), then the closes-link resolution with existence probes, disarm-before-push, push, find-or-open with the title rules, arm per the arming ladder, and follow until it lands or says what stopped it. Exits 10 and 17 self-heal by integrating the base and re-submitting; every other code surfaces unchanged, because skills, hooks, and humans branch on them.

fm abandon is the exit: disarm, close the pull request, delete both branches, return to the base. fm submit.merge merges a green pull request that was deliberately left unarmed, and refuses anything less than green. fm submit.arm and fm submit.disarm set and take off a pull request's auto-merge and leave it open. The three act on this branch's pull request, or on the one a number names, from any checkout.

The arming ladder, highest wins: --armed/--no-armed for one invocation; WORKSHOP_AUTOMERGE as the per-user standing preference; the workspace contract's [ci] automerge as committed repo policy; off. The ladder is footman's option ladder; only the printed reason is derived here.

Classes:

Name Description
Plan

Everything a push and pull request need, validated, no network.

Functions:

Name Description
ci_automerge

The committed repo policy: the workspace contract's [ci] automerge.

arming_reason

One sentence naming the ladder level that decided armed.

branch_issue

The issue number a <type>/<number>-slug branch carries, or None.

parse_number

Read the issue or pull request number token spells; None when it spells none.

with_closes

body with its Closes #number trailer, present exactly once.

resolve_closes

The issue submit will link, per the three guards.

prepare

Validate the branch and assemble the pull request shape.

resolve_base

The branch the pull request targets.

abort_if_merged

Stop before pushing into a pull request that already merged.

disarm_before_push

Disarm an armed pull request before pushing to it.

label_every_runner

Put livery.workshop.EVERY_RUNNER_LABEL on pull request number.

push_and_pr

Disarm, push, find-or-open the pull request, label and arm as asked.

refuse_ambiguous_title

Refuse a defaulted title on a branch more than one commit ahead.

submit_flow

The whole submitting act; returns the pull request number.

submit_default

Gate, push, open-or-reuse the PR, arm, and watch it land.

forge_failures_named

Fail with the forge's own words when it refuses or does not answer.

worktree_for

The linked worktree holding branch; "" when none does or root does.

only_local_work

Why branch holds work that exists nowhere else; "" when safe.

merged_pull_request

The merged pull request branch was the head of, or None.

teardown_branch

The one branch teardown every stop verb wears; idempotent.

abandon_flow

Give the feature up: close the PR, delete both branches; idempotent.

abandon

Give up a feature: close the PR, delete the branches, return to base.

pull_request_named

Find the pull request ref numbers; this branch's when ref is empty.

arm_flow

Arm pr to merge when green, as fm submit --armed arms; idempotent.

disarm_flow

Take auto-merge off pr and leave it open; idempotent.

merge_flow

Merge the pull request pr as soon as possible; a merged one is done.

submit_merge

Merge a PR as soon as possible: this branch's, or the one numbered.

submit_arm

Arm a PR to merge when green: this branch's, or the one numbered.

submit_disarm

Take auto-merge off a PR and leave it open: this branch's, or the one numbered.

Attributes:

Name Type Description
submit

submit module-attribute

submit = group('submit', help='Gate, push, open-or-reuse the PR, arm, and watch it land')

Plan dataclass

Plan(branch: str, base: str, title: str, body: str, title_given: bool, body_given: bool = False, subjects: tuple[str, ...] = ())

Everything a push and pull request need, validated, no network.

Attributes:

Name Type Description
branch str

The feature branch being submitted.

base str

The branch the pull request targets.

title str

The pull request title, validated.

body str

The pull request body.

title_given bool

Whether the title came from the caller. A defaulted title tracks HEAD, so only a given title may overwrite an existing pull request's.

body_given bool

Whether the body came from the caller; the same rule for an existing pull request's body.

subjects tuple[str, ...]

The subjects of the commits the branch carries beyond origin/<base>, read once for the checks that need them.

branch instance-attribute

branch: str

base instance-attribute

base: str

title instance-attribute

title: str

body instance-attribute

body: str

title_given instance-attribute

title_given: bool

body_given class-attribute instance-attribute

body_given: bool = False

subjects class-attribute instance-attribute

subjects: tuple[str, ...] = ()

ci_automerge

ci_automerge() -> bool

The committed repo policy: the workspace contract's [ci] automerge.

Source code in packages/workshop/src/livery/workshop/_submit.py
def ci_automerge() -> bool:
    """The committed repo policy: the workspace contract's ``[ci] automerge``."""
    root = workspace_root()
    if root is None:
        return False
    contract = load_contract(root / "workshop.toml")
    return bool((contract.get("ci") or {}).get("automerge", False))

arming_reason

arming_reason(*, armed: bool, flag_given: bool) -> str

One sentence naming the ladder level that decided armed.

Source code in packages/workshop/src/livery/workshop/_submit.py
def arming_reason(*, armed: bool, flag_given: bool) -> str:
    """One sentence naming the ladder level that decided *armed*."""
    if flag_given:
        return f"--{'' if armed else 'no-'}armed (this invocation)"
    if os.environ.get("WORKSHOP_AUTOMERGE") is not None:
        return "WORKSHOP_AUTOMERGE (per-user standing preference)"
    root = workspace_root()
    if root is not None:
        contract = load_contract(root / "workshop.toml")
        if "automerge" in (contract.get("ci") or {}):
            return "[ci] automerge in workshop.toml (committed repo policy)"
    return "the default (auto-merge is opt-in; nothing configured)"

branch_issue

branch_issue(branch: str) -> int | None

The issue number a <type>/<number>-slug branch carries, or None.

Source code in packages/workshop/src/livery/workshop/_submit.py
def branch_issue(branch: str) -> int | None:
    """The issue number a ``<type>/<number>-slug`` branch carries, or None."""
    match = _BRANCH_ISSUE_RE.match(branch)
    return int(match.group(1)) if match else None

parse_number

parse_number(token: str) -> int | None

Read the issue or pull request number token spells; None when it spells none.

The one rule every verb that takes a number from a person reads it by. A leading # is accepted, as the forges print a number, so #123 and 123 are the same number. Anything else that is not all decimal digits spells no number.

Source code in packages/workshop/src/livery/workshop/_submit.py
def parse_number(token: str) -> int | None:
    """Read the issue or pull request number *token* spells; None when it spells none.

    The one rule every verb that takes a number from a person reads it
    by. A leading ``#`` is accepted, as the forges print a number, so
    ``#123`` and ``123`` are the same number. Anything else that is
    not all decimal digits spells no number.
    """
    bare = token.lstrip("#")
    return int(bare) if bare.isdecimal() else None

with_closes

with_closes(body: str, number: int) -> str

body with its Closes #number trailer, present exactly once.

Source code in packages/workshop/src/livery/workshop/_submit.py
def with_closes(body: str, number: int) -> str:
    """*body* with its ``Closes #number`` trailer, present exactly once."""
    trailer = f"Closes #{number}"
    if trailer in body:
        return body
    return f"{body}\n\n{trailer}" if body else trailer

resolve_closes

resolve_closes(repo: Repository, branch: str, closes_flag: int) -> int | None

The issue submit will link, per the three guards.

The flag beats the branch-name parse; a disagreement is printed, never silently resolved; and the issue must exist before Closes #N is written. A branch-parsed number that does not exist drops the link with a note (plain branches always work); an explicit --closes that does not exist refuses.

Source code in packages/workshop/src/livery/workshop/_submit.py
def resolve_closes(repo: Repository, branch: str, closes_flag: int) -> int | None:
    """The issue submit will link, per the three guards.

    The flag beats the branch-name parse; a disagreement is printed,
    never silently resolved; and the issue must exist before
    ``Closes #N`` is written. A branch-parsed number that does not
    exist drops the link with a note (plain branches always work); an
    explicit ``--closes`` that does not exist refuses.
    """
    parsed = branch_issue(branch)
    if closes_flag:
        if parsed is not None and parsed != closes_flag:
            print(f"  note: --closes {closes_flag} beats the branch's #{parsed}")
        if repo.issue.get(closes_flag) is None:
            fail(f"--closes {closes_flag} refused: the issue does not exist")
        return closes_flag
    if parsed is None:
        return None
    if repo.issue.get(parsed) is None:
        print(
            f"  note: branch names issue #{parsed}, which does not exist;"
            " submitting without a Closes link"
        )
        return None
    return parsed

prepare

prepare(root: Path, *, title: str = '', body: str = '', base: str = 'main', branch: str = '') -> Plan

Validate the branch and assemble the pull request shape.

branch is the checked-out branch when the caller read it already; read here otherwise.

Source code in packages/workshop/src/livery/workshop/_submit.py
def prepare(
    root: Path,
    *,
    title: str = "",
    body: str = "",
    base: str = "main",
    branch: str = "",
) -> Plan:
    """Validate the branch and assemble the pull request shape.

    *branch* is the checked-out branch when the caller read it already;
    read here otherwise.
    """
    branch = branch or git.current_branch(root)
    if not branch or branch == base:
        fail(
            f"not on a feature branch (on {branch or '(detached)'!r}, base is"
            f" {base!r}): create a <type>/<slug> branch first"
        )
    if not _BRANCH_RE.match(branch) and not branch.startswith("workflow/"):
        # Reserved workflow branches are the engine's, named by their
        # workflow identity, outside the feature grammar on purpose.
        fail(
            f"branch {branch!r} does not match <type>/<slug>"
            f" (types: {', '.join(_BRANCH_TYPES)})"
        )
    # A merge commit (the engine's MERGE_DEFAULT, `fm integrate`) can
    # be HEAD, and "Merge branch ..." is never the intent: the last
    # real subject is. The squash erases the merge commits anyway.
    default_title, default_body = git.head_message(root)
    subjects = tuple(git.subjects_ahead(root, base))
    if not title and default_title.startswith("Merge "):
        real = [subject for subject in subjects if not subject.startswith("Merge ")]
        if real:
            default_title = real[-1]
    resolved_title = title or default_title
    if not _TITLE_RE.match(resolved_title):
        fail(
            f"PR title rejected: {resolved_title!r}\n"
            '  pass a valid one: --title="type(scope): subject"'
        )
    return Plan(
        branch=branch,
        base=base,
        title=resolved_title,
        body=body or default_body,
        title_given=bool(title),
        body_given=bool(body),
        subjects=subjects,
    )

resolve_base

resolve_base(root: Path, base: str, *, given: bool, branch: str = '') -> str

The branch the pull request targets.

A --base flag wins. Otherwise the parent fm start --from recorded for the branch is the target while origin still has it, and base once it is gone: a merged parent's branch is deleted, and the forge retargets the child's pull request to the parent's own base at that moment.

Origin is asked for the branch, never the remote-tracking ref: a plain fetch does not prune, so the tracking ref of a branch the forge deleted at the merge survives, and a pull request against a branch that is gone is refused with a validation error rather than a sentence.

Source code in packages/workshop/src/livery/workshop/_submit.py
def resolve_base(root: Path, base: str, *, given: bool, branch: str = "") -> str:
    """The branch the pull request targets.

    A ``--base`` flag wins. Otherwise the parent ``fm start --from``
    recorded for the branch is the target while origin still has it,
    and *base* once it is gone: a merged parent's branch is deleted,
    and the forge retargets the child's pull request to the parent's
    own base at that moment.

    Origin is asked for the branch, never the remote-tracking ref: a
    plain fetch does not prune, so the tracking ref of a branch the
    forge deleted at the merge survives, and a pull request against a
    branch that is gone is refused with a validation error rather than
    a sentence.
    """
    if given:
        return base
    parent, _tip = _stack.stack(root, branch or git.current_branch(root))
    if not parent:
        return base
    if parent in git.remote_branches(root, parent):
        print(f"  base: {parent}, the parent `{footman.prog()} start --from` recorded")
        return parent
    print(f"  base: {base}; the recorded parent {parent} is gone from origin (merged)")
    return base

abort_if_merged

abort_if_merged(repo: Repository, root: Path, branch: str) -> int | None

Stop before pushing into a pull request that already merged.

The merge took the pre-push head, so pushing on would open a second pull request carrying the follow-up. That is only true when the local branch still carries the merged head: a branch with the same name cut fresh off the merged base is a new cycle (the release train reuses its reserved branch name every release), and it proceeds. Detection is best-effort: a merged pull request whose head branch is already deleted is found by head sha instead, and one invisible both ways surfaces later as the stray-PR symptom the message names.

Returns the merged pull request's number when HEAD is the head it merged: there is nothing to push, and the re-run's job is to report the merge. None when no merged pull request claims the branch or the branch is a fresh cycle.

Source code in packages/workshop/src/livery/workshop/_submit.py
def abort_if_merged(repo: Repository, root: Path, branch: str) -> int | None:
    """Stop before pushing into a pull request that already merged.

    The merge took the pre-push head, so pushing on would open a
    second pull request carrying the follow-up. That is only true
    when the local branch still carries the merged head: a branch
    with the same name cut fresh off the merged base is a new cycle
    (the release train reuses its reserved branch name every
    release), and it proceeds. Detection is best-effort: a merged
    pull request whose head branch is already deleted is found by
    head sha instead, and one invisible both ways surfaces later as
    the stray-PR symptom the message names.

    Returns the merged pull request's number when HEAD is the head it
    merged: there is nothing to push, and the re-run's job is to
    report the merge. None when no merged pull request claims the
    branch or the branch is a fresh cycle.
    """
    pr = merged_pull_request(repo, root, branch)
    if pr is None:
        return None
    if pr.head_sha and not git.is_ancestor(root, pr.head_sha, "HEAD"):
        return None
    if pr.head_sha and pr.head_sha == git.head_sha(root):
        return pr.number
    fail(
        f"PR #{pr.number} for {branch} has already merged.\n"
        "  Your commit is NOT in it and has not been pushed: the merge took"
        " the pre-push head.\n"
        "  Start a fresh branch off the merged base; check for a stray PR"
        " before re-running."
    )

disarm_before_push

disarm_before_push(repo: Repository, root: Path, branch: str) -> int | None

Disarm an armed pull request before pushing to it.

A push to an armed pull request races auto-merge: the merge can take the pre-push head. The disarm narrows that window; it cannot close it, so the merged check runs after it on every path. An unreadable arming state must not block the submit; the push itself surfaces a real transport problem. Returns what livery.workshop._submit.abort_if_merged returns: the number of a pull request that already merged this very head, else None.

Source code in packages/workshop/src/livery/workshop/_submit.py
def disarm_before_push(repo: Repository, root: Path, branch: str) -> int | None:
    """Disarm an armed pull request before pushing to it.

    A push to an armed pull request races auto-merge: the merge can
    take the pre-push head. The disarm narrows that window; it cannot
    close it, so the merged check runs after it on every path. An
    unreadable arming state must not block the submit; the push itself
    surfaces a real transport problem. Returns what
    livery.workshop._submit.abort_if_merged returns: the number of a
    pull request that already merged this very head, else None.
    """
    try:
        pr = repo.pr.find_by_head(branch)
        if pr is not None and repo.pr.is_armed(pr.number):
            repo.pr.disarm(pr.number)
            print(f"  disarmed PR #{pr.number} before pushing (the race)")
    except ForgeError as exc:
        print(f"  note: could not read the arming state before pushing ({exc})")
    return abort_if_merged(repo, root, branch)

label_every_runner

label_every_runner(repo: Repository, number: int) -> None

Put livery.workshop.EVERY_RUNNER_LABEL on pull request number.

The gate then runs every runner for it, where its check legs run on fewer. Idempotent: a label the pull request already carries stays. A forge that refuses, one whose repository does not carry the label among them, fails with the forge's words; the pull request exists by then, so a re-run labels the same one.

Source code in packages/workshop/src/livery/workshop/_submit.py
def label_every_runner(repo: Repository, number: int) -> None:
    """Put [livery.workshop.EVERY_RUNNER_LABEL][] on pull request *number*.

    The gate then runs every runner for it, where its check legs run on
    fewer. Idempotent: a label the
    pull request already carries stays. A forge that refuses, one
    whose repository does not carry the label among them, fails with
    the forge's words; the pull request exists by then, so a re-run
    labels the same one.
    """
    try:
        repo.pr.add_labels(number, (EVERY_RUNNER_LABEL,))
    except ForgeError as error:
        fail(
            f"PR #{number} exists, but {EVERY_RUNNER_LABEL} could not be set on"
            f" it: {error}\n  `{footman.prog()} workflow.configure` creates the"
            " label on the repository; then re-run"
            f" `{footman.prog()} submit --every-runner`"
        )
    print(
        f"  every runner: labelled {EVERY_RUNNER_LABEL}; the gate runs every"
        " runner for this pull request"
    )

push_and_pr

push_and_pr(repo: Repository, root: Path, plan: Plan, *, closes: int | None, armed: bool, force: bool = False, every_runner: bool = False) -> int

Disarm, push, find-or-open the pull request, label and arm as asked.

Source code in packages/workshop/src/livery/workshop/_submit.py
def push_and_pr(
    repo: Repository,
    root: Path,
    plan: Plan,
    *,
    closes: int | None,
    armed: bool,
    force: bool = False,
    every_runner: bool = False,
) -> int:
    """Disarm, push, find-or-open the pull request, label and arm as asked."""
    body = with_closes(plan.body, closes) if closes is not None else plan.body
    merged = disarm_before_push(repo, root, plan.branch)
    if merged is not None:
        # Re-running the submit is its recovery procedure: a head the
        # pull request already merged has nothing to push, open, or
        # arm, and the caller's follow reports the merge.
        print(f"  PR #{merged} already merged this head; nothing to push")
        return merged
    # Found by branch name, so no push is needed first - and the
    # refusal below must run before the push: a refusal that leaves a
    # branch on the remote makes the next submit of a rebuilt branch
    # fail non-fast-forward.
    pr = repo.pr.find_by_head(plan.branch)
    if pr is None:
        _push(root, plan.branch, force=force, repo=repo)
        pr = repo.pr.open(plan.branch, plan.base, plan.title, body)
        print(f"  opened PR #{pr.number}: {pr.title}")
    else:
        _push(root, plan.branch, force=force, repo=repo)
        print(f"  reusing PR #{pr.number}")
        if plan.title_given and pr.title != plan.title:
            repo.pr.update_title(pr.number, plan.title)
            print(f"  title updated: {plan.title}")
        if plan.body_given and pr.body != body:
            repo.pr.update_body(pr.number, body)
            print("  body updated")
    if every_runner:
        label_every_runner(repo, pr.number)
    if armed:
        _arm_and_say(
            repo,
            pr.number,
            title=_merge_title(repo, plan),
            message=body,
            kind=_contract_forge_kind(root),
        )
    return pr.number

refuse_ambiguous_title

refuse_ambiguous_title(root: Path, plan: Plan) -> None

Refuse a defaulted title on a branch more than one commit ahead.

A defaulted title is trustworthy only when it is unambiguous: one commit ahead, its subject is the intent. More, and whichever commit is HEAD would name the pull request, a guess dressed as a default, so it refuses instead, listing the subjects. A given title never refuses, and a pull request that already exists keeps its title, so the caller asks only on a first open.

Source code in packages/workshop/src/livery/workshop/_submit.py
def refuse_ambiguous_title(root: Path, plan: Plan) -> None:
    """Refuse a defaulted title on a branch more than one commit ahead.

    A defaulted title is trustworthy only when it is unambiguous: one
    commit ahead, its subject is the intent. More, and whichever
    commit is HEAD would name the pull request, a guess dressed as a
    default, so it refuses instead, listing the subjects. A given
    title never refuses, and a pull request that already exists keeps
    its title, so the caller asks only on a first open.
    """
    if plan.title_given:
        return
    subjects = [
        subject for subject in plan.subjects if not subject.startswith("Merge ")
    ]
    if len(subjects) > 1:
        listed = "\n".join(f"    - {subject}" for subject in subjects)
        fail(
            f"the branch is {len(subjects)} commits ahead, so no"
            " commit subject can default the PR title:\n"
            f"{listed}\n"
            '  pass the intent: --title="type(scope): subject"'
        )

submit_flow

submit_flow(repo: Repository, root: Path, *, title: str = '', body: str = '', base: str = 'main', closes: int = 0, close: bool = True, armed: bool = False, armed_reason: str = '', gate: bool = True, fix: bool = False, force: bool = False, every_runner: bool = False, follow_to_verdict: bool = True, interval: float = 15, timeout: float = 1800) -> int

The whole submitting act; returns the pull request number.

The task shell resolves the repository, the git seam, and the arming ladder; everything after that lives here so tests drive the same flow against livery.forge.testing.FakeForge and a temporary repository.

Source code in packages/workshop/src/livery/workshop/_submit.py
def submit_flow(
    repo: Repository,
    root: Path,
    *,
    title: str = "",
    body: str = "",
    base: str = "main",
    closes: int = 0,
    close: bool = True,
    armed: bool = False,
    armed_reason: str = "",
    gate: bool = True,
    fix: bool = False,
    force: bool = False,
    every_runner: bool = False,
    follow_to_verdict: bool = True,
    interval: float = 15,
    timeout: float = 1800,
) -> int:
    """The whole submitting act; returns the pull request number.

    The task shell resolves the repository, the git seam, and the
    arming ladder; everything after that lives here so tests drive the
    same flow against livery.forge.testing.FakeForge and a temporary
    repository.
    """
    # Every refusal the arguments decide comes before the gate: the
    # branch's name, the title's shape, and whether a title can
    # default at all. A person never pays minutes of gate for a flag
    # they could have passed, and the title is decided from the
    # branch as it is, before a fold adds a commit of its own.
    git.fetch(root)
    branch = git.current_branch(root)
    # The stack, read once for the flow: a restack that moved the branch
    # may have forgotten it, so it is read again after one.
    stack = _stack.stack(root, branch)
    moved = _restack_before_push(root, branch=branch, stack=stack)
    if moved:
        stack = _stack.stack(root, branch)
    force = moved or force
    plan = prepare(root, title=title, body=body, base=base, branch=branch)
    # A first open only: a pull request that exists, open, merged, or
    # closed, keeps its title, and the merged and closed cases get
    # their own refusals further on.
    if repo.pr.find_by_head(plan.branch, state="all") is None:
        if not plan.subjects:
            fail(
                f"{plan.branch} has no commits beyond origin/{plan.base}, so"
                " there is nothing to submit: commit first"
                f' (`{footman.prog()} commit <type> "<subject>"`), then re-run'
                f" `{footman.prog()} submit`"
            )
        refuse_ambiguous_title(root, plan)
    # The check CI's setup makes with `sync --locked`, made before the
    # push and before the gate's minutes: a lock that is not current
    # refuses here, on this machine.
    from livery.workshop._sync import stale_locks

    for problem in stale_locks(root):
        fail(
            f"{problem}. CI's setup refuses a lock that is not current:"
            f" `{footman.prog()} sync` writes it; commit it, then re-run"
            f" `{footman.prog()} submit`"
        )
    if gate:
        _gate(fix, root=root, base=base)
        if fix and not git.is_clean(root):
            _fold_fixes(root, base)
    else:
        print("  gate skipped (--no-gate): CI is now the first verifier")
    _heal_context_rename(repo, root, plan, fix=fix)
    linked = resolve_closes(repo, plan.branch, closes) if close else None
    if linked is not None:
        print(f"  Closes #{linked} on merge")
    elif not close:
        print("  closes nothing (--no-close): the branch's issue stays open")
    parent, _tip = stack
    if armed and parent and plan.base == parent:
        # The forge refuses to arm a pull request into a branch with no
        # required checks, and arming into the parent would land the
        # child there, not on main: the arm waits for the parent's merge.
        armed = False
        print(
            f"  arming: off - {parent} is still open; after it merges, run"
            f" `{footman.prog()} sync` then `{footman.prog()} submit --armed`"
        )
    elif armed_reason:
        print(f"  arming: {'on' if armed else 'off'} - decided by {armed_reason}")
    number = push_and_pr(
        repo,
        root,
        plan,
        closes=linked,
        armed=armed,
        force=force,
        every_runner=every_runner,
    )
    if not follow_to_verdict:
        return number
    heals = 0

    def trace_the_run() -> None:
        """Hand the run just followed to this command's own trace, if any.

        Called at every way out of the watch, a red run included: a timeline
        is wanted most where something went wrong. Nothing is kept in the
        ordinary case, and nothing here can fail the submit.
        """
        if traced := drop_run(repo, root):
            print(f"  {traced}")

    while True:
        try:
            follow_pull_request(
                repo, plan.branch, root, interval=interval, timeout=timeout
            )
        except SystemExit as exc:
            code = exc.code if isinstance(exc.code, int) else 1
            if code == EXIT_DISARMED and not armed:
                # The submit was asked not to arm, so a green parked PR is
                # this run finishing its job, not a blocker: prose above
                # already said where it is parked, and the exit is clean.
                # 11 still surfaces on an *armed* submit, where a gone
                # schedule means something interfered.
                print(f"  done: CI is green and PR #{number} awaits your call")
                trace_the_run()
                return number
            if code in (EXIT_CONFLICTS, EXIT_BEHIND) and heals < _MAX_HEALS:
                heals += 1
                print(
                    f"  exit {code}: integrating origin/{plan.base} and"
                    f" re-submitting (self-heal {heals}/{_MAX_HEALS})"
                )
                disarm_before_push(repo, root, plan.branch)
                before = git.head_sha(root)
                try:
                    git.integrate(root, plan.base)
                except git.GitError as exc2:
                    fail(
                        f"the merge stopped on a conflict; resolve it, commit,"
                        f" and re-run `{footman.prog()} submit`:\n{exc2}"
                    )
                # The merge can bring the code this process runs, and the
                # gate must judge the merged tree with the code it carries:
                # the rest is a fresh submit on that code. Re-running the
                # verb is the recovery, so nothing is lost by the handoff.
                from livery.workshop._sync import continue_on_moved_code

                continue_on_moved_code(root, before, git.head_sha(root), verb="submit")
                if gate:
                    _gate(root=root, base=plan.base)
                number = push_and_pr(
                    repo,
                    root,
                    plan,
                    closes=linked,
                    armed=armed,
                    force=force,
                    every_runner=every_runner,
                )
                continue
            trace_the_run()
            raise
        # Before the tidy moves this checkout off the branch, whose head is
        # how the run is found.
        trace_the_run()
        _tidy_after_merge(repo, root, plan.branch, plan.base, number)
        return number

submit_default

submit_default(title: Annotated[str, doc("PR title; defaults to HEAD's subject")] = '', body: Annotated[str, doc("PR body; defaults to HEAD's body")] = '', base: Annotated[str, doc('target branch')] = 'main', closes: Annotated[int, doc('issue to close on merge; 0 = from branch name')] = 0, close: Annotated[bool, doc("close the branch's issue on merge")] = True, armed: Annotated[bool, env('WORKSHOP_AUTOMERGE'), default(ci_automerge), doc('arm auto-merge (ladder: flag, WORKSHOP_AUTOMERGE, [ci] automerge)')] = False, gate: Annotated[bool, doc(f'run `{prog()} check` first')] = True, fix: Annotated[bool, doc('heal mechanical gate findings, fold into HEAD')] = False, force: Annotated[bool, doc('force-push with a lease after a deliberate history rewrite')] = False, every_runner: Annotated[bool, doc(f"label the PR {EVERY_RUNNER_LABEL} so the gate runs every runner: for a change only another platform reaches while the pull request's legs run on fewer")] = False, follow: Annotated[bool, doc('watch until it lands or says what stopped it')] = True, interval: Annotated[int, doc('watch poll seconds')] = 15, timeout: Annotated[int, doc('watch deadline seconds')] = 1800) -> None

Gate, push, open-or-reuse the PR, arm, and watch it land.

Idempotent: re-running it is the recovery procedure. Exits 10 and 17 self-heal by integrating the base and re-submitting; the other verdict codes surface unchanged (see livery.workshop._verdict). --fix runs the gate's format and lint in their fix modes and folds any rewrites into the branch before pushing: amended into HEAD while unpushed, a follow-up commit otherwise. --no-close submits without the close footer, for a branch that carries preparatory work on an issue the merge must leave open. --every-runner labels the pull request ci:every-runner, so the gate runs every runner for it where its check legs run on fewer: for a change to a line only another platform reaches, which a narrowed run judges red by name.

Source code in packages/workshop/src/livery/workshop/_submit.py
@submit.default(serial=True)
def submit_default(
    title: Annotated[str, doc("PR title; defaults to HEAD's subject")] = "",
    body: Annotated[str, doc("PR body; defaults to HEAD's body")] = "",
    base: Annotated[str, doc("target branch")] = "main",
    closes: Annotated[int, doc("issue to close on merge; 0 = from branch name")] = 0,
    close: Annotated[bool, doc("close the branch's issue on merge")] = True,
    armed: Annotated[
        bool,
        footman.env("WORKSHOP_AUTOMERGE"),
        footman.default(ci_automerge),
        doc("arm auto-merge (ladder: flag, WORKSHOP_AUTOMERGE, [ci] automerge)"),
    ] = False,
    gate: Annotated[bool, doc(f"run `{footman.prog()} check` first")] = True,
    fix: Annotated[bool, doc("heal mechanical gate findings, fold into HEAD")] = False,
    force: Annotated[
        bool, doc("force-push with a lease after a deliberate history rewrite")
    ] = False,
    every_runner: Annotated[
        bool,
        doc(
            f"label the PR {EVERY_RUNNER_LABEL} so the gate runs every runner: for"
            " a change only another platform reaches while the pull request's"
            " legs run on fewer"
        ),
    ] = False,
    follow: Annotated[bool, doc("watch until it lands or says what stopped it")] = True,
    interval: Annotated[int, doc("watch poll seconds")] = 15,
    timeout: Annotated[int, doc("watch deadline seconds")] = 1800,
) -> None:
    """Gate, push, open-or-reuse the PR, arm, and watch it land.

    Idempotent: re-running it is the recovery procedure. Exits 10 and
    17 self-heal by integrating the base and re-submitting; the other
    verdict codes surface unchanged (see livery.workshop._verdict).
    ``--fix`` runs the gate's format and lint in their fix modes and
    folds any rewrites into the branch before pushing: amended into
    HEAD while unpushed, a follow-up commit otherwise. ``--no-close``
    submits without the close footer, for a branch that carries
    preparatory work on an issue the merge must leave open.
    ``--every-runner`` labels the pull request ``ci:every-runner``, so
    the gate runs every runner for it where its check legs run on
    fewer: for a change to a line only another platform reaches, which
    a narrowed run judges red by name.
    """
    root = _root()
    from livery.workshop._forge_lane import this_repository

    repo = this_repository(root)
    reason = arming_reason(armed=armed, flag_given=footman.given("armed"))
    base = resolve_base(root, base, given=footman.given("base"))
    with forge_failures_named():
        submit_flow(
            repo,
            root,
            title=title,
            body=body,
            base=base,
            closes=closes,
            close=close,
            armed=armed,
            armed_reason=reason,
            gate=gate,
            force=force,
            fix=fix,
            every_runner=every_runner,
            follow_to_verdict=follow,
            interval=interval,
            timeout=timeout,
        )

forge_failures_named

forge_failures_named() -> Generator[None]

Fail with the forge's own words when it refuses or does not answer.

A submit is safe to run again, so a read that timed out or a write the forge refused ends the run with the forge's message and that advice, not a traceback.

Source code in packages/workshop/src/livery/workshop/_submit.py
@contextlib.contextmanager
def forge_failures_named() -> Generator[None]:
    """Fail with the forge's own words when it refuses or does not answer.

    A submit is safe to run again, so a read that timed out or a write
    the forge refused ends the run with the forge's message and that
    advice, not a traceback.
    """
    try:
        yield
    except ForgeError as error:
        fail(
            f"{error}\n  `{footman.prog()} submit` is safe to run again: it"
            " starts from what the forge already has"
        )

worktree_for

worktree_for(root: Path, branch: str) -> str

The linked worktree holding branch; "" when none does or root does.

Source code in packages/workshop/src/livery/workshop/_submit.py
def worktree_for(root: Path, branch: str) -> str:
    """The linked worktree holding *branch*; "" when none does or *root* does."""
    listing = git.run(root, "worktree", "list", "--porcelain")
    tree = ""
    current: dict[str, str] = {}
    for line in [*listing.splitlines(), ""]:
        if not line.strip():
            if current.get("branch", "").endswith(f"refs/heads/{branch}"):
                tree = current.get("worktree", "")
            current = {}
            continue
        key, _, value = line.partition(" ")
        current[key] = value
    if tree and Path(tree).resolve() == root.resolve():
        return ""
    return tree

only_local_work

only_local_work(root: Path, branch: str, *, merged_head: str = '') -> str

Why branch holds work that exists nowhere else; "" when safe.

The one keep-or-drop rule: fm issue.close, fm issue.stop, the submit's own teardown after a merge, the sweep, and fm sync all ask it, so what they destroy is decided in one place. Dirt is looked for where the branch actually lives: this checkout when it stands on the branch, the branch's linked worktree otherwise.

merged_head is the head a merged pull request took. A tip equal to it holds nothing only here: the merge took every commit, and the squash rewrote them, so the remote's ancestry says nothing (after a squash the branch's commits are never ancestors of the base, and the forge deletes the remote branch). A tip past it holds the commits made after the merge. A tip the merged head does not reach was rewritten after the merge, and the ancestry rule below judges it. Without a merged head, ahead is measured against the remote branch when one exists, and against the base when none does.

Source code in packages/workshop/src/livery/workshop/_submit.py
def only_local_work(root: Path, branch: str, *, merged_head: str = "") -> str:
    """Why *branch* holds work that exists nowhere else; "" when safe.

    The one keep-or-drop rule: ``fm issue.close``, ``fm issue.stop``,
    the submit's own teardown after a merge, the sweep, and ``fm sync``
    all ask it, so what they destroy is decided in one place. Dirt is
    looked for where the branch actually lives: this checkout when it
    stands on the branch, the branch's linked worktree otherwise.

    *merged_head* is the head a merged pull request took. A tip equal
    to it holds nothing only here: the merge took every commit, and
    the squash rewrote them, so the remote's ancestry says nothing
    (after a squash the branch's commits are never ancestors of the
    base, and the forge deletes the remote branch). A tip past it
    holds the commits made after the merge. A tip the merged head
    does not reach was rewritten after the merge, and the ancestry
    rule below judges it. Without a merged head, ahead is measured
    against the remote branch when one exists, and against the base
    when none does.
    """
    if git.current_branch(root) == branch and not git.is_clean(root):
        return "uncommitted changes"
    tree = worktree_for(root, branch)
    if tree:
        status = git.run(root, "-C", tree, "status", "--porcelain").strip()
        if status:
            return f"uncommitted changes in the worktree {tree}"
    if merged_head:
        tip = git.object_id(root, f"refs/heads/{branch}")
        if tip == merged_head:
            return ""
        if git.is_ancestor(root, merged_head, tip):
            count = git.run(
                root, "rev-list", "--count", f"{merged_head}..{tip}"
            ).strip()
            return f"{count} commit(s) past the merged head"
    remote = f"origin/{branch}"
    upstream = remote if branch in git.remote_branches(root, "") else "origin/main"
    count = git.run(root, "rev-list", "--count", f"{upstream}..{branch}").strip()
    if count.isdigit() and int(count) > 0:
        where = "the remote branch" if upstream == remote else "any remote"
        return f"{count} commit(s) not on {where}"
    return ""

merged_pull_request

merged_pull_request(repo: Repository, root: Path, branch: str) -> PullRequest | None

The merged pull request branch was the head of, or None.

livery.workshop._forge_lane.pull_request_for finds it, by head branch and then by the branch's head commit; a forge that cannot be asked raises.

Source code in packages/workshop/src/livery/workshop/_submit.py
def merged_pull_request(
    repo: Repository, root: Path, branch: str
) -> PullRequest | None:
    """The merged pull request *branch* was the head of, or None.

    [livery.workshop._forge_lane.pull_request_for][] finds it, by head
    branch and then by the branch's head commit; a forge that cannot
    be asked raises.
    """
    from livery.workshop._forge_lane import pull_request_for

    pr = pull_request_for(repo, root, branch)
    return pr if pr is not None and pr.merged else None

teardown_branch

teardown_branch(repo: Repository, root: Path, branch: str, base: str) -> None

The one branch teardown every stop verb wears; idempotent.

Disarm, close the PR (a merged one is left alone), delete the remote and local branch, and step back onto an up-to-date base when standing on branch. Mechanism only: state gates, forces, and refusals are the calling policy's job (livery.workshop._submit.abandon_flow for a feature, workflow.abort for a reserved workflow), so the policies can never drift apart. Removing a linked worktree moves the process into the main checkout first: Windows refuses to remove a directory a process stands in, and the shell that ran the verb is told where to go. A real move of the process directory is a serial task's to make (footman refuses it in a parallel one), so every verb that reaches this from inside a worktree is declared serial.

Source code in packages/workshop/src/livery/workshop/_submit.py
def teardown_branch(
    repo: Repository,
    root: Path,
    branch: str,
    base: str,
) -> None:
    """The one branch teardown every stop verb wears; idempotent.

    Disarm, close the PR (a merged one is left alone), delete the
    remote and local branch, and step back onto an up-to-date *base*
    when standing on *branch*. Mechanism only: state gates, forces,
    and refusals are the calling policy's job
    (livery.workshop._submit.abandon_flow for a feature,
    ``workflow.abort`` for a reserved workflow), so the policies can
    never drift apart. Removing a
    linked worktree moves the process into the main checkout first:
    Windows refuses to remove a directory a process stands in, and
    the shell that ran the verb is told where to go. A real move of
    the process directory is a serial task's to make (footman refuses
    it in a parallel one), so every verb that reaches this from
    inside a worktree is declared ``serial``.
    """
    pr = repo.pr.find_by_head(branch)
    if pr is not None and not pr.merged:
        _disarm_and_say(repo, pr.number)
        repo.pr.close(pr.number)
        print(f"  closed PR #{pr.number}")
    if repo.branch_exists(branch):
        repo.delete_branch(branch)
        print(f"  deleted origin/{branch}")
    git_dir = git.run(root, "rev-parse", "--git-dir").strip()
    common_dir = git.run(root, "rev-parse", "--git-common-dir").strip()
    standing = git.current_branch(root) == branch
    if standing and git_dir != common_dir:
        # A linked worktree cannot switch to *base*: the main
        # checkout holds it. The worktree itself is the leftover, so
        # it is removed from the main checkout, branch and all. The
        # shell that ran this stands in a deleted directory afterwards
        # and is told where to go.
        import os

        main_root = git.main_checkout(root)
        os.chdir(main_root)
        git.run(main_root, "worktree", "remove", "--force", str(root))
        if git.local_branch_exists(main_root, branch):
            git.delete_branch(main_root, branch)
        print(f"  removed the worktree {root} and deleted {branch}")
        print(f"  this shell's directory is gone: cd {main_root}")
        return
    if standing:
        git.switch(root, base)
        git.integrate(root, base)
    else:
        tree = worktree_for(root, branch)
        if tree:
            git.run(root, "worktree", "remove", "--force", tree)
            print(f"  removed the worktree {tree}")
    if git.local_branch_exists(root, branch):
        git.delete_branch(root, branch)
        # Only a checkout that stood on the branch moved to the base.
        print(f"  deleted {branch}" + (f"; back on {base}" if standing else ""))

abandon_flow

abandon_flow(repo: Repository, root: Path, branch: str, base: str) -> None

Give the feature up: close the PR, delete both branches; idempotent.

A dirty tree refuses before anything else moves: abandoning deletes the branch, and uncommitted work must be a person's explicit loss, not a side effect.

Source code in packages/workshop/src/livery/workshop/_submit.py
def abandon_flow(repo: Repository, root: Path, branch: str, base: str) -> None:
    """Give the feature up: close the PR, delete both branches; idempotent.

    A dirty tree refuses before anything else moves: abandoning
    deletes the branch, and uncommitted work must be a person's
    explicit loss, not a side effect.
    """
    if not branch or branch == base:
        fail(f"not on a feature branch (on {branch or '(detached)'!r})")
    if branch == git.current_branch(root):
        if not git.is_clean(root):
            fail(
                "the working tree has uncommitted changes; commit or discard"
                " them before abandoning"
            )
    else:
        tree = worktree_for(root, branch)
        if tree and git.run(root, "-C", tree, "status", "--porcelain").strip():
            fail(
                f"the worktree {tree} has uncommitted changes; commit or"
                " discard them before abandoning"
            )
    pr = repo.pr.find_by_head(branch)
    if pr is not None and pr.merged:
        fail(f"PR #{pr.number} already merged: nothing to abandon")
    if pr is None:
        print(f"  no open pull request for {branch}")
    teardown_branch(repo, root, branch, base)

abandon

abandon(branch: Annotated[Arg[str], doc('a branch to give up; this one when absent')] = '') -> None

Give up a feature: close the PR, delete the branches, return to base.

This branch when none is named, or the named one from anywhere: its linked worktree goes with it. Disarms and closes the pull request, deletes the remote and the local branch, and leaves this checkout on an up-to-date base when it stood on the branch. A dirty tree, here or in the branch's worktree, refuses first. Idempotent: a second run finds nothing left to undo.

Source code in packages/workshop/src/livery/workshop/_submit.py
@footman.task(serial=True)
def abandon(
    branch: Annotated[Arg[str], doc("a branch to give up; this one when absent")] = "",
) -> None:
    """Give up a feature: close the PR, delete the branches, return to base.

    This branch when none is named, or the named one from anywhere:
    its linked worktree goes with it. Disarms and closes the pull
    request, deletes the remote and the local branch, and leaves this
    checkout on an up-to-date base when it stood on the branch. A
    dirty tree, here or in the branch's worktree, refuses first.
    Idempotent: a second run finds nothing left to undo.
    """
    root = _root()
    from livery.workshop._forge_lane import this_repository

    abandon_flow(
        this_repository(root), root, branch or git.current_branch(root), "main"
    )

pull_request_named

pull_request_named(repo: Repository, root: Path, ref: str) -> PullRequest

Find the pull request ref numbers; this branch's when ref is empty.

ref is read by livery.workshop._submit.parse_number, the rule the issue verbs read an issue number by, so #123 and 123 name the same pull request. On the current branch the open pull request is looked up by the branch's name, and when there is none, a merged one by the branch's head commit, which outlives a head branch the merge deleted: after a merge, the answer is that it merged. Every other answer fails and names the next action: a ref that is no number, a number no pull request has, a branch without an open or merged pull request, and a pull request closed without merging.

Parameters:

Name Type Description Default
repo Repository

The workspace's repository on its forge.

required
root Path

The checkout whose current branch an empty ref means.

required
ref str

A pull request number, with or without #; empty for the current branch's.

required

Returns:

Type Description
PullRequest

The pull request, open or merged. What a merged one means is

PullRequest

the verb's to decide.

Source code in packages/workshop/src/livery/workshop/_submit.py
def pull_request_named(repo: Repository, root: Path, ref: str) -> PullRequest:
    """Find the pull request *ref* numbers; this branch's when *ref* is empty.

    *ref* is read by [livery.workshop._submit.parse_number][], the
    rule the issue verbs read an issue number by, so ``#123`` and
    ``123`` name the same pull request. On the current branch the open
    pull request is looked up by the branch's name, and when there is
    none, a merged one by the branch's head commit, which outlives a
    head branch the merge deleted: after a merge, the answer is that
    it merged. Every other answer fails and names the next action: a
    *ref* that is no number, a number no pull request has, a branch
    without an open or merged pull request, and a pull request closed
    without merging.

    Args:
        repo: The workspace's repository on its forge.
        root: The checkout whose current branch an empty *ref* means.
        ref: A pull request number, with or without ``#``; empty for
            the current branch's.

    Returns:
        The pull request, open or merged. What a merged one means is
        the verb's to decide.
    """
    prog = footman.prog()
    if ref:
        number = parse_number(ref)
        if number is None:
            fail(
                f"{ref!r} is not a pull request number: name one, 123 or"
                " #123, or none for this branch's"
            )
        pr = repo.pr.get(number)
        if pr is None:
            fail(f"no pull request #{number} on the forge: check the number")
    else:
        branch = git.current_branch(root)
        if not branch:
            fail("HEAD is detached, so no branch names a pull request: name its number")
        pr = repo.pr.find_by_head(branch)
        if pr is None:
            done = repo.pr.find_by_head_sha(git.head_sha(root))
            pr = done if done is not None and done.merged else None
        if pr is None:
            fail(
                f"no open pull request for {branch}: `{prog} submit` opens"
                " one, or name a pull request's number"
            )
    if pr.state != "open" and not pr.merged:
        fail(
            f"PR #{pr.number} is closed: `{prog} submit` on {pr.head_branch}"
            " opens a new one"
        )
    return pr

arm_flow

arm_flow(repo: Repository, root: Path, pr: PullRequest) -> None

Arm pr to merge when green, as fm submit --armed arms; idempotent.

The squash takes the pull request's own title and body. An armed pull request is left as it is, and a merged one is the end the arm aims at: each line says so, and neither is an error.

Source code in packages/workshop/src/livery/workshop/_submit.py
def arm_flow(repo: Repository, root: Path, pr: PullRequest) -> None:
    """Arm *pr* to merge when green, as ``fm submit --armed`` arms; idempotent.

    The squash takes the pull request's own title and body. An armed
    pull request is left as it is, and a merged one is the end the arm
    aims at: each line says so, and neither is an error.
    """
    if _merged_already(pr):
        return
    if repo.pr.is_armed(pr.number):
        print(f"  PR #{pr.number} is armed already; nothing changed")
        return
    _arm_and_say(
        repo,
        pr.number,
        title=pr.title.strip(),
        message=pr.body,
        kind=_contract_forge_kind(root),
    )

disarm_flow

disarm_flow(repo: Repository, pr: PullRequest) -> None

Take auto-merge off pr and leave it open; idempotent.

An unarmed pull request is left as it is, and the line says so. A merged one refuses: the merge the disarm was to prevent has happened.

Source code in packages/workshop/src/livery/workshop/_submit.py
def disarm_flow(repo: Repository, pr: PullRequest) -> None:
    """Take auto-merge off *pr* and leave it open; idempotent.

    An unarmed pull request is left as it is, and the line says so. A
    merged one refuses: the merge the disarm was to prevent has
    happened.
    """
    if pr.merged:
        fail(f"PR #{pr.number} has already merged: too late to disarm")
    if not _disarm_and_say(repo, pr.number):
        print(f"  PR #{pr.number} is not armed; nothing changed")

merge_flow

merge_flow(repo: Repository, root: Path, pr: PullRequest, *, title: str = '') -> None

Merge the pull request pr as soon as possible; a merged one is done.

Merge means merge asap, never merge-if-instant-else-fail: checks still running are followed to their verdict, the forge's own holds (the mergeability recompute, the settling beat) are followed to completion, and the task's timeout is the only backstop. Red refuses at once naming the state, behind base teaches integrate, and merging red stays a person's act in the forge's own interface.

Whether pr is behind its base is judged at HEAD when pr is this branch's pull request, since HEAD is what the next submit pushes, and at the head the forge holds for any other, which the fetch brings here. A head this clone cannot see is left to the forge's own refusal.

Source code in packages/workshop/src/livery/workshop/_submit.py
def merge_flow(
    repo: Repository, root: Path, pr: PullRequest, *, title: str = ""
) -> None:
    """Merge the pull request *pr* as soon as possible; a merged one is done.

    Merge means merge asap, never merge-if-instant-else-fail: checks
    still running are followed to their verdict, the forge's own
    holds (the mergeability recompute, the settling beat) are
    followed to completion, and the task's timeout is the only
    backstop. Red refuses at once naming the state, behind base
    teaches integrate, and merging red stays a person's act in the
    forge's own interface.

    Whether *pr* is behind its base is judged at HEAD when *pr* is
    this branch's pull request, since HEAD is what the next submit
    pushes, and at the head the forge holds for any other, which the
    fetch brings here. A head this clone cannot see is left to the
    forge's own refusal.
    """
    if _merged_already(pr):
        return
    own = pr.head_branch == git.current_branch(root)
    _wait_for_verdict(repo, pr.number, local_head=git.head_sha(root) if own else "")
    # The wait follows a head that moves, so the verdict is read for
    # the head it settled on, not the one *pr* was read with.
    pr = repo.pr.get(pr.number) or pr
    status = repo.checks.status(pr.head_sha)
    if status.state == "failure":
        fail(
            f"CI is red for PR #{pr.number}: fix it and `{footman.prog()} submit`."
            " This verb never merges red."
        )
    git.fetch(root)
    head = "HEAD" if own else git.sha_of(root, pr.head_sha)
    if head and not git.is_ancestor(root, f"origin/{pr.base_branch}", head):
        where = "" if own else f" on {pr.head_branch},"
        fail(
            f"PR #{pr.number} is behind {pr.base_branch}:{where}"
            f" `{footman.prog()} integrate`, then `{footman.prog()} submit`,"
            " and merge again"
        )
    subject = title or pr.title
    _follow_merge_state(
        repo,
        _contract_forge_kind(root),
        pr.number,
        repo.pr.merge_now,
        pr.number,
        title=subject,
    )
    print(f"  merged PR #{pr.number}")

submit_merge

submit_merge(pr: _PullRef = '', title: Annotated[str, doc('squash subject; defaults to the PR title')] = '') -> None

Merge a PR as soon as possible: this branch's, or the one numbered.

Waits for a running CI's verdict and follows the forge's own holds to completion; refuses red or behind-base at once, saying why, and refuses a pull request closed without merging. A pull request that has merged already is done: the verb says so and succeeds, so a re-run is the recovery. A merge that lands while it runs is success too, as livery.forge.PullRequests.merge_now reads one.

Source code in packages/workshop/src/livery/workshop/_submit.py
@submit.task(name="merge")
def submit_merge(
    pr: _PullRef = "",
    title: Annotated[str, doc("squash subject; defaults to the PR title")] = "",
) -> None:
    """Merge a PR as soon as possible: this branch's, or the one numbered.

    Waits for a running CI's verdict and follows the forge's own
    holds to completion; refuses red or behind-base at once, saying
    why, and refuses a pull request closed without merging. A pull
    request that has merged already is done: the verb says so and
    succeeds, so a re-run is the recovery. A merge that lands while it
    runs is success too, as livery.forge.PullRequests.merge_now reads
    one.
    """
    repo, root, found = _named(pr)
    merge_flow(repo, root, found, title=title)

submit_arm

submit_arm(pr: _PullRef = '') -> None

Arm a PR to merge when green: this branch's, or the one numbered.

Arms as fm submit --armed arms, with the pull request's own title as the squash subject, and reads the schedule back. A pull request already green is merged at once, since a forge that arms only a blocked pull request refuses. An armed one is left as it is, and a merged one is done: the verb says so and succeeds, also on the branch once its head branch is gone. One closed without merging refuses.

Source code in packages/workshop/src/livery/workshop/_submit.py
@submit.task(name="arm")
def submit_arm(pr: _PullRef = "") -> None:
    """Arm a PR to merge when green: this branch's, or the one numbered.

    Arms as ``fm submit --armed`` arms, with the pull request's own
    title as the squash subject, and reads the schedule back. A pull
    request already green is merged at once, since a forge that arms
    only a blocked pull request refuses. An armed one is left as it
    is, and a merged one is done: the verb says so and succeeds, also
    on the branch once its head branch is gone. One closed without
    merging refuses.
    """
    repo, root, found = _named(pr)
    arm_flow(repo, root, found)

submit_disarm

submit_disarm(pr: _PullRef = '') -> None

Take auto-merge off a PR and leave it open: this branch's, or the one numbered.

The pull request and its branch stay as they are, so it waits unmerged until fm submit.arm arms it again. An unarmed one is left as it is. A merged one refuses, since the merge the disarm was to prevent has happened, and so does one closed without merging.

Source code in packages/workshop/src/livery/workshop/_submit.py
@submit.task(name="disarm")
def submit_disarm(pr: _PullRef = "") -> None:
    """Take auto-merge off a PR and leave it open: this branch's, or the one numbered.

    The pull request and its branch stay as they are, so it waits
    unmerged until ``fm submit.arm`` arms it again. An unarmed one is
    left as it is. A merged one refuses, since the merge the disarm
    was to prevent has happened, and so does one closed without
    merging.
    """
    repo, _root_dir, found = _named(pr)
    disarm_flow(repo, found)