Bl Submit

/bl-submit - Git-Branchless PR Submission

Category: Git Workflow

Submit commits from your stack as pull requests. Creates branches, pushes to remote, and guides stacked PR configuration.

Usage

/bl-submit [options]

Options

Examples

# Submit current commit with auto-generated branch name
/bl-submit

# Submit current commit with custom branch name
/bl-submit pr/user-authentication

# Submit entire stack (creates branches for all commits)
/bl-submit --all

# Update all existing PRs after changes
/bl-submit --update

Execution

This command delegates to the bl-submit-expert agent:

Task(subagent_type="git-workflow:bl-submit-expert",
     prompt="Execute submit: <options>")

Execution Instructions

1. Verify Prerequisites

   • Check git-branchless is installed
   • Check remote is configured

2. Show Current State

   • Run git sl to display stack with branches
   • Identify commits without branches

3. Execute Submission

   • For single: Create branch at current commit, push
   • For all: Navigate stack, create branches, push each
   • For update: Force-push all existing branches

4. Guide PR Configuration

   • Explain stacked PR base branches
   • Provide table of branch → base relationships

5. Confirm Result

   • Show branches on remote
   • Display final state with git sl

Interactive Flow

User: /bl-submit pr/user-auth

Agent: Submitting current commit...

Current position:
● def5678 feat: add user authentication

Creating branch...
git switch -c pr/user-auth

Pushing to remote...
git submit -c @

✓ Branch pr/user-auth pushed to origin

◆ abc1234 (main) initial commit
┃
● def5678 (ᐅ pr/user-auth) feat: add user authentication

You can now create a PR on GitHub:
  Base: main
  Compare: pr/user-auth

User: /bl-submit --all

Agent: Submitting entire stack (3 commits)...

◆ abc1234 (main) initial commit
┃
◯ def5678 feat: add User class
┃
◯ ghi9012 feat: add validation
┃
● jkl3456 feat: add repository

[1/3] Creating branch at "feat: add User class"...
  git switch -c pr/user-class
  git submit -c @
  ✓ pr/user-class pushed

[2/3] Creating branch at "feat: add validation"...
  git switch -c pr/validation
  git submit -c @
  ✓ pr/validation pushed

[3/3] Creating branch at "feat: add repository"...
  git switch -c pr/repository
  git submit -c @
  ✓ pr/repository pushed

◆ abc1234 (main) initial commit
┃
◯ (pr/user-class) feat: add User class
┃
◯ (pr/validation) feat: add validation
┃
● (ᐅ pr/repository) feat: add repository

All 3 branches pushed!

Create stacked PRs on GitHub:
┌─────────────────┬──────────────────┐
│ Branch          │ Base Branch      │
├─────────────────┼──────────────────┤
│ pr/user-class   │ main             │
│ pr/validation   │ pr/user-class    │
│ pr/repository   │ pr/validation    │
└─────────────────┴──────────────────┘

User: /bl-submit --update

Agent: Updating all PR branches...

Branches to update:
  - pr/user-class
  - pr/validation
  - pr/repository

Running git submit...

  pr/user-class:   abc123 → def456 (force-pushed)
  pr/validation:   ghi789 → jkl012 (force-pushed)
  pr/repository:   mno345 → pqr678 (force-pushed)

All 3 PR branches updated.
GitHub PRs will show new changes automatically.

Stacked PRs Guide

When you submit a stack, you create stacked PRs on GitHub:

Commit Stack          GitHub PRs
─────────────         ──────────
pr/repository    →    PR #3: base = pr/validation
     ↓
pr/validation    →    PR #2: base = pr/user-class
     ↓
pr/user-class    →    PR #1: base = main
     ↓
    main

Important: On GitHub, set each PR's base branch to its parent branch, not main. This ensures reviewers see only the diff for that specific commit.

After a PR is merged:

1. GitHub may auto-update child PR base branches
2. Locally, run /bl-sync --after-merge to clean up
3. Then /bl-submit --update to push changes

Error Handling

Converted and distributed by TomeVault — claim your Tome and manage your conversions.