Skip to main content

Module await_pr

git_workflow::commands

Module await_pr 

Source
Expand description

gw await command - Watch a specific PR to completion, then clean up.

await is the closing bookend of the workflow. Its irreducible job is to watch the PR until it reaches a terminal state (merged or closed); the CI wait and the post-merge cleanup are adjacent steps composed on top, each toggleable by a flag.

The PR is identified by number, not by the current branch. This keeps a background watcher bound to one PR even if you switch branches (e.g. while working a stacked PR), and lets the post-merge cleanup target the PR’s own head branch rather than whatever happens to be checked out.

State machine:

  • Wait for CI: poll until the checks reach a verdict (skip with --no-wait). “Pending” just keeps waiting; pass/fail are terminal. A branch with no CI at all (“no checks reported”, confirmed across a few polls) isn’t waited on — there’s nothing to wait for, so we proceed. Watching the PR is the irreducible job, so this step also bails the moment the PR itself merges or closes.
  • On CI pass (or no CI): open the PR in the browser (with --open), then watch for merge.
  • On CI fail: report and stop, so you can fix → push → rerun await.
  • Watch for merge: poll the PR state every --interval seconds.
  • On merge: notify, then gw cleanup <head branch> (skip with --no-cleanup).

Environment-specific behavior stays in the user’s dotfiles, not the CLI:

  • --open opens the URL via GW_OPEN_URL_CMD/OPEN_URL_CMD (see gw open)
  • the merge notification is delegated to GW_NOTIFY_CMD (called as $GW_NOTIFY_CMD "<message>"), e.g. a script wrapping macOS osascript.

Functions§

run
Execute the await command for a specific PR number