but: switch command by estib-vega · Pull Request #14278 · gitbutlerapp/gitbutler

estib-vega · 2026-06-17T14:39:45Z

Usage

Switch to a local branch, workspace branch ID, or the GitButler workspace.

Examples

Switch to a branch:
but switch my-feature

Switch back to the GitButler workspace:
but switch --workspace

Create a new branch at the target and switch to it (canned name if no name is specified):
but switch --new my-feature
but switch --new

estib-vega · 2026-06-17T15:11:57Z

~~Waiting on this other PR #14277 to be merged to fix the integration test issues.~~

Good to go

Copilot

Pull request overview

Adds a new but switch subcommand to the but CLI, enabling users to switch to an existing local branch (by name, full ref, or workspace CLI ID), switch back to the GitButler workspace ref, or create-and-switch to a new branch. This fits into the CLI’s branching workflow alongside existing branch/workspace operations, and wires the command into help text and metrics.

Changes:

Introduces but switch command implementation and clap argument wiring (--workspace, --new, optional target).
Extends but-api branch checkout helpers with a workspace checkout entrypoint (ref-based checkout refactor).
Adds integration tests covering the main switch scenarios and several input validation cases.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
crates/but/tests/but/command/switch.rs	New integration tests for `but switch` behavior (existing branch, workspace, new branch, invalid inputs).
crates/but/tests/but/command/mod.rs	Registers the new `switch` test module.
crates/but/src/utils/metrics.rs	Maps `Subcommands::Switch` to the `Switch` metrics command name.
crates/but/src/lib.rs	Dispatches the `Switch` subcommand to `command::switch::handle`.
crates/but/src/command/switch.rs	Implements `but switch` behavior (workspace checkout, new branch checkout, existing local branch resolution).
crates/but/src/command/mod.rs	Exposes the new `switch` command module.
crates/but/src/command/help.rs	Adds `switch` into grouped help output.
crates/but/src/args/mod.rs	Defines the `Switch` clap subcommand, flags, argument grouping, and help text.
crates/but/src/args/metrics.rs	Adds `CommandName::Switch` for telemetry identifiers.
crates/but/src/args/atoms/branch_arg.rs	Gates `try_resolve_stack` behind `legacy` since atoms are now used outside legacy.
crates/but-api/src/branch.rs	Adds `workspace_checkout_with_perm` and factors checkout into a shared ref-based helper.

Copilot

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

+        /// Branch name, full local branch ref, or workspace CLI branch ID
+        target: Option<CliIdArg>,


+        /// Create a new branch at the target and switch to it
+        #[clap(long = "new", short = 'n')]
+        new: bool,


+        .stderr_eq(str![[r#"
+Error: Invalid branch. '94' is a commit
+
+"#]]);


Copilot

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.

+    if matches.len() > 1 {
+        return Err(anyhow::anyhow!(
+            "Branch '{}' is ambiguous. Try using more characters to disambiguate.",
+            target.0
+        )
+        .into());
+    }


+    if target.0.starts_with("refs/remotes/") || looks_like_remote_branch(&repo, &target.0) {
+        return Err(bad_input(format!(
+            "Can only switch to local branches, got '{}'",
+            target.0
+        ))
+        .into());
+    }
+
+    if let Ok(short_name) = Category::LocalBranch.to_full_name(target.0.as_str())
+        && repo.try_find_reference(short_name.as_ref())?.is_some()
+    {
+        return Ok(short_name);
+    }


estib-vega · 2026-06-22T08:24:22Z

Notes for reviewer: This command should be hidden for now, even if we add it. Since switching away from the workspace and then running other actions will trigger an error until something like: #14276 lands

slarse

Looks fine to add as a hidden command, but argument parsing should be consolidated with CLI atoms.

Note that hidden commands are added to auto completion, and users are likely to find switch very quickly. If we want it to be less discoverable, consider prepending an unusual character (e.g. _) to the command name until we're ready to release it to the masses.

slarse · 2026-06-22T08:22:43Z

+fn resolve_existing_local_branch(
+    ctx: &but_ctx::Context,
+    perm: &but_core::sync::RepoShared,
+    target: &CliIdArg,
+) -> CliResult<FullName> {
+    let repo = ctx.repo.get()?;
+
+    if target.0.starts_with("refs/heads/") {
+        let full_name = FullName::try_from(target.0.as_str())
+            .map_err(|_| bad_input(format!("Invalid branch ref '{}'", target.0)))?;
+        ensure_existing_local_branch(&repo, &full_name)?;
+        return Ok(full_name);
+    }
+
+    if target.0.starts_with("refs/remotes/") || looks_like_remote_branch(&repo, &target.0) {
+        return Err(bad_input(format!(
+            "Can only switch to local branches, got '{}'",
+            target.0
+        ))
+        .into());
+    }
+
+    if let Ok(short_name) = Category::LocalBranch.to_full_name(target.0.as_str())
+        && repo.try_find_reference(short_name.as_ref())?.is_some()
+    {
+        return Ok(short_name);
+    }
+
+    let id_map = IdMap::new_from_context(ctx, None, perm)?;
+    let matches = id_map.parse_using_context(&target.0, ctx)?;
+    if matches.is_empty() {
+        return Err(bad_input(format!("Could not find branch: '{}'", target.0)).into());
+    }
+    if matches.len() > 1 {
+        return Err(anyhow::anyhow!(
+            "Branch '{}' is ambiguous. Try using more characters to disambiguate.",
+            target.0
+        )
+        .into());
+    }
+
+    match &matches[0] {
+        CliId::Branch { name, .. } => {
+            let branch = Category::LocalBranch.to_full_name(name.as_str())?;
+            ensure_existing_local_branch(&repo, &branch)?;
+            Ok(branch)
+        }
+        other => {
+            let kind = match other {
+                CliId::Branch { .. } => unreachable!("handled above"),
+                CliId::Commit { .. } => "a commit",
+                CliId::Uncommitted(..) => "an uncommitted file",
+                CliId::PathPrefix { .. } => "a path",
+                CliId::CommittedFile { .. } => "a committed file",
+                CliId::Unassigned { .. } => "unassigned changes",
+                CliId::Stack { .. } => "a stack",
+            };
+            Err(bad_input(format!("Invalid branch. '{}' is {kind}", target.0)).into())
+        }
+    }
+}


We try to contain this kind of resolution to CLI atoms, this duplicates lot of that code. I think BranchArg::resolve_branch() should do the trick, see if you can use that instead.

I don't know if we have any existing code path from CliIdArg all the way to an unapplied branch, but you should be able to cobble it together from CLI atoms, perhaps with some minimal extension.

estib-vega · 2026-06-22T08:31:43Z

Looks fine to add as a hidden command, but argument parsing should be consolidated with CLI atoms.

Thanks! I'll address the changes and hide the command.

Add a command to switch to an new or existing ref. And back to the workspace.

estib-vega · 2026-06-22T10:56:43Z

Addressed the feedback

github-actions Bot added rust Pull requests that update Rust code CLI The command-line program `but` labels Jun 17, 2026

estib-vega force-pushed the but-switch-command branch from 9371b86 to 96871ac Compare June 17, 2026 15:11

estib-vega requested review from davidpdrsn and slarse June 17, 2026 15:12

estib-vega force-pushed the but-switch-command branch from 96871ac to 8ca6d40 Compare June 17, 2026 15:15

estib-vega marked this pull request as ready for review June 17, 2026 15:15

Copilot AI review requested due to automatic review settings June 17, 2026 15:15

Copilot started reviewing on behalf of estib-vega June 17, 2026 15:16 View session

Copilot AI reviewed Jun 17, 2026

View reviewed changes

Comment thread crates/but/tests/but/command/switch.rs Outdated

Comment thread crates/but/src/args/mod.rs Outdated

estib-vega force-pushed the but-switch-command branch from 8ca6d40 to 7baca4e Compare June 18, 2026 07:28

Copilot AI review requested due to automatic review settings June 18, 2026 07:46

estib-vega force-pushed the but-switch-command branch from 7baca4e to be4fea3 Compare June 18, 2026 07:46

Copilot started reviewing on behalf of estib-vega June 18, 2026 07:47 View session

Copilot AI reviewed Jun 18, 2026

View reviewed changes

estib-vega force-pushed the but-switch-command branch from be4fea3 to 0b84953 Compare June 18, 2026 08:02

Copilot AI review requested due to automatic review settings June 18, 2026 08:31

estib-vega force-pushed the but-switch-command branch from 0b84953 to 95f8f4c Compare June 18, 2026 08:31

Copilot started reviewing on behalf of estib-vega June 18, 2026 08:31 View session

Copilot AI reviewed Jun 18, 2026

View reviewed changes

slarse approved these changes Jun 22, 2026

View reviewed changes

but: switch command

142012e

Add a command to switch to an new or existing ref. And back to the workspace.

estib-vega force-pushed the but-switch-command branch from 95f8f4c to 142012e Compare June 22, 2026 10:54

estib-vega enabled auto-merge June 22, 2026 10:55

estib-vega merged commit 6454170 into master Jun 22, 2026
39 checks passed

estib-vega deleted the but-switch-command branch June 22, 2026 11:11

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

but: switch command#14278

but: switch command#14278
estib-vega merged 1 commit into
masterfrom
but-switch-command

estib-vega commented Jun 17, 2026 •

edited

Loading

Uh oh!

estib-vega commented Jun 17, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

estib-vega commented Jun 22, 2026

Uh oh!

slarse left a comment •

edited

Loading

Uh oh!

slarse Jun 22, 2026

Uh oh!

estib-vega commented Jun 22, 2026

Uh oh!

estib-vega commented Jun 22, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		/// Branch name, full local branch ref, or workspace CLI branch ID
		target: Option<CliIdArg>,

Uh oh!

Conversation

estib-vega commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Usage

Examples

Uh oh!

estib-vega commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

estib-vega commented Jun 22, 2026

Uh oh!

slarse left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

slarse Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

estib-vega commented Jun 22, 2026

Uh oh!

estib-vega commented Jun 22, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

estib-vega commented Jun 17, 2026 •

edited

Loading

estib-vega commented Jun 17, 2026 •

edited

Loading

slarse left a comment •

edited

Loading