glab mr checkout: add --worktree flag to checkout MR into a git worktree

Problem to solve

As a developer reviewing merge requests, I want to check out an MR into a separate git worktree, so I can review or test it without disrupting my current working directory.

Currently, glab mr checkout switches the branch in the current worktree, which means I have to stash or commit any in-progress work first. A third-party tool (worktree-cli) already wraps glab to provide this functionality.

Proposal

Add a --worktree <path> flag (or -w) to glab mr checkout that creates a new git worktree at the specified path with the MR's source branch checked out.

For example:

glab mr checkout 123 --worktree ../review-mr-123

This would be equivalent to:

branch=$(glab mr view 123 --output json | jq -r '.source_branch') git fetch origin "$branch" git worktree add ../review-mr-123 "origin/$branch"

A sensible default path convention (e.g. ../mr-<id>) could also be supported when --worktree is passed without a value.

Further details

  • This is especially useful for reviewers who want to run tests or explore code while continuing their own work

Links / references

Implementation plan

Note: This plan was drafted during an AI-assisted triage of the backlog and has not been validated by a maintainer. Treat it as a starting point: file paths, line numbers, and the approach may need adjusting.

An implementation of this already exists in merge request !3900 (merged). These steps describe the same change, for reference or in case that MR stalls.

  1. Add a worktree string field to options in internal/commands/mr/checkout/mr_checkout.go and register the flag in NewCmdCheckout: fl.StringVarP(&opts.worktree, "worktree", "w", "", "Check out the merge request into a new Git worktree at <path> instead of the current working directory.").
  2. In (*options).run, keep every step up to the checkout unchanged (MR resolution, fetch of the source branch, branch.<name>.remote and branch.<name>.merge config). Replace only the final step: when o.worktree != "", run o.gr.GitWithIO(o.io.StdOut, o.io.StdErr, "worktree", "add", o.worktree, o.branch) instead of "checkout", o.branch, and wrap the error with the path and branch so a pre-existing path is actionable.
  3. Fix the --set-upstream-to path in the same function: git branch --set-upstream-to <upstream> applies to the current branch, which is wrong once the checkout happens in another worktree. Pass the branch explicitly: o.gr.Git("branch", "--set-upstream-to", o.upstream, o.branch). This is correct in both modes.
  4. Extend internal/commands/mr/checkout/mr_checkout_test.go with cases asserting the recorded git commands: --worktree <path> issues git worktree add <path> <branch> and never git checkout, the default path still issues git checkout, and --worktree combined with --set-upstream-to issues git branch --set-upstream-to <upstream> <branch>. Use the existing cmdtest setup in that file.
  5. Update Long and Example on the cobra.Command to document the flag, then run make gen-docs and commit the regenerated docs/source/mr/checkout.md in the same commit.
  6. The issue also floats an optional default path (../mr-<id>) when --worktree is passed with no value. Leave that out of the first change: a Cobra string flag with an optional value needs NoOptDefVal, and the default convention is worth deciding separately.
Edited by Kai Armstrong