abbreviated workflow to quickly add to stacks

Author: skarim

README.md

@@ -59,14 +59,15 @@ 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. 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 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`.
 
 Enables `git rerere` automatically so that conflict resolutions are remembered across rebases.
 
 | Flag | Description |
 |------|-------------|
 | `-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 |
 
 **Examples:**
 
@@ -82,23 +83,57 @@ 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
+gh stack init -p feat
 ```
 
 ### `gh stack add`
 
 Add a new branch on top of the current stack.
 
 ```
-gh stack add [branch]
+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.
+
+| Flag | Description |
+|------|-------------|
+| `-a, --all` | Stage all changes (including untracked files); requires `-m` |
+| `-u, --update` | Stage changes to tracked files only; requires `-m` |
+| `-m, --message <string>` | Create a commit with this message before creating the branch |
+
+> **Note:** `-a` and `-u` are mutually exclusive.
+
 **Examples:**
 
 ```sh
+# Create a branch by name
 gh stack add api-routes
-gh stack add  # prompts for name
+
+# Prompt for a branch name interactively
+gh stack add
+
+# Stage all changes, commit, and auto-generate the branch name
+gh stack add -am "Add login endpoint"
+
+# Stage only tracked files, commit, and auto-generate the branch name
+gh stack add -um "Fix auth bug"
+
+# Commit already-staged changes and auto-generate the branch name
+gh stack add -m "Add user model"
+
+# Stage all changes, commit, and use an explicit branch name
+gh stack add -am "Add tests" test-layer
+
+# Stage only tracked files, commit, and use an explicit branch name
+gh stack add -um "Update docs" docs-layer
+
+# Commit already-staged changes and use an explicit branch name
+gh stack add -m "Refactor utils" cleanup-layer
 ```
 
 ### `gh stack checkout`
@@ -355,3 +390,42 @@ gh stack push
 # 8. When the first PR is merged, sync the stack
 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.
+
+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
+#    → creates feat/01 and checks it out
+
+# 2. Write code for the first layer
+#    ... write code ...
+
+# 3. Stage and commit on the current branch
+gh stack add -am "Auth middleware"
+#    → feat/01 has no commits yet, so the commit lands here
+#      (no new branch is created)
+
+# 4. Write code for the next layer
+#    ... write code ...
+
+# 5. Create the next branch and commit
+gh stack add -am "API routes"
+#    → feat/01 already has commits, so a new branch feat/02 is
+#      created, checked out, and the commit lands there
+
+# 6. Keep going
+#    ... write code ...
+
+gh stack add -am "Frontend components"
+#    → feat/02 already has commits, creates feat/03 and commits there
+
+# 7. Push everything and create PRs
+gh stack push
+```
+
+Compared to the typical workflow, there's no need to name branches, run `git add`, or run `git commit` separately. Each `gh stack add -am "..."` does it all.

cmd/add.go

@@ -3,25 +3,58 @@ package cmd
 import (
 	"fmt"
 
+	"github.com/github/gh-stack/internal/branch"
 	"github.com/github/gh-stack/internal/config"
 	"github.com/github/gh-stack/internal/git"
 	"github.com/github/gh-stack/internal/stack"
 	"github.com/spf13/cobra"
 )
 
+type addOptions struct {
+	stageAll     bool
+	stageTracked bool
+	message      string
+}
+
 func AddCmd(cfg *config.Config) *cobra.Command {
+	opts := &addOptions{}
+
 	cmd := &cobra.Command{
 		Use:   "add [branch]",
 		Short: "Add a new branch on top of the current stack",
-		Args:  cobra.MaximumNArgs(1),
+		Long: `Add a new branch on top of the current stack.
+
+Optionally stage changes and create a commit before creating the branch:
+  -a    Stage all changes (including untracked) before committing
+  -u    Stage tracked file changes before committing
+  -m    Create a commit with the given message
+
+When -m is provided without an explicit branch name, the branch name
+is auto-generated based on the commit message and stack prefix.`,
+		Args: cobra.MaximumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return runAdd(cfg, args)
+			return runAdd(cfg, opts, args)
 		},
 	}
+
+	cmd.Flags().BoolVarP(&opts.stageAll, "all", "a", false, "Stage all changes including untracked files")
+	cmd.Flags().BoolVarP(&opts.stageTracked, "update", "u", false, "Stage changes to tracked files only")
+	cmd.Flags().StringVarP(&opts.message, "message", "m", "", "Create a commit with this message")
+
 	return cmd
 }
 
-func runAdd(cfg *config.Config, args []string) error {
+func runAdd(cfg *config.Config, opts *addOptions, args []string) error {
+	// Validate flag combinations
+	if opts.stageAll && opts.stageTracked {
+		cfg.Errorf("flags -a and -u are mutually exclusive")
+		return nil
+	}
+	if (opts.stageAll || opts.stageTracked) && opts.message == "" {
+		cfg.Errorf("staging flags (-a, -u) require -m to create a commit")
+		return nil
+	}
+
 	gitDir, err := git.GitDir()
 	if err != nil {
 		cfg.Errorf("not a git repository")
@@ -69,14 +102,82 @@ func runAdd(cfg *config.Config, args []string) error {
 		return nil
 	}
 
+	// When -m is provided, check if the current branch is a stack branch with
+	// no unique commits relative to its parent. If so, the commit should land
+	// on this branch without creating a new one (e.g., right after init).
+	var branchIsEmpty bool
+	if opts.message != "" && idx >= 0 {
+		parentBranch := s.ActiveBaseBranch(currentBranch)
+		commits, _ := git.LogRange(parentBranch, currentBranch)
+		branchIsEmpty = len(commits) == 0
+	}
+
+	// Empty branch path: stage and commit here, don't create a new branch.
+	if branchIsEmpty && opts.message != "" {
+		if opts.stageAll {
+			if err := git.StageAll(); err != nil {
+				cfg.Errorf("failed to stage changes: %s", err)
+				return nil
+			}
+		} else if opts.stageTracked {
+			if err := git.StageTracked(); err != nil {
+				cfg.Errorf("failed to stage changes: %s", err)
+				return nil
+			}
+		}
+		if !git.HasStagedChanges() {
+			cfg.Errorf("nothing to commit; stage changes first or use -a/-u")
+			return nil
+		}
+		sha, err := git.Commit(opts.message)
+		if err != nil {
+			cfg.Errorf("failed to commit: %s", err)
+			return nil
+		}
+		cfg.Successf("Created commit %s on %s", cfg.ColorBold(sha[:7]), currentBranch)
+		cfg.Warningf("Branch %s has no prior commits — adding your commit here instead of creating a new branch", currentBranch)
+		cfg.Printf("When you're ready for the next layer, run %s again", cfg.ColorCyan("gh stack add"))
+		return nil
+	}
+
+	// Resolve branch name
 	var branchName string
+	var explicitName string
 	if len(args) > 0 {
-		branchName = args[0]
+		explicitName = args[0]
+	}
+
+	if opts.message != "" {
+		// Auto-naming mode
+		existingBranches := s.BranchNames()
+		isFirstBranch := len(existingBranches) == 0
+		name, info := branch.ResolveBranchName(s.Prefix, opts.message, explicitName, existingBranches, isFirstBranch)
+		if name == "" {
+			cfg.Errorf("could not generate branch name")
+			return nil
+		}
+		branchName = name
+		if info != "" {
+			cfg.Infof("%s", info)
+		}
+	} else if explicitName != "" {
+		// No -m, but explicit name given
+		if s.Prefix != "" {
+			branchName = s.Prefix + "/" + explicitName
+			cfg.Infof("Branch name prefixed: %s", branchName)
+		} else {
+			branchName = explicitName
+		}
 	} else {
+		// No -m, no explicit name — prompt
 		fmt.Fprintf(cfg.Err, "Enter a name for the new branch: ")
 		if _, err := fmt.Fscan(cfg.In, &branchName); err != nil {
 			return fmt.Errorf("could not read branch name: %w", err)
 		}
+		if s.Prefix != "" && branchName != "" {
+			branchName = s.Prefix + "/" + branchName
+			cfg.Infof("Branch name prefixed: %s", branchName)
+		}
 	}
 
 	if branchName == "" {
@@ -90,10 +191,11 @@ func runAdd(cfg *config.Config, args []string) error {
 	}
 
 	if git.BranchExists(branchName) {
-		cfg.Errorf("branch %q already exists", branchName)
+		cfg.Errorf("branch %q already exists; provide an explicit name", branchName)
 		return nil
 	}
 
+	// Create the new branch from the current HEAD and check it out
 	if err := git.CreateBranch(branchName, currentBranch); err != nil {
 		cfg.Errorf("failed to create branch: %s", err)
 		return nil
@@ -107,11 +209,44 @@ func runAdd(cfg *config.Config, args []string) error {
 	base, _ := git.HeadSHA(currentBranch)
 	s.Branches = append(s.Branches, stack.BranchRef{Branch: branchName, Base: base})
 
+	// Stage and commit on the NEW branch if -m is provided
+	var commitSHA string
+	if opts.message != "" {
+		if opts.stageAll {
+			if err := git.StageAll(); err != nil {
+				cfg.Errorf("failed to stage changes: %s", err)
+				return nil
+			}
+		} else if opts.stageTracked {
+			if err := git.StageTracked(); err != nil {
+				cfg.Errorf("failed to stage changes: %s", err)
+				return nil
+			}
+		}
+		if !git.HasStagedChanges() {
+			cfg.Errorf("nothing to commit; stage changes first or use -a/-u")
+			return nil
+		}
+		sha, err := git.Commit(opts.message)
+		if err != nil {
+			cfg.Errorf("failed to commit: %s", err)
+			return nil
+		}
+		commitSHA = sha[:7]
+	}
+
 	if err := stack.Save(gitDir, sf); err != nil {
 		cfg.Errorf("failed to save stack state: %s", err)
 		return nil
 	}
 
-	cfg.Successf("Created and checked out branch %q", branchName)
+	// Print summary
+	position := len(s.Branches)
+	if commitSHA != "" {
+		cfg.Successf("Created branch %s (layer %d) with commit %s", cfg.ColorBold(branchName), position, commitSHA)
+	} else {
+		cfg.Successf("Created and checked out branch %q", branchName)
+	}
+
 	return nil
 }