Skip to content

Commit 8a9f1c8

Browse files
skarimCopilot
andauthored
commands help text (#88)
* more help text for commands * improved root help * fix typo Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * updated examples for add cmd Co-authored-by: Sameen Karim <skarim@github.com> --------- Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
1 parent d159b80 commit 8a9f1c8

16 files changed

Lines changed: 339 additions & 90 deletions

File tree

‎cmd/add.go‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,17 @@ When -m is omitted but -A or -u is used, your editor opens for the
3030
commit message. When -m is provided without an explicit branch name,
3131
the branch name is auto-generated based on the commit message and
3232
stack prefix.`,
33+
Example: ` # Add a new named branch to the stack
34+
$ gh stack add my-feature
35+
36+
# Add a branch and commit staged changes
37+
$ gh stack add -Am "Add user authentication" my-feature
38+
39+
# Auto-generate branch name from the commit message
40+
$ gh stack add -m "Fix login bug"
41+
42+
# Add a branch and open editor to write commit message
43+
$ gh stack add -A my-feature`,
3344
Args: cobra.MaximumNArgs(1),
3445
RunE: func(cmd *cobra.Command, args []string) error {
3546
return runAdd(cfg, opts, args)

‎cmd/alias.go‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,14 @@ func AliasCmd(cfg *config.Config) *cobra.Command {
3232
This installs a small wrapper script into ~/.local/bin/ that forwards all
3333
arguments to "gh stack". The default alias name is "gs", but you can choose
3434
any name by passing it as an argument.`,
35+
Example: ` # Create the default 'gs' alias
36+
$ gh stack alias
37+
38+
# Create a custom alias
39+
$ gh stack alias gst
40+
41+
# Remove alias
42+
$ gh stack alias --remove`,
3543
Args: cobra.MaximumNArgs(1),
3644
RunE: func(cmd *cobra.Command, args []string) error {
3745
name := defaultAliasName

‎cmd/checkout.go‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,14 @@ locally tracked stacks only.
3838
3939
When run without arguments, shows a menu of all locally available
4040
stacks to choose from.`,
41+
Example: ` # Check out a stack by PR number
42+
$ gh stack checkout 42
43+
44+
# Check out a stack by branch name
45+
$ gh stack checkout feat/api-routes
46+
47+
# Show a menu of all locally tracked stacks
48+
$ gh stack checkout`,
4149
Args: cobra.MaximumNArgs(1),
4250
RunE: func(cmd *cobra.Command, args []string) error {
4351
if len(args) > 0 {
@@ -114,6 +122,8 @@ func runCheckout(cfg *config.Config, opts *checkoutOptions) error {
114122

115123
cfg.Successf("Switched to %s", targetBranch)
116124
cfg.Printf("Stack: %s", s.DisplayChain())
125+
cfg.Printf("Run `%s` to see the full stack",
126+
cfg.ColorCyan("gh stack view"))
117127
return nil
118128
}
119129

‎cmd/feedback.go‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,11 @@ func FeedbackCmd(cfg *config.Config) *cobra.Command {
1919
Use: "feedback [title]",
2020
Short: "Submit feedback for gh-stack",
2121
Long: "Opens a GitHub Discussion in the gh-stack repository to submit feedback. Optionally provide a title for the discussion post.",
22+
Example: ` # Open the feedback form in your browser
23+
$ gh stack feedback
24+
25+
# Open with a pre-filled title
26+
$ gh stack feedback "My feature request"`,
2227
RunE: func(cmd *cobra.Command, args []string) error {
2328
return runFeedback(cfg, args)
2429
},

‎cmd/link.go‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,14 @@ automatically with the correct base branch chaining.
4545
If the PRs are not yet in a stack, a new stack is created. If some of
4646
the PRs are already in a stack, the existing stack is updated to include
4747
the new PRs (existing PRs are never removed).`,
48+
Example: ` # Link branches into a stack (bottom to top)
49+
$ gh stack link auth-layer api-routes ui-components
50+
51+
# Link existing PRs by number
52+
$ gh stack link 41 42 43
53+
54+
# Specify a custom base branch for stack
55+
$ gh stack link --base develop auth-layer api-routes`,
4856
Args: cobra.MinimumNArgs(2),
4957
RunE: func(cmd *cobra.Command, args []string) error {
5058
return runLink(cfg, opts, args)

‎cmd/modify.go‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,14 @@ Operations available:
3434
3535
All changes are staged in the TUI and applied together when you press Ctrl+S.
3636
After applying, run 'gh stack submit' to push changes and recreate the stack on GitHub.`,
37+
Example: ` # Open the interactive TUI to restructure the stack
38+
$ gh stack modify
39+
40+
# Abort a modify session and restore the stack
41+
$ gh stack modify --abort
42+
43+
# Continue after resolving conflicts from a modify
44+
$ gh stack modify --continue`,
3745
RunE: func(cmd *cobra.Command, args []string) error {
3846
if opts.abort {
3947
return runModifyAbort(cfg)
@@ -202,9 +210,9 @@ func runModifyAbort(cfg *config.Config) error {
202210
if err := modify.UnwindFromStateFile(cfg, gitDir); err != nil {
203211
cfg.Errorf("recovery failed: %s", err)
204212
cfg.Printf("The stack may be in an inconsistent state.")
205-
cfg.Printf("Try `%s` to fix, or `%s` + `%s` to recreate.",
206-
cfg.ColorCyan("gh stack rebase"), cfg.ColorCyan("gh stack unstack --local"),
207-
cfg.ColorCyan("gh stack init --adopt"))
213+
cfg.Printf("Try `%s` to fix, or `%s` + `%s` to recreate.",
214+
cfg.ColorCyan("gh stack rebase"), cfg.ColorCyan("gh stack unstack --local"),
215+
cfg.ColorCyan("gh stack init --adopt"))
208216
return ErrSilent
209217
}
210218
cfg.Successf("Stack restored successfully")

‎cmd/navigate.go‎

Lines changed: 24 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,14 @@ func UpCmd(cfg *config.Config) *cobra.Command {
1212
return &cobra.Command{
1313
Use: "up [n]",
1414
Short: "Check out a branch further up in the stack (further from the trunk)",
15-
Args: cobra.MaximumNArgs(1),
15+
Long: `Check out a branch further up in the stack (further from the trunk).
16+
Merged branches are automatically skipped.`,
17+
Example: ` # Move one branch up
18+
$ gh stack up
19+
20+
# Move three branches up
21+
$ gh stack up 3`,
22+
Args: cobra.MaximumNArgs(1),
1623
RunE: func(cmd *cobra.Command, args []string) error {
1724
n := 1
1825
if len(args) > 0 {
@@ -32,7 +39,14 @@ func DownCmd(cfg *config.Config) *cobra.Command {
3239
return &cobra.Command{
3340
Use: "down [n]",
3441
Short: "Check out a branch further down in the stack (closer to the trunk)",
35-
Args: cobra.MaximumNArgs(1),
42+
Long: `Check out a branch further down in the stack (closer to the trunk).
43+
Merged branches are automatically skipped.`,
44+
Example: ` # Move one branch down
45+
$ gh stack down
46+
47+
# Move two branches down
48+
$ gh stack down 2`,
49+
Args: cobra.MaximumNArgs(1),
3650
RunE: func(cmd *cobra.Command, args []string) error {
3751
n := 1
3852
if len(args) > 0 {
@@ -52,6 +66,10 @@ func TopCmd(cfg *config.Config) *cobra.Command {
5266
return &cobra.Command{
5367
Use: "top",
5468
Short: "Check out the top branch of the stack (furthest from the trunk)",
69+
Long: `Check out the top branch of the stack (furthest from the trunk).
70+
Merged branches are automatically skipped.`,
71+
Example: ` # Jump to the top of the stack
72+
$ gh stack top`,
5573
RunE: func(cmd *cobra.Command, args []string) error {
5674
return runNavigateToEnd(cfg, true)
5775
},
@@ -62,6 +80,10 @@ func BottomCmd(cfg *config.Config) *cobra.Command {
6280
return &cobra.Command{
6381
Use: "bottom",
6482
Short: "Check out the bottom branch of the stack (closest to the trunk)",
83+
Long: `Check out the bottom branch of the stack (closest to the trunk).
84+
Merged branches are automatically skipped.`,
85+
Example: ` # Jump to the bottom of the stack
86+
$ gh stack bottom`,
6587
RunE: func(cmd *cobra.Command, args []string) error {
6688
return runNavigateToEnd(cfg, false)
6789
},

‎cmd/push.go‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,16 @@ func PushCmd(cfg *config.Config) *cobra.Command {
2222
cmd := &cobra.Command{
2323
Use: "push",
2424
Short: "Push all branches in the current stack to the remote",
25+
Long: `Push all branches in the current stack to the remote.
26+
27+
Uses --force-with-lease and --atomic to ensure safe, all-or-nothing pushes.
28+
Merged and queued branches are automatically skipped. This command is safe to
29+
run repeatedly — it will only update branches that have changed.`,
30+
Example: ` # Push all stack branches to the default remote
31+
$ gh stack push
32+
33+
# Push to a specific remote
34+
$ gh stack push --remote upstream`,
2535
RunE: func(cmd *cobra.Command, args []string) error {
2636
return runPush(cfg, opts)
2737
},
@@ -123,6 +133,8 @@ func runPush(cfg *config.Config, opts *pushOptions) error {
123133
if hasBranchWithoutPR {
124134
cfg.Printf("To create PRs for this stack, run `%s`",
125135
cfg.ColorCyan("gh stack submit"))
136+
} else {
137+
cfg.Printf("Run `%s` to see your stack of PRs", cfg.ColorCyan("gh stack view"))
126138
}
127139
return nil
128140
}

‎cmd/rebase.go‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,20 @@ func RebaseCmd(cfg *config.Config) *cobra.Command {
4646
4747
Ensures that each branch in the stack has the tip of the previous
4848
layer in its commit history, rebasing if necessary.`,
49+
Example: ` # Rebase the entire stack
50+
$ gh stack rebase
51+
52+
# Only rebase from trunk to the current branch
53+
$ gh stack rebase --downstack
54+
55+
# Only rebase from current branch to the top
56+
$ gh stack rebase --upstack
57+
58+
# Continue after resolving conflicts
59+
$ gh stack rebase --continue
60+
61+
# Abort and restore all branches
62+
$ gh stack rebase --abort`,
4963
Args: cobra.MaximumNArgs(1),
5064
RunE: func(cmd *cobra.Command, args []string) error {
5165
if len(args) > 0 {

‎cmd/root.go‎

Lines changed: 112 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,25 @@ func RootCmd() *cobra.Command {
1313
cfg := config.New()
1414

1515
root := &cobra.Command{
16-
Use: "stack <command>",
17-
Short: "Manage stacked branches and pull requests",
18-
Long: "Create, navigate, and manage stacks of branches and pull requests.",
16+
Use: "stack <command>",
17+
Short: "Manage stacked branches and pull requests",
18+
Long: `Stacked PRs let you break a large change into a chain of pull requests
19+
that build on each other. Use ` + "`gh stack`" + ` to create and manage your stack
20+
locally, then push to GitHub to create your stack of PRs.`,
21+
Example: ` # Start a new stack targeting your default branch
22+
$ gh stack init
23+
24+
# Or turn an existing set of branches into a stack
25+
$ gh stack init --adopt branch1 branch2 branch3
26+
27+
# Make changes and commit, then add a branch to the stack
28+
$ gh stack add branch4
29+
30+
# Push all branches and create/update PRs on GitHub
31+
$ gh stack submit
32+
33+
# Keep your local in sync with remote
34+
$ gh stack sync`,
1935
Version: Version,
2036
SilenceUsage: true,
2137
SilenceErrors: true,
@@ -26,36 +42,104 @@ func RootCmd() *cobra.Command {
2642
root.SetOut(cfg.Out)
2743
root.SetErr(cfg.Err)
2844

29-
// Local operations
30-
root.AddCommand(InitCmd(cfg))
31-
root.AddCommand(AddCmd(cfg))
45+
root.AddGroup(
46+
&cobra.Group{ID: "stack", Title: "Stack management:"},
47+
&cobra.Group{ID: "remote", Title: "Remote operations:"},
48+
&cobra.Group{ID: "nav", Title: "Navigation:"},
49+
&cobra.Group{ID: "utils", Title: "Utilities:"},
50+
)
51+
52+
defaultHelp := root.HelpFunc()
53+
root.SetHelpFunc(func(cmd *cobra.Command, args []string) {
54+
defaultHelp(cmd, args)
55+
if cmd.Name() == "stack" {
56+
out := cmd.OutOrStderr()
57+
fmt.Fprintln(out)
58+
fmt.Fprintln(out, "Learn more:")
59+
fmt.Fprintln(out, " Documentation: https://gh.io/stacks")
60+
fmt.Fprintln(out, " Feedback: https://gh.io/stacks-feedback")
61+
}
62+
})
3263

33-
// Remote operations
34-
root.AddCommand(CheckoutCmd(cfg))
35-
root.AddCommand(PushCmd(cfg))
36-
root.AddCommand(SubmitCmd(cfg))
37-
root.AddCommand(SyncCmd(cfg))
38-
root.AddCommand(UnstackCmd(cfg))
39-
root.AddCommand(MergeCmd(cfg))
40-
root.AddCommand(LinkCmd(cfg))
64+
// Stack management commands
65+
initCmd := InitCmd(cfg)
66+
initCmd.GroupID = "stack"
67+
root.AddCommand(initCmd)
4168

42-
// Helper commands
43-
root.AddCommand(ViewCmd(cfg))
44-
root.AddCommand(RebaseCmd(cfg))
45-
root.AddCommand(ModifyCmd(cfg))
69+
addCmd := AddCmd(cfg)
70+
addCmd.GroupID = "stack"
71+
root.AddCommand(addCmd)
4672

47-
// Navigation commands
48-
root.AddCommand(UpCmd(cfg))
49-
root.AddCommand(DownCmd(cfg))
50-
root.AddCommand(TopCmd(cfg))
51-
root.AddCommand(BottomCmd(cfg))
52-
root.AddCommand(SwitchCmd(cfg))
73+
viewCmd := ViewCmd(cfg)
74+
viewCmd.GroupID = "stack"
75+
root.AddCommand(viewCmd)
76+
77+
checkoutCmd := CheckoutCmd(cfg)
78+
checkoutCmd.GroupID = "stack"
79+
root.AddCommand(checkoutCmd)
80+
81+
modifyCmd := ModifyCmd(cfg)
82+
modifyCmd.GroupID = "stack"
83+
root.AddCommand(modifyCmd)
5384

54-
// Alias
55-
root.AddCommand(AliasCmd(cfg))
85+
unstackCmd := UnstackCmd(cfg)
86+
unstackCmd.GroupID = "stack"
87+
root.AddCommand(unstackCmd)
5688

57-
// Feedback
58-
root.AddCommand(FeedbackCmd(cfg))
89+
// Remote operations commands
90+
submitCmd := SubmitCmd(cfg)
91+
submitCmd.GroupID = "remote"
92+
root.AddCommand(submitCmd)
93+
94+
syncCmd := SyncCmd(cfg)
95+
syncCmd.GroupID = "remote"
96+
root.AddCommand(syncCmd)
97+
98+
rebaseCmd := RebaseCmd(cfg)
99+
rebaseCmd.GroupID = "remote"
100+
root.AddCommand(rebaseCmd)
101+
102+
pushCmd := PushCmd(cfg)
103+
pushCmd.GroupID = "remote"
104+
root.AddCommand(pushCmd)
105+
106+
linkCmd := LinkCmd(cfg)
107+
linkCmd.GroupID = "remote"
108+
root.AddCommand(linkCmd)
109+
110+
mergeCmd := MergeCmd(cfg)
111+
mergeCmd.GroupID = "remote"
112+
root.AddCommand(mergeCmd)
113+
114+
// Navigation commands
115+
switchCmd := SwitchCmd(cfg)
116+
switchCmd.GroupID = "nav"
117+
root.AddCommand(switchCmd)
118+
119+
upCmd := UpCmd(cfg)
120+
upCmd.GroupID = "nav"
121+
root.AddCommand(upCmd)
122+
123+
downCmd := DownCmd(cfg)
124+
downCmd.GroupID = "nav"
125+
root.AddCommand(downCmd)
126+
127+
topCmd := TopCmd(cfg)
128+
topCmd.GroupID = "nav"
129+
root.AddCommand(topCmd)
130+
131+
bottomCmd := BottomCmd(cfg)
132+
bottomCmd.GroupID = "nav"
133+
root.AddCommand(bottomCmd)
134+
135+
// Utility commands
136+
aliasCmd := AliasCmd(cfg)
137+
aliasCmd.GroupID = "utils"
138+
root.AddCommand(aliasCmd)
139+
140+
feedbackCmd := FeedbackCmd(cfg)
141+
feedbackCmd.GroupID = "utils"
142+
root.AddCommand(feedbackCmd)
59143

60144
return root
61145
}

0 commit comments

Comments
 (0)