//! `git queue` — manage queues of dependent branches and their numbered PRs.
mod commands;
pub mod engine;
mod gh;
mod git;
mod ident;
mod meta;
mod queue;
mod render;
mod requeue;
mod view;
use clap::{CommandFactory, Parser, Subcommand};
use std::path::PathBuf;
#[derive(Parser)]
#[command(
name = "git-queue",
bin_name = "git queue",
version,
about = "Manage queues of dependent branches and their numbered pull requests",
long_about = "A PR queue is an ordered series of dependent branches: each branch builds on \
the one before it, and the PRs merge in FIFO order — front of the queue \
first. git-queue tracks that order, keeps the queue rebased on its base \
branch, and opens numbered, cross-linked pull requests — one per branch. \
Run `git queue setup` after installing to add man pages, shell completion, \
and an optional `git q` alias."
)]
struct Cli {
#[command(subcommand)]
command: Command,
}
#[derive(Subcommand)]
enum Command {
/// Create a new branch queued after the current one.
#[command(
long_about = "Creates the next branch of the queue at the current branch's tip (or at `--base <branch>`'s tip). In a namespaced queue — one with an explicit name, or whose branches already live under queue/<name>/… — you give the short name and the branch is created as queue/<name>/<short>, exactly like edit's sections; names containing `/` are used as-is, and plain-named queues stay plain. Extending a queue inherits its name; starting a new one asks (or takes `--queue`). The front PR targets the base branch, which is how queues can be built on release branches. Branch arguments elsewhere (`--base`, `track --parent`, `checkout`) accept the same short names."
)]
Create {
/// Name of the new branch.
name: String,
/// Start the queue on this base branch instead of the current branch.
#[arg(long)]
base: Option<String>,
/// Name for the queue when this starts a new one.
#[arg(long)]
queue: Option<String>,
},
/// Show the current queue and its PR status.
#[command(
long_about = "Read-only view of the current line: one row per branch, front of the queue at the bottom, with PR number and state, a left-margin marker on the checked-out branch, and — when a branch holds persisted conflict markers — a warning listing the conflicting files. Markers are detected live from each tip, so the warning can never be stale. Output is colourised on a terminal (set NO_COLOR to disable), and PR numbers are clickable links in terminals that render hyperlinks."
)]
Status,
/// List every queue in the repo, most recently touched first.
#[command(visible_alias = "list")]
#[command(
long_about = "Lists every queue in the repository, most recently touched first — each with its branch roster, the first line of its description, and a marker for the queue you're on. Activity timestamps update whenever a queue operation runs, so the top entry is what you worked on last. Unnamed queues are listed with instructions to name them."
)]
Ls,
/// Show or set the current queue's name.
#[command(
long_about = "Shows the current queue's name, or (re)names it. Every queue is named: the name appears in each PR's header, namespaces the queue's branches (`queue/<name>/<branch>`), and keys the queue-level description and activity time. Naming records membership on every branch of the line, so branches that don't follow the `queue/<name>/…` convention still resolve."
)]
Name {
/// New name for the queue (shows the current name when omitted).
name: Option<String>,
},
/// The status tree with each branch's commits (and their Stable-Commit-Ids) shown.
#[command(
long_about = "`status` with one more level of depth: each branch's commits are listed beneath it, newest first, prefixed with the abbreviated Stable-Commit-Id (`(no id)` for unstamped commits). Those abbreviations are accepted by every command that takes a commit, so `log` is the natural way to find the argument for `move`, `checkout` or `reword`."
)]
Log,
/// Detach HEAD on a queue commit (SHA or Stable-Commit-Id) to edit it in place.
#[command(
long_about = "Detaches HEAD on a commit of the current queue — named by SHA or Stable-Commit-Id — after validating membership and a clean stage. From there, edit and `git add`, then: plain `git commit` INSERTS a new commit right after it, while `git commit --amend` REVISES it (the message carries over, so its Stable-Commit-Id is preserved). Either way everything that followed rebases onto the new commit, automatically with hooks installed or via `git queue requeue`. HEAD stays detached at the edited commit so you can keep going; `git queue checkout <branch>` reattaches and ends the session."
)]
Checkout {
/// A commit of the current queue, or one of its branches to reattach.
commit: String,
},
/// Edit the whole queue: reassign commits to branches in an editor.
#[command(visible_alias = "split")]
#[command(
long_about = "Opens the whole queue in an editor: every branch is a `[name]` section header, with the commits belonging to it listed beneath (the first section is the front of the queue — it merges first). The commit sequence is fixed — commits cannot be reordered or deleted, only assigned to branches — so editing means moving, renaming, adding, or removing the `[name]` header lines: add a header to split a branch in two, remove one to dissolve a branch into its neighbours, move one to shift commits between adjacent branches. Branch refs simply move to the new section boundaries; no commit is rewritten. Removed branches are deleted (their commits are covered by the remaining branches). Short header names resolve within the queue and new ones are created as `queue/<name>/<short>` in namespaced queues. Also works on an untracked branch: it becomes one section over trunk, ready to divide."
)]
Edit {
/// Queue name when editing starts a new queue (untracked branch).
#[arg(long)]
queue: Option<String>,
},
/// Interactively shape the current queue line in a terminal UI.
#[command(
long_about = "Opens the current queue line in an interactive, keyboard-driven terminal editor: reorder, squash, split, reword and delete commits, and edit branch boundaries, with per-operation undo/redo. Unlike `edit` — which is ref-only, scriptable, and never rewrites a commit — `tui` rewrites history immediately, so the panes always show true, materialised state. It requires an interactive terminal (errors and points you to `edit` otherwise), a clean worktree, and a non-empty queue, and refuses a forked line (rewriting shared history is out of scope)."
)]
Tui,
/// Describe the current QUEUE (the "About this queue" section of its PRs).
#[command(
long_about = "Sets the QUEUE's description — the \"About this queue\" section rendered into every PR of the queue on the next submit/sync. Use it for the narrative that spans the whole queue: what the series achieves and how the pieces fit. Opens `$EDITOR` without `-m`; an empty message clears it."
)]
Describe {
/// Description text (opens $EDITOR if omitted).
#[arg(short = 'm', long)]
message: Option<String>,
},
/// Describe the current BRANCH (the "About this branch" section of its PR).
#[command(name = "describe-branch")]
#[command(
long_about = "Sets the current BRANCH's description — the \"About this branch\" section of its PR. Use it for what this one slice does. A hand-written body on a PR adopted from before the queue existed is imported here automatically rather than overwritten. Opens `$EDITOR` without `-m`; an empty message clears it."
)]
DescribeBranch {
/// Description text (opens $EDITOR if omitted).
#[arg(short = 'm', long)]
message: Option<String>,
},
/// Adopt the current branch into a queue.
#[command(
long_about = "Adopts an existing branch into a queue: records its parent (trunk by default, or `--parent`), asks for a queue name when starting a new one, and offers to stamp Stable-Commit-Ids onto the adopted commits — asking first because stamping rewrites them (hashes change; an already-pushed branch will be force-pushed with lease on the next sync). `--stamp-ids`/`--no-stamp-ids` decide non-interactively, and `--edit` continues straight into the queue editor to divide the adopted commits into multiple branches."
)]
Track {
/// Parent branch (defaults to trunk).
#[arg(long)]
parent: Option<String>,
/// Stamp Stable-Commit-Ids onto existing commits without asking (rewrites them).
#[arg(long, conflicts_with = "no_stamp_ids")]
stamp_ids: bool,
/// Never stamp Stable-Commit-Ids onto existing commits.
#[arg(long)]
no_stamp_ids: bool,
/// After adopting, open the queue editor to divide the commits into
/// multiple queued branches.
#[arg(long, alias = "split")]
edit: bool,
/// Name for the queue when this adoption starts a new one.
#[arg(long)]
queue: Option<String>,
},
/// Forget the current branch's queue metadata.
#[command(
long_about = "Forgets the current branch's queue metadata (parent, anchor, cached PR number, descriptions, membership). The branch and its commits are untouched — this only removes it from the queue's structure."
)]
Untrack,
/// Check out the child branch (toward the back of the queue).
#[command(visible_alias = "up")]
#[command(
long_about = "Checks out the child branch — one step toward the back of the queue. Errors helpfully at the top or at a fork (listing the children so you can pick one)."
)]
Next,
/// Check out the parent branch (toward the front of the queue).
#[command(visible_alias = "down")]
#[command(
long_about = "Checks out the parent branch — one step toward the front of the queue."
)]
Prev,
/// Make a new commit on the current branch and requeue its descendants.
#[command(
long_about = "Commits like `git commit`, then requeues every descendant branch onto the new tip in one atomic pass (engine: `git replay`), so the branches behind yours never go stale. Stamps a Stable-Commit-Id if the commit-msg hook didn't. With hooks installed, plain `git commit` behaves the same — this command exists for hookless repositories and for scripting."
)]
Commit {
/// Commit message (opens the editor if omitted).
#[arg(short = 'm', long)]
message: Option<String>,
},
/// Fold STAGED changes into the current commit and update all descendants.
#[command(
long_about = "Folds the STAGED changes into the current branch's tip commit and updates every descendant, atomically (engine: `git history fixup`): if propagating would conflict with a descendant, it aborts and changes nothing — it cannot leave conflict markers. This is the everyday tool for addressing review feedback on a PR that has others queued behind it. The commit message, and with it the Stable-Commit-Id, is preserved."
)]
Amend,
/// Rewrite a commit message and update all descendants (defaults to HEAD).
#[command(
long_about = "Rewrites a commit's message — HEAD by default, or any queue commit named by SHA or Stable-Commit-Id — and updates every descendant (engine: `git history reword`; atomic, aborts cleanly on conflict). Content is untouched."
)]
Reword {
/// Commit to reword: a revision or a Stable-Commit-Id (unique prefix ok).
commit: Option<String>,
},
/// Move a commit (or inclusive <first>..<last> range) elsewhere in the queue.
#[command(
long_about = "Relocates a commit, or an inclusive `<first>..<last>` range of consecutive commits, to directly follow `--new-parent` — reordering within one PR or moving work to a different PR (the commits join the branch segment their new parent belongs to). All arguments accept SHAs or Stable-Commit-Ids. The whole line is rewritten in one `git rebase --update-refs` pass: branch refs ride along, conflicts are persisted as markers and flagged, and passing the base branch's tip as `--new-parent` moves commits to the very front of the queue."
)]
Move {
/// The commit to move, or an inclusive range `<first>..<last>` of
/// consecutive commits. Each may be a revision or a Stable-Commit-Id
/// (unique prefix ok). Must be commits of this queue.
commit: String,
/// The queue commit the moved commits should directly follow — a
/// revision or a Stable-Commit-Id. Pass the base branch's tip commit
/// to move them to the front of the queue.
#[arg(long)]
new_parent: String,
},
/// Requeue the current branch's descendants onto its tip.
#[command(visible_alias = "restack")]
#[command(
long_about = "The repair primitive: makes every descendant of the current branch consistent with its tip — nothing else. No network, no PR edits, no pruning. It is what the hooks run after a plain `git commit`/`--amend` (`--auto` stays silent when there is nothing to do), and the only command that reintegrates a `git queue checkout` editing session when hooks aren't installed. Reach for it manually after hand-made history surgery (cherry-picks, resets) leaves the branches above you stale."
)]
Requeue {
/// Quiet on no-op / non-queue branches (used by hooks).
#[arg(long)]
auto: bool,
},
/// Pull remote commits, requeue onto the latest base branch, and push (with lease).
#[command(
long_about = "The converge-with-reality command. Fetches with `--prune`, fast-forwards each queue's base branch, stamps Stable-Commit-Ids onto any queue commits missing them, drops branches whose work has landed (merged PRs, and squash-merges detected by Stable-Commit-Id), pulls genuinely new teammate commits (id correspondence guarantees your own rewrites are never re-applied over themselves), requeues the whole forest onto its bases, pushes everything back with `--force-with-lease`, and reconciles the PRs of every published queue — opening missing ones, reviving closed ones, refreshing bases, titles and queue maps. `--no-push` stops after the local requeue. It never pushes a branch that would make GitHub mislabel an open child PR as merged."
)]
Sync {
/// Skip pushing the branches back to the remote.
#[arg(long)]
no_push: bool,
},
/// Push the queue and open/update its numbered PRs.
#[command(visible_alias = "push")]
#[command(
long_about = "Publishes the current line: pushes every branch (front first, so bases exist), opens or revives its numbered PRs, and rewrites each PR's base, `[k/n]` title and body (queue map + About sections). Adopted PRs keep their hand-written titles (renumbered) and bodies. With the status gate enabled it also posts the red/green merge-order statuses. `--draft` opens new PRs as drafts."
)]
Submit {
/// Open new PRs as drafts.
#[arg(long)]
draft: bool,
},
/// Close every open (non-merged) PR in the current queue.
#[command(
long_about = "Closes every open PR of the current queue without merging — for abandoning or restarting a published queue. Merged PRs, local branches and metadata are all left untouched."
)]
Yank,
/// Interactive setup: hooks, gate, man page, completion, `git q` alias, agent skills.
#[command(
long_about = "Walks through git-queue's optional integrations, asking permission for each step: the git hooks (auto-requeue after plain commits, Stable-Commit-Id stamping), the advisory merge-order gate (red/green commit status per PR), the man page (`man git-queue`), shell completion for your shell, a `git q` alias in your global git config, the Claude Code skill (when Claude Code is detected), and a git-queue section in AGENTS.md (when other agent CLIs are detected — the cross-agent convention read by Codex, Cursor, Copilot and others). --yes accepts the two repo-local steps (hooks, gate) non-interactively; the user-scoped steps (man page, completion, alias, skill) are interactive only. --undo reverses everything."
)]
Setup {
/// Accept the hooks and gate steps without asking (integrations still ask).
#[arg(long)]
yes: bool,
/// Reverse setup: remove hooks, gate, skill and AGENTS.md section.
#[arg(long)]
undo: bool,
},
/// Report whether merge-order signalling is set up (read-only).
#[command(
long_about = "Read-only diagnosis of merge-order signalling: whether the status gate is enabled, and whether the GitHub CLI is ready. Changes nothing."
)]
Doctor,
/// Internal: `GIT_SEQUENCE_EDITOR` for id stamping (marks picks as reword).
#[command(hide = true, name = "stamp-todo")]
StampTodo {
/// Path to the rebase todo file (passed by git).
file: PathBuf,
},
/// Internal: commit-msg hook adding a `Stable-Commit-Id` trailer on queue branches.
#[command(hide = true, name = "add-queue-id")]
AddQueueId {
/// Path to the commit-message file (passed by git).
file: PathBuf,
},
/// Internal: `GIT_SEQUENCE_EDITOR` for `git queue move` (rewrites a rebase todo).
#[command(hide = true, name = "reorder-todo")]
ReorderTodo {
/// Path to the rebase todo file (passed by git).
file: PathBuf,
},
/// Print a shell completion script to stdout.
#[command(
long_about = "Prints a completion script for the given shell (bash, zsh, fish, elvish, powershell) to stdout. `git queue setup` installs this for you interactively; use this to install it by hand, e.g. `git queue completions zsh > ~/.local/share/zsh/site-functions/_git-queue`."
)]
Completions {
/// The shell to generate completions for.
shell: clap_complete::Shell,
},
/// Generate the roff man page (enables `git queue --help`; installed by `setup`).
#[command(hide = true)]
Man {
/// Directory to write `git-queue.1` into. Prints to stdout if omitted.
#[arg(long)]
dir: Option<PathBuf>,
},
}
/// The clap command tree — the single source used to render both the man page
/// and shell completions.
pub(crate) fn cli_command() -> clap::Command {
Cli::command()
}
/// Render the man page as roff text. `clap_mangen` produces the top-level page,
/// whose SUBCOMMANDS section references non-existent per-subcommand pages
/// (git-queue-init(1)); we replace it with a fully detailed COMMANDS section —
/// real `git queue <cmd>` names, the long description, and every argument —
/// generated from the same clap definitions.
pub(crate) fn man_text() -> anyhow::Result<String> {
let cmd = Cli::command();
let man = clap_mangen::Man::new(cmd.clone());
let mut buffer: Vec<u8> = Vec::new();
man.render(&mut buffer)?;
let text = String::from_utf8(buffer)?;
// Drop the auto-generated SUBCOMMANDS section (starts at .SH SUBCOMMANDS,
// ends at the next .SH) and put the detailed section in its place.
Ok(match text.find(".SH SUBCOMMANDS") {
Some(start) => {
let rest = &text[start + 4..];
let end = rest.find(".SH ").map_or(text.len(), |i| start + 4 + i);
format!(
"{}{}{}",
&text[..start],
commands_section(&cmd),
&text[end..]
)
}
None => text + &commands_section(&cmd),
})
}
/// Write the man page to `dir/git-queue.1`, or to stdout when `dir` is `None`.
fn generate_man(dir: Option<PathBuf>) -> anyhow::Result<()> {
use std::io::Write;
let text = man_text()?;
match dir {
Some(dir) => {
std::fs::create_dir_all(&dir)?;
let path = dir.join("git-queue.1");
std::fs::write(&path, text)?;
eprintln!("Wrote {}", path.display());
}
None => std::io::stdout().write_all(text.as_bytes())?,
}
Ok(())
}
fn roff(s: &str) -> String {
s.replace('\\', "\\\\").replace('-', "\\-")
}
/// One detailed roff section per visible subcommand.
fn commands_section(cmd: &clap::Command) -> String {
let mut out = String::from(".SH COMMANDS\n");
for sub in cmd.get_subcommands().filter(|s| !s.is_hide_set()) {
let mut synopsis = format!("git queue {}", sub.get_name());
for a in sub.get_arguments().filter(|a| a.get_id() != "help") {
let piece = if a.is_positional() {
let v = a.get_id().to_string().to_uppercase();
if a.is_required_set() {
format!("<{v}>")
} else {
format!("[{v}]")
}
} else {
let long = a.get_long().map(|l| format!("--{l}")).unwrap_or_default();
let val = if a.get_action().takes_values() {
format!(" <{}>", a.get_id().to_string().to_uppercase())
} else {
String::new()
};
if a.is_required_set() {
format!("{long}{val}")
} else {
format!("[{long}{val}]")
}
};
synopsis.push(' ');
synopsis.push_str(&piece);
}
out.push_str(&format!(".SS \\fB{}\\fR\n", roff(&synopsis)));
let aliases: Vec<String> = sub.get_visible_aliases().map(str::to_string).collect();
if !aliases.is_empty() {
out.push_str(&format!("Alias: {}\n.PP\n", roff(&aliases.join(", "))));
}
let about = sub
.get_long_about()
.or_else(|| sub.get_about())
.map(std::string::ToString::to_string)
.unwrap_or_default();
out.push_str(&format!("{}\n", roff(&about)));
for a in sub.get_arguments().filter(|a| a.get_id() != "help") {
let name = if a.is_positional() {
format!("<{}>", a.get_id().to_string().to_uppercase())
} else {
let val = if a.get_action().takes_values() {
format!(" <{}>", a.get_id().to_string().to_uppercase())
} else {
String::new()
};
format!("--{}{val}", a.get_long().unwrap_or_default())
};
let req = if a.is_required_set() {
" (required)"
} else {
" (optional)"
};
let help = a
.get_long_help()
.or_else(|| a.get_help())
.map(std::string::ToString::to_string)
.unwrap_or_default();
out.push_str(&format!(
".TP\n\\fB{}\\fR{}\n{}\n",
roff(&name),
req,
roff(&help)
));
}
}
out
}
/// Parse the CLI and run the selected subcommand. Exits the process on error.
/// Called by the `git-queue` binary.
pub fn run() {
let cli = Cli::parse();
let result = match cli.command {
Command::Create { name, base, queue } => {
commands::create(&name, base.as_deref(), queue.as_deref())
}
Command::Status => commands::status(),
Command::Ls => commands::ls(),
Command::Name { name } => commands::name(name),
Command::Log => commands::log(),
Command::Checkout { commit } => commands::checkout(&commit),
Command::Edit { queue } => commands::edit(queue.as_deref()),
Command::Tui => commands::tui(),
Command::Describe { message } => commands::describe(message),
Command::DescribeBranch { message } => commands::describe_branch(message),
Command::Track {
parent,
stamp_ids,
no_stamp_ids,
edit,
queue,
} => commands::track(parent, stamp_ids, no_stamp_ids, edit, queue.as_deref()),
Command::Untrack => commands::untrack(),
Command::Next => commands::next(),
Command::Prev => commands::prev(),
Command::Sync { no_push } => commands::sync(no_push),
Command::Submit { draft } => commands::submit(draft),
Command::Yank => commands::yank(),
Command::Doctor => commands::doctor(),
Command::Setup { yes, undo } => commands::setup(yes, undo),
Command::Commit { message } => commands::commit(message),
Command::Amend => commands::amend(),
Command::Reword { commit } => commands::reword(commit),
Command::Move { commit, new_parent } => commands::move_commits(&commit, &new_parent),
Command::StampTodo { file } => commands::stamp_todo(&file),
Command::AddQueueId { file } => commands::add_queue_id(&file),
Command::ReorderTodo { file } => commands::reorder_todo(&file),
Command::Requeue { auto } => commands::requeue(auto),
Command::Completions { shell } => commands::completions(shell),
Command::Man { dir } => generate_man(dir),
};
if let Err(e) = result {
eprintln!("error: {e:#}");
std::process::exit(1);
}
}