checkout: add spice.checkout.verbose config

This adds a new configuration option that controls whether checkout
navigation commands print verbose messages when switching branches.
The option defaults to true but allows users to opt out.

Resolves #717

Author: abhinav

.changes/unreleased/Added-20250716-202212.yaml

@@ -0,0 +1,5 @@
+kind: Added
+body: |
+  Add 'spice.checkout.verbose' configuration option
+  to report the branch name when checking out a branch.
+time: 2025-07-16T20:22:12.449527-07:00

doc/includes/cli-reference.md

@@ -579,7 +579,7 @@ By default, branches are sorted by name.
 * `--detach`: Detach HEAD after checking out
 * `-u`, `--untracked` ([:material-wrench:{ .middle title="spice.branchCheckout.showUntracked" }](/cli/config.md#spicebranchcheckoutshowuntracked)): Show untracked branches if one isn't supplied
 
-**Configuration**: [spice.branchCheckout.showUntracked](/cli/config.md#spicebranchcheckoutshowuntracked), [spice.branchCheckout.trackUntrackedPrompt](/cli/config.md#spicebranchcheckouttrackuntrackedprompt), [spice.branchPrompt.sort](/cli/config.md#spicebranchpromptsort)
+**Configuration**: [spice.branchCheckout.showUntracked](/cli/config.md#spicebranchcheckoutshowuntracked), [spice.branchCheckout.trackUntrackedPrompt](/cli/config.md#spicebranchcheckouttrackuntrackedprompt), [spice.branchPrompt.sort](/cli/config.md#spicebranchpromptsort), [spice.checkout.verbose](/cli/config.md#spicecheckoutverbose)
 
 ### gs branch create
 
@@ -1036,6 +1036,8 @@ Use the -n flag to print the branch without checking it out.
 * `-n`, `--dry-run`: Print the target branch without checking it out
 * `--detach`: Detach HEAD after checking out
 
+**Configuration**: [spice.checkout.verbose](/cli/config.md#spicecheckoutverbose)
+
 ### gs down
 
 ```
@@ -1058,6 +1060,8 @@ Use the -n flag to print the branch without checking it out.
 * `-n`, `--dry-run`: Print the target branch without checking it out
 * `--detach`: Detach HEAD after checking out
 
+**Configuration**: [spice.checkout.verbose](/cli/config.md#spicecheckoutverbose)
+
 ### gs top
 
 ```
@@ -1076,6 +1080,8 @@ Use the -n flag to print the branch without checking it out.
 * `-n`, `--dry-run`: Print the target branch without checking it out
 * `--detach`: Detach HEAD after checking out
 
+**Configuration**: [spice.checkout.verbose](/cli/config.md#spicecheckoutverbose)
+
 ### gs bottom
 
 ```
@@ -1092,6 +1098,8 @@ Use the -n flag to print the branch without checking it out.
 * `-n`, `--dry-run`: Print the target branch without checking it out
 * `--detach`: Detach HEAD after checking out
 
+**Configuration**: [spice.checkout.verbose](/cli/config.md#spicecheckoutverbose)
+
 ### gs trunk
 
 ```
@@ -1105,6 +1113,8 @@ Move to the trunk branch
 * `-n`, `--dry-run`: Print the target branch without checking it out
 * `--detach`: Detach HEAD after checking out
 
+**Configuration**: [spice.checkout.verbose](/cli/config.md#spicecheckoutverbose)
+
 ## gs version
 
 ```

doc/src/cli/config.md

@@ -112,6 +112,20 @@ Commonly used values are:
 - `<name>/`: the committer's name
 - `<username>/`: the committer's username
 
+### spice.checkout.verbose
+
+<!-- gs:version unreleased -->
+
+Whether branch navigation commands
+($$gs up$$, $$gs down$$, $$gs top$$, $$gs bottom$$,
+$$gs trunk$$, $$gs branch checkout$$)
+should print a message when switching branches.
+
+**Accepted values:**
+
+- `true` (default)
+- `false`
+
 ### spice.forge.github.apiUrl
 
 URL at which the GitHub API is available.

internal/handler/checkout/handler.go

@@ -23,6 +23,8 @@ import (
 type Options struct {
 	DryRun bool `short:"n" xor:"detach-or-dry-run" help:"Print the target branch without checking it out"`
 	Detach bool `xor:"detach-or-dry-run" help:"Detach HEAD after checking out"`
+
+	Verbose bool `name:"checkout-verbose" hidden:"" default:"true" config:"checkout.verbose"`
 }
 
 // Store provides access to the git-spice state.
@@ -133,5 +135,9 @@ func (h *Handler) CheckoutBranch(ctx context.Context, req *Request) error {
 		return fmt.Errorf("checkout branch: %w", err)
 	}
 
+	if opts.Verbose {
+		log.Infof("switched to branch: %s", branch)
+	}
+
 	return nil
 }

internal/handler/checkout/handler_test.go

@@ -499,3 +499,89 @@ func TestHandler_CheckoutBranch_EdgeCases(t *testing.T) {
 		assert.ErrorIs(t, err, detachError)
 	})
 }
+
+func TestHandler_CheckoutBranch_Verbose(t *testing.T) {
+	mockStore := NewMockStore(gomock.NewController(t))
+	mockStore.
+		EXPECT().
+		Trunk().
+		Return("main").
+		AnyTimes()
+
+	t.Run("VerboseTrue", func(t *testing.T) {
+		ctrl := gomock.NewController(t)
+		mockWorktree := NewMockGitWorktree(ctrl)
+
+		var logBuffer bytes.Buffer
+		handler := &Handler{
+			Stdout:   io.Discard,
+			Log:      silog.New(&logBuffer, nil),
+			Store:    mockStore,
+			Worktree: mockWorktree,
+			Track:    NewMockTrackHandler(ctrl),
+			Service:  NewMockService(ctrl),
+		}
+
+		mockWorktree.
+			EXPECT().
+			Checkout(gomock.Any(), "main").
+			Return(nil)
+
+		err := handler.CheckoutBranch(t.Context(), &Request{
+			Branch:  "main",
+			Options: &Options{Verbose: true},
+		})
+		assert.NoError(t, err)
+		assert.Contains(t, logBuffer.String(), "switched to branch: main")
+	})
+
+	t.Run("VerboseFalse", func(t *testing.T) {
+		ctrl := gomock.NewController(t)
+		mockWorktree := NewMockGitWorktree(ctrl)
+
+		var logBuffer bytes.Buffer
+		handler := &Handler{
+			Stdout:   io.Discard,
+			Log:      silog.New(&logBuffer, nil),
+			Store:    mockStore,
+			Worktree: mockWorktree,
+			Track:    NewMockTrackHandler(ctrl),
+			Service:  NewMockService(ctrl),
+		}
+
+		mockWorktree.
+			EXPECT().
+			Checkout(gomock.Any(), "main").
+			Return(nil)
+
+		err := handler.CheckoutBranch(t.Context(), &Request{
+			Branch:  "main",
+			Options: &Options{Verbose: false},
+		})
+		assert.NoError(t, err)
+		assert.NotContains(t, logBuffer.String(), "switched to branch")
+	})
+
+	t.Run("DryRunNoVerbose", func(t *testing.T) {
+		ctrl := gomock.NewController(t)
+
+		var logBuffer bytes.Buffer
+		var stdout bytes.Buffer
+		handler := &Handler{
+			Stdout:   &stdout,
+			Log:      silog.New(&logBuffer, nil),
+			Store:    mockStore,
+			Worktree: NewMockGitWorktree(ctrl),
+			Track:    NewMockTrackHandler(ctrl),
+			Service:  NewMockService(ctrl),
+		}
+
+		err := handler.CheckoutBranch(t.Context(), &Request{
+			Branch:  "main",
+			Options: &Options{DryRun: true, Verbose: true},
+		})
+		assert.NoError(t, err)
+		assert.Equal(t, "main\n", stdout.String())
+		assert.NotContains(t, logBuffer.String(), "switched to branch")
+	})
+}

testdata/script/checkout_verbose.txt

@@ -0,0 +1,71 @@
+# Test checkout verbose messages with default and configured behaviors.
+
+as 'Test <test@example.com>'
+at '2025-07-17T21:28:29Z'
+
+# Setup repository
+mkdir repo
+cd repo
+git init
+git commit --allow-empty -m 'Initial commit'
+gs repo init
+
+# Create a simple stack
+gs branch create feature1 -m 'Add feature1'
+gs branch create feature2 -m 'Add feature2'
+
+# Test 1: Default behavior - verbose should be true by default, showing messages
+gs top
+gs down
+stderr 'switched to branch: feature1'
+
+gs up
+stderr 'switched to branch: feature2'
+
+gs trunk
+stderr 'switched to branch: main'
+
+gs top
+stderr 'switched to branch: feature2'
+
+gs bottom
+stderr 'switched to branch: feature1'
+
+# Test 2: Explicitly set verbose to true
+git config spice.checkout.verbose true
+
+gs down
+stderr 'switched to branch: main'
+
+gs up
+stderr 'switched to branch: feature1'
+
+# Test 3: Opt out of verbose messages
+git config spice.checkout.verbose false
+
+gs up
+! stderr 'switched to branch'
+
+gs down
+! stderr 'switched to branch'
+
+gs top
+! stderr 'switched to branch'
+
+gs bottom
+! stderr 'switched to branch'
+
+gs trunk
+! stderr 'switched to branch'
+
+# Test 4: Dry run should not show checkout message (regardless of config)
+git config spice.checkout.verbose true
+
+gs bco feature1
+gs up -n
+stdout 'feature2'
+! stderr 'switched to branch'
+
+gs down -n
+stdout 'main'
+! stderr 'switched to branch'