default to named branches, numbering is a flag set on init

Author: skarim

README.md

@@ -71,7 +71,9 @@ Initialize a new stack in the current repository.
 gh stack init [branches...] [flags]
 ```
 
-Creates an entry in `.git/gh-stack` to track stack state. In interactive mode (no arguments), prompts you to name branches and offers to use the current branch as the first layer. In interactive mode, you'll also be prompted to set an optional branch prefix for auto-naming (unless adopting existing branches). When explicit branch names are given, creates any that don't already exist (branching from the trunk). The trunk defaults to the repository's default branch unless overridden with `--base`.
+Creates an entry in `.git/gh-stack` to track stack state. In interactive mode (no arguments), prompts you to name branches and offers to use the current branch as the first layer. In interactive mode, you'll also be prompted to set an optional branch prefix (unless adopting existing branches). When a prefix is set, branch names you enter are automatically prefixed. When explicit branch names are given, creates any that don't already exist (branching from the trunk). The trunk defaults to the repository's default branch unless overridden with `--base`.
+
+Use `--numbered` with `--prefix` to enable auto-incrementing numbered branch names (`prefix/01`, `prefix/02`, …). Without `--numbered`, you'll always be prompted to provide a meaningful branch name.
 
 Enables `git rerere` automatically so that conflict resolutions are remembered across rebases.
 
@@ -80,6 +82,7 @@ Enables `git rerere` automatically so that conflict resolutions are remembered a
 | `-b, --base <branch>` | Trunk branch for the stack (defaults to the repository's default branch) |
 | `-a, --adopt` | Adopt existing branches into a stack instead of creating new ones |
 | `-p, --prefix <string>` | Set a branch name prefix for the stack |
+| `-n, --numbered` | Use auto-incrementing numbered branch names (requires `--prefix`) |
 
 **Examples:**
 
@@ -96,8 +99,14 @@ gh stack init --base develop feature-auth
 # Adopt existing branches into a stack
 gh stack init --adopt feature-auth feature-api
 
-# Set a prefix for auto-naming branches
+# Set a prefix — you'll be prompted for a branch name
 gh stack init -p feat
+#    → prompts "Enter a name for the first branch (will be prefixed with feat/)"
+#    → type "auth" → creates feat/auth
+
+# Use numbered auto-incrementing branch names
+gh stack init -p feat --numbered
+#    → creates feat/01 automatically
 ```
 
 ### `gh stack add`
@@ -110,7 +119,7 @@ gh stack add [branch] [flags]
 
 Creates a new branch at the current HEAD, adds it to the top of the stack, and checks it out. Must be run while on the topmost branch of a stack. If no branch name is given, prompts for one.
 
-You can optionally stage changes and create a commit as part of the `add` flow. When `-m` is provided without an explicit branch name, the branch name is auto-generated. Auto-generated names use either numbered format (`prefix/01`, `prefix/02`) or date+slug format depending on prefix configuration and existing branch naming patterns.
+You can optionally stage changes and create a commit as part of the `add` flow. When `-m` is provided without an explicit branch name, the branch name is auto-generated. If the stack was created with `--numbered`, auto-generated names use numbered format (`prefix/01`, `prefix/02`); otherwise, date+slug format is used (e.g., `prefix/2025-03-24-add-login`).
 
 | Flag | Description |
 |------|-------------|
@@ -409,13 +418,13 @@ gh stack sync
 
 ## Abbreviated workflow
 
-If you want to minimize keystrokes, use a branch prefix and the `-Am` flags to fold staging, committing, and branch creation into a single command. Branch names are auto-generated from your commit messages.
+If you want to minimize keystrokes, use a branch prefix with `--numbered` and the `-Am` flags to fold staging, committing, and branch creation into a single command. Branch names are auto-generated as `prefix/01`, `prefix/02`, etc.
 
 When a branch has no commits yet (e.g., right after `init`), `add -Am` stages and commits directly on that branch instead of creating a new one. Once a branch has commits, `add -Am` creates a new branch, checks it out, and commits there.
 
 ```sh
-# 1. Start a stack with a prefix
-gh stack init -p feat
+# 1. Start a stack with a prefix and numbered branches
+gh stack init -p feat --numbered
 #    → creates feat/01 and checks it out
 
 # 2. Write code for the first layer

cmd/add.go

@@ -111,8 +111,7 @@ func runAdd(cfg *config.Config, opts *addOptions, args []string) error {
 
 	if opts.message != "" {
 		// Auto-naming mode
-		isFirstBranch := len(existingBranches) == 0
-		name, info := branch.ResolveBranchName(s.Prefix, opts.message, explicitName, existingBranches, isFirstBranch)
+		name, info := branch.ResolveBranchName(s.Prefix, opts.message, explicitName, existingBranches, s.Numbered)
 		if name == "" {
 			cfg.Errorf("could not generate branch name")
 			return ErrSilent
@@ -124,10 +123,9 @@ func runAdd(cfg *config.Config, opts *addOptions, args []string) error {
 	} else if explicitName != "" {
 		branchName = applyPrefix(cfg, s.Prefix, explicitName)
 	} else {
-		// No -m, no explicit name — auto-generate if following numbered
+		// No -m, no explicit name — auto-generate if using numbered
 		// convention, otherwise prompt for a name.
-		if s.Prefix != "" && len(existingBranches) > 0 &&
-			branch.FollowsNumbering(s.Prefix, existingBranches[len(existingBranches)-1]) {
+		if s.Numbered && s.Prefix != "" {
 			branchName = branch.NextNumberedName(s.Prefix, existingBranches)
 		} else {
 			p := prompter.New(cfg.In, cfg.Out, cfg.Err)

cmd/add_test.go

@@ -278,6 +278,7 @@ func TestAdd_NumberedNaming(t *testing.T) {
 	gitDir := t.TempDir()
 	saveStack(t, gitDir, stack.Stack{
 		Prefix:   "feat",
+		Numbered: true,
 		Trunk:    stack.BranchRef{Branch: "main"},
 		Branches: []stack.BranchRef{{Branch: "feat/01"}},
 	})

cmd/init.go

@@ -18,6 +18,7 @@ type initOptions struct {
 	base     string
 	adopt    bool
 	prefix   string
+	numbered bool
 }
 
 func InitCmd(cfg *config.Config) *cobra.Command {
@@ -43,6 +44,7 @@ Trunk defaults to default branch, unless specified otherwise.`,
 	cmd.Flags().StringVarP(&opts.base, "base", "b", "", "Trunk branch for stack (defaults to default branch)")
 	cmd.Flags().BoolVarP(&opts.adopt, "adopt", "a", false, "Track existing branches as part of a stack")
 	cmd.Flags().StringVarP(&opts.prefix, "prefix", "p", "", "Branch name prefix for the stack")
+	cmd.Flags().BoolVarP(&opts.numbered, "numbered", "n", false, "Use auto-incrementing numbered branch names (requires --prefix)")
 
 	return cmd
 }
@@ -99,6 +101,13 @@ func runInit(cfg *config.Config, opts *initOptions) error {
 
 	var branches []string
 
+	// Validate --numbered requires a prefix (either from flag or interactive input,
+	// but for non-interactive paths we can check early).
+	if opts.numbered && opts.prefix == "" && !cfg.IsInteractive() {
+		cfg.Errorf("--numbered requires --prefix")
+		return ErrInvalidArgs
+	}
+
 	if opts.adopt {
 		// Adopt mode: validate all specified branches exist
 		if len(opts.branches) == 0 {
@@ -160,69 +169,40 @@ func runInit(cfg *config.Config, opts *initOptions) error {
 
 		// Step 1: Ask for prefix
 		if opts.prefix == "" {
-			prefixInput, err := p.Input("Set a branch prefix? (leave blank to skip)", "")
-			if err != nil {
-				if isInterruptError(err) {
-					printInterrupt(cfg)
-					return ErrSilent
-				}
-				cfg.Errorf("failed to read prefix: %s", err)
-				return ErrSilent
-			}
-			opts.prefix = strings.TrimSpace(prefixInput)
-		}
-
-		// Step 2: Ask for branch name
-		if currentBranch != "" && currentBranch != trunk {
-			// Already on a non-trunk branch — offer to use it
-			useCurrentBranch, err := p.Confirm(
-				fmt.Sprintf("Would you like to use %s as the first layer of your stack?", currentBranch),
-				true,
-			)
-			if err != nil {
-				if isInterruptError(err) {
-					printInterrupt(cfg)
+			if opts.numbered {
+				// --numbered requires a prefix; prompt specifically for one
+				prefixInput, err := p.Input("Enter a branch prefix (required for --numbered)", "")
+				if err != nil {
+					if isInterruptError(err) {
+						printInterrupt(cfg)
+						return ErrSilent
+					}
+					cfg.Errorf("failed to read prefix: %s", err)
 					return ErrSilent
 				}
-				cfg.Errorf("failed to confirm branch selection: %s", err)
-				return ErrSilent
-			}
-			if useCurrentBranch {
-				if err := sf.ValidateNoDuplicateBranch(currentBranch); err != nil {
-					cfg.Errorf("branch %q already exists in the stack", currentBranch)
+				opts.prefix = strings.TrimSpace(prefixInput)
+				if opts.prefix == "" {
+					cfg.Errorf("--numbered requires a prefix")
 					return ErrInvalidArgs
 				}
-				branches = []string{currentBranch}
-			}
-		}
-
-		if len(branches) == 0 {
-			prompt := "What branch would you like to use as the first layer of your stack?"
-			if opts.prefix != "" {
-				prompt = fmt.Sprintf("Name the first branch, or leave blank to use %s", branch.NextNumberedName(opts.prefix, nil))
-			}
-			branchName, err := p.Input(prompt, "")
-			if err != nil {
-				if isInterruptError(err) {
-					printInterrupt(cfg)
+			} else {
+				prefixInput, err := p.Input("Set a branch prefix? (leave blank to skip)", "")
+				if err != nil {
+					if isInterruptError(err) {
+						printInterrupt(cfg)
+						return ErrSilent
+					}
+					cfg.Errorf("failed to read prefix: %s", err)
 					return ErrSilent
 				}
-				cfg.Errorf("failed to read branch name: %s", err)
-				return ErrSilent
-			}
-			branchName = strings.TrimSpace(branchName)
-
-			if branchName == "" && opts.prefix != "" {
-				// Auto-generate numbered branch name
-				branchName = branch.NextNumberedName(opts.prefix, nil)
-			} else if branchName == "" {
-				cfg.Errorf("branch name cannot be empty")
-				return ErrInvalidArgs
-			} else if opts.prefix != "" {
-				// Prepend prefix to the user-provided name
-				branchName = opts.prefix + "/" + branchName
+				opts.prefix = strings.TrimSpace(prefixInput)
 			}
+		}
 
+		// Step 2: Ask for branch name (unless --numbered auto-generates it)
+		if opts.numbered {
+			// Auto-generate numbered branch name
+			branchName := branch.NextNumberedName(opts.prefix, nil)
 			if err := sf.ValidateNoDuplicateBranch(branchName); err != nil {
 				cfg.Errorf("branch %q already exists in a stack", branchName)
 				return ErrInvalidArgs
@@ -234,6 +214,67 @@ func runInit(cfg *config.Config, opts *initOptions) error {
 				}
 			}
 			branches = []string{branchName}
+		} else {
+			if currentBranch != "" && currentBranch != trunk {
+				// Already on a non-trunk branch — offer to use it
+				useCurrentBranch, err := p.Confirm(
+					fmt.Sprintf("Would you like to use %s as the first layer of your stack?", currentBranch),
+					true,
+				)
+				if err != nil {
+					if isInterruptError(err) {
+						printInterrupt(cfg)
+						return ErrSilent
+					}
+					cfg.Errorf("failed to confirm branch selection: %s", err)
+					return ErrSilent
+				}
+				if useCurrentBranch {
+					if err := sf.ValidateNoDuplicateBranch(currentBranch); err != nil {
+						cfg.Errorf("branch %q already exists in the stack", currentBranch)
+						return ErrInvalidArgs
+					}
+					branches = []string{currentBranch}
+				}
+			}
+
+			if len(branches) == 0 {
+				prompt := "What branch would you like to use as the first layer of your stack?"
+				if opts.prefix != "" {
+					prompt = fmt.Sprintf("Enter a name for the first branch (will be prefixed with %s/)", opts.prefix)
+				}
+				branchName, err := p.Input(prompt, "")
+				if err != nil {
+					if isInterruptError(err) {
+						printInterrupt(cfg)
+						return ErrSilent
+					}
+					cfg.Errorf("failed to read branch name: %s", err)
+					return ErrSilent
+				}
+				branchName = strings.TrimSpace(branchName)
+
+				if branchName == "" {
+					cfg.Errorf("branch name cannot be empty")
+					return ErrInvalidArgs
+				}
+
+				if opts.prefix != "" {
+					branchName = opts.prefix + "/" + branchName
+				}
+
+				if err := sf.ValidateNoDuplicateBranch(branchName); err != nil {
+					cfg.Errorf("branch %q already exists in a stack", branchName)
+					return ErrInvalidArgs
+				}
+				if !git.BranchExists(branchName) {
+					if err := git.CreateBranch(branchName, trunk); err != nil {
+						cfg.Errorf("creating branch %s: %s", branchName, err)
+						return ErrSilent
+					}
+				}
+				branches = []string{branchName}
+			}
 		}
 	}
 
@@ -258,7 +299,8 @@ func runInit(cfg *config.Config, opts *initOptions) error {
 	}
 
 	newStack := stack.Stack{
-		Prefix: opts.prefix,
+		Prefix:   opts.prefix,
+		Numbered: opts.numbered,
 		Trunk: stack.BranchRef{
 			Branch: trunk,
 			Head:   trunkSHA,

internal/branch/name.go

@@ -97,10 +97,10 @@ func NextNumberedName(prefix string, existingBranches []string) string {
 //   - message: commit message (from -m flag; may be empty if not using auto-naming)
 //   - explicitName: branch name provided as argument (may be empty)
 //   - existingBranches: current branch names in the stack
-//   - isFirstBranch: true if this is the first branch being added to the stack
+//   - numbered: true if the stack uses auto-incrementing numbered branches
 //
 // Returns the resolved branch name and an informational message (may be empty).
-func ResolveBranchName(prefix, message, explicitName string, existingBranches []string, isFirstBranch bool) (name string, info string) {
+func ResolveBranchName(prefix, message, explicitName string, existingBranches []string, numbered bool) (name string, info string) {
 	if explicitName != "" {
 		// Explicit name provided
 		if prefix != "" {
@@ -118,18 +118,10 @@ func ResolveBranchName(prefix, message, explicitName string, existingBranches []
 	}
 
 	if prefix != "" {
-		// Check if we should use numbered format
-		useNumbering := isFirstBranch
-		if !useNumbering && len(existingBranches) > 0 {
-			lastBranch := existingBranches[len(existingBranches)-1]
-			useNumbering = FollowsNumbering(prefix, lastBranch)
-		}
-
-		if useNumbering {
+		if numbered {
 			name = NextNumberedName(prefix, existingBranches)
 		} else {
 			name = prefix + "/" + DateSlug(message)
-			info = "Branch name auto-generated using date+slug format because existing branches don't follow numbering convention"
 		}
 	} else {
 		// No prefix — always use date+slug

internal/branch/name_test.go

@@ -98,24 +98,23 @@ func TestResolveBranchName(t *testing.T) {
 		assert.Empty(t, info)
 	})
 
-	t.Run("message with prefix first branch uses numbered format", func(t *testing.T) {
+	t.Run("message with prefix and numbered uses numbered format", func(t *testing.T) {
 		name, _ := ResolveBranchName("stack", "add login", "", nil, true)
 		assert.Equal(t, "stack/01", name)
 	})
 
-	t.Run("message with prefix last branch follows numbering uses next number", func(t *testing.T) {
+	t.Run("message with prefix and numbered continues sequence", func(t *testing.T) {
 		existing := []string{"stack/01", "stack/02"}
-		name, _ := ResolveBranchName("stack", "add login", "", existing, false)
+		name, _ := ResolveBranchName("stack", "add login", "", existing, true)
 		assert.Equal(t, "stack/03", name)
 	})
 
-	t.Run("message with prefix last branch not numbered uses date-slug", func(t *testing.T) {
+	t.Run("message with prefix not numbered uses date-slug", func(t *testing.T) {
 		existing := []string{"stack/some-feature"}
-		name, info := ResolveBranchName("stack", "add login", "", existing, false)
+		name, _ := ResolveBranchName("stack", "add login", "", existing, false)
 		today := time.Now().Format("2006-01-02")
 		assert.True(t, strings.HasPrefix(name, "stack/"+today), "expected date prefix, got: %s", name)
 		assert.Contains(t, name, "add-login")
-		assert.NotEmpty(t, info, "should explain why date+slug was used")
 	})
 
 	t.Run("message without prefix uses date-slug", func(t *testing.T) {

internal/stack/stack.go

@@ -37,6 +37,7 @@ type BranchRef struct {
 type Stack struct {
 	ID       string      `json:"id,omitempty"`
 	Prefix   string      `json:"prefix,omitempty"`
+	Numbered bool        `json:"numbered,omitempty"`
 	Trunk    BranchRef   `json:"trunk"`
 	Branches []BranchRef `json:"branches"`
 }