feat: improve av stack reorder UX

internal/actions/sync_branch.go

@@ -355,8 +355,8 @@ func syncBranchRebase(
 
 	// Scenario 3: the branch is not up-to-date with its parent.
 	_, _ = fmt.Fprint(os.Stderr,
-		"  - synching branch ", colors.UserInput(branch.Name),
-		" on latest commit ", git.ShortSha(parentHead),
+		"  - syncing branch ", colors.UserInput(branch.Name),
+		" on latest commit ", colors.UserInput(git.ShortSha(parentHead)),
 		" of parent branch ", colors.UserInput(parentState.Name),
 		"\n",
 	)

internal/git/git.go

@@ -112,6 +112,9 @@ type Output struct {
 
 func (o Output) Lines() []string {
 	s := strings.TrimSpace(string(o.Stdout))
+	if s == "" {
+		return nil
+	}
 	return strings.Split(s, "\n")
 }
 

internal/reorder/editor.go

@@ -23,6 +23,7 @@ func EditPlan(repo *git.Repo, plan []Cmd) ([]Cmd, error) {
 		text.WriteString(cmd.String())
 		text.WriteString("\n")
 	}
+	text.WriteString(instructionsText)
 
 	res, err := editor.Launch(repo, editor.Config{
 		Text:              text.String(),
@@ -76,3 +77,18 @@ func Diff(old []Cmd, new []Cmd) PlanDiff {
 		AddedBranches:   sliceutils.Subtract(newBranches, oldBranches),
 	}
 }
+
+const instructionsText = `
+# Instructions:
+#
+# Commands:
+# sb, stack-branch <branch-name> [--parent <parent-branch-name> | --trunk <trunk-branch-name>]
+#         Create a new branch as part of a stack. If parent is not specified,
+#         the previous branch in the stack is used (if any). If trunk is
+#         specified, the branch is rooted from the given branch.
+#         trunk-branch-name can be either a branch name or a branch name with a
+#         commit ID in the format "<branch-name>@<commit-id>".
+# p, pick <commit-id>
+#         Pick a commit to be included in the stack. Only valid after a
+#         stack-branch command.
+`

internal/reorder/plan.go

@@ -37,9 +37,9 @@ func CreatePlan(repo *git.Repo, tx meta.ReadTx, rootBranch string) ([]Cmd, error
 			branchCmd.Trunk = branch.Parent.Name + "@" + trunkCommit
 			upstreamCommit = trunkCommit
 		}
-		cmds = append(cmds, branchCmd)
 
-		// Add a pick command for every commit associated with this branch
+		// Figure out the commits that belong to this branch.
+		// We'll use this to generate a "pick" command for each commit.
 		commitIDs, err := repo.RevList(git.RevListOpts{
 			Specifiers: []string{branchName, "^" + upstreamCommit},
 			Reverse:    true,
@@ -48,13 +48,23 @@ func CreatePlan(repo *git.Repo, tx meta.ReadTx, rootBranch string) ([]Cmd, error
 			return nil, err
 		}
 
+		// If no commits associated with this branch, bail out early and add a
+		// helpful comment for the user.
+		if len(commitIDs) == 0 {
+			branchCmd.Comment = "this branch has no commits"
+			cmds = append(cmds, branchCmd)
+			continue
+		}
+
 		commitObjects, err := repo.GetRefs(&git.GetRefs{
 			Revisions: commitIDs,
 		})
 		if err != nil {
 			return nil, err
 		}
 
+		// Append the "stack-branch" command and each "pick" command to the plan
+		cmds = append(cmds, branchCmd)
 		for _, object := range commitObjects {
 			commit, err := git.ParseCommitContents(object.Contents)
 			if err != nil {

internal/reorder/stackbranch.go

@@ -26,6 +26,8 @@ type StackBranchCmd struct {
 	// The branch can be rooted at a given commit by appending "@<commit>" to the
 	// branch name.
 	Trunk string
+	// An optional comment to include in the reorder plan for this command.
+	Comment string
 }
 
 func (b StackBranchCmd) Execute(ctx *Context) error {
@@ -98,6 +100,10 @@ func (b StackBranchCmd) String() string {
 		sb.WriteString(" --trunk ")
 		sb.WriteString(b.Trunk)
 	}
+	if b.Comment != "" {
+		sb.WriteString("  # ")
+		sb.WriteString(b.Comment)
+	}
 	return sb.String()
 }