Skip to main content

gitq rename

Renames a branch, in git and in the stack tree, in one step.

Usage​

bash
gitq rename <old> <new> [--stack <name>]

Flags​

flagmeaning
--stack <name>Which tracked stack <old> belongs to. Optional when the repo has exactly one; required otherwise. See Global flags.

Behavior​

Guarded by the stack lease. Rewrites the branch directly in the worktree you ran it from, so it refuses up front if <old> is checked out anywhere else, dirty or not: branch "<old>" is checked out in slot "<slot>" (<path>); run this from that worktree or free the branch first (refuseIfCheckedOutElsewhere, src/cli/commands/surgery.ts:33-42,243-245).

Runs git branch -m <old> <new> (src/core/git-shell.ts:594-596), then renames the node in the stack tree, keeping its parent and its children (renameBranch, src/core/branch-rename.ts:17-26; StackManager.renameBranch, src/core/stack-manager.ts:181-198). No commits move and nothing is rebased.

  • Refuses if <old> isn't a node in the stack (Branch "<old>" not found in stack "<id>"), or <new> already is (Branch "<new>" already exists in stack "<id>").
  • The git rename happens first: if it fails (<new> already exists as a git branch), the stack tree is left untouched.
  • Renaming a published branch does not rename it on the forge. The old name stays on the remote, and the MR is still attached to it.

Recorded to the operation log under rename, but not reversible: rename is not one of the four types in REVERSIBLE_OPERATIONS, so gitq undo afterward refuses with cannot undo "rename" (not reversible) (src/core/undo.ts:16-21).

Exit codes​

  • 0: renamed.
  • 1: <old> checked out elsewhere, <old> not found, <new> already exists (in git or in the stack), or a lease held.

Never exits 2. See Exit codes for the general contract.

See also​