Skip to content

Commit 0f53bd4

Browse files
skarimskarim
committed
more help text for commands
1 parent 05de7e1 commit 0f53bd4

13 files changed

Lines changed: 152 additions & 10 deletions

File tree

‎cmd/add.go‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,14 @@ 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"
38+
39+
# Auto-generate branch name from the commit message
40+
$ gh stack add -m "Fix login bug"`,
3341
Args: cobra.MaximumNArgs(1),
3442
RunE: func(cmd *cobra.Command, args []string) error {
3543
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/submit.go‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,24 @@ func SubmitCmd(cfg *config.Config) *cobra.Command {
2929
cmd := &cobra.Command{
3030
Use: "submit",
3131
Short: "Create a stack of PRs on GitHub",
32+
Long: `Push all branches and create or update a stack of PRs on GitHub.
33+
34+
This command performs several steps:
35+
1. Pushes all branches to the remote
36+
2. Creates new PRs for branches that don't have one
37+
3. Updates base branches for existing PRs
38+
4. Creates or updates the stack on GitHub
39+
40+
New PRs are created as drafts by default. Use --open to mark them as ready
41+
for review.`,
42+
Example: ` # Push and create/update PRs (prompts for PR titles)
43+
$ gh stack submit
44+
45+
# Use auto-generated PR titles without prompting
46+
$ gh stack submit --auto
47+
48+
# Mark all PRs as ready for review
49+
$ gh stack submit --open`,
3250
RunE: func(cmd *cobra.Command, args []string) error {
3351
return runSubmit(cfg, opts)
3452
},

0 commit comments

Comments
 (0)