From 39ee151b70787927b5fe095fdff43feb8d0803c6 Mon Sep 17 00:00:00 2001 From: Luis Ball Date: Mon, 29 Dec 2025 14:20:24 -0800 Subject: [PATCH 1/2] docs: update log documentation for smart defaults Update docs/log.md to document the new smart default behavior: - Stack discovery from current branch - New flags: --branch, --all, --ci, --trunk - CI usage examples - On trunk branch behavior - No PR found behavior with gh pr create suggestion Also add reference to status command in 'See also' section. --- docs/log.md | 82 ++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 78 insertions(+), 4 deletions(-) diff --git a/docs/log.md b/docs/log.md index 5378b42..1c845a0 100644 --- a/docs/log.md +++ b/docs/log.md @@ -5,13 +5,32 @@ Visualize your stack's structure and status. ## Usage ```bash +# Infer stack from current branch (recommended) +gh-stack log + +# Infer from a specific branch +gh-stack log --branch feat/my-feature + +# List all stacks and select interactively +gh-stack log --all + +# Search by identifier in PR titles gh-stack log 'STACK-ID' -gh-stack log 'STACK-ID' --short # compact list view -gh-stack log 'STACK-ID' --include-closed # show closed/merged PRs -gh-stack log 'STACK-ID' --no-color # disable colors and unicode -gh-stack log 'STACK-ID' -C /path/to/repo # specify repo path + +# CI mode (non-interactive) +gh-stack log --branch $GITHUB_HEAD_REF --ci ``` +## Stack Discovery + +When run without an identifier, `gh-stack log` automatically discovers your stack by: + +1. Finding the PR for your current branch +2. Walking up the PR base chain to find ancestors +3. Walking down to find PRs that build on yours + +This works with any PR structure - no special naming required. + ## Output The default tree view shows: @@ -50,7 +69,12 @@ The `--short` flag shows a compact list: | Flag | Description | |------|-------------| +| `--branch`, `-b` | Infer stack from this branch instead of current | +| `--all`, `-a` | List all stacks and select interactively | +| `--ci` | Non-interactive mode for CI environments | +| `--trunk` | Override trunk branch (default: auto-detect or "main") | | `--short`, `-s` | Compact list format instead of tree | +| `--status` | Show CI, approval, and merge status bits | | `--include-closed` | Show branches with closed/merged PRs | | `--no-color` | Disable colors and unicode characters | | `-C`, `--project` | Path to local repository | @@ -58,6 +82,55 @@ The `--short` flag shows a compact list: | `-o`, `--origin` | Git remote name (default: origin) | | `-e`, `--excl` | Exclude PR by number (repeatable) | +## CI Usage + +In CI environments, use `--ci` to disable interactive prompts: + +```bash +# Must provide branch explicitly +gh-stack log --branch $GITHUB_HEAD_REF --ci + +# Or use identifier +gh-stack log 'STACK-ID' --ci +``` + +The `--ci` flag will: +- Fail with an error if no identifier or branch is provided +- Fail if on a trunk branch without an identifier +- Never prompt for user input + +## On Trunk Branch + +When you're on a trunk branch (main, master, etc.), `gh-stack log` will prompt you to: + +1. Enter a stack identifier manually +2. Select from detected stacks in the repository +3. Cancel + +``` +You're on 'main' (trunk branch). + +? What would you like to do? +> Enter a stack identifier + Select from detected stacks (3 found) + Cancel +``` + +## No PR Found + +If no PR exists for your current branch: + +``` +No PR found for branch 'feat/new-feature'. + +Create a PR with: + gh pr create --base main --head feat/new-feature + +? Create PR now? [Y/n] +``` + +If you confirm, `gh-stack` will run `gh pr create` for you. + ## When to use - Before rebasing to understand stack structure @@ -68,4 +141,5 @@ The `--short` flag shows a compact list: ## See also - [annotate](annotate.md) - Add stack tables to PR descriptions +- [status](status.md) - Show CI and approval status - [land](land.md) - Merge the stack From 267e10f89d86a26d8e9920973cdd1ebd12a41fb5 Mon Sep 17 00:00:00 2001 From: Luis Ball Date: Mon, 29 Dec 2025 15:29:30 -0800 Subject: [PATCH 2/2] docs: update status documentation for smart defaults Update docs/status.md to document the new smart default behavior: - Stack discovery from current branch - New flags: --branch, --all, --ci, --trunk - CI usage examples - Updated options table with new flags - Reorganized examples section --- docs/status.md | 82 +++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 65 insertions(+), 17 deletions(-) diff --git a/docs/status.md b/docs/status.md index ab5f9c1..cc6d4f1 100644 --- a/docs/status.md +++ b/docs/status.md @@ -5,11 +5,35 @@ Show stack status with CI, approval, and merge readiness indicators. ## Usage ```bash -gh-stack status [OPTIONS] -# or -gh-stack log --status [OPTIONS] +# Infer stack from current branch (recommended) +gh-stack status + +# Infer from a specific branch +gh-stack status --branch feat/my-feature + +# List all stacks and select interactively +gh-stack status --all + +# Search by identifier in PR titles +gh-stack status 'STACK-ID' + +# CI mode (non-interactive) +gh-stack status --branch $GITHUB_HEAD_REF --ci + +# Use with log command +gh-stack log --status 'STACK-ID' ``` +## Stack Discovery + +When run without an identifier, `gh-stack status` automatically discovers your stack by: + +1. Finding the PR for your current branch +2. Walking up the PR base chain to find ancestors +3. Walking down to find PRs that build on yours + +This works with any PR structure - no special naming required. + ## Description The `status` command displays your PR stack with status bits showing: @@ -68,19 +92,43 @@ Status: [CI | Approved | Mergeable | Stack] | Flag | Description | |------|-------------| -| `--no-checks` | Skip fetching CI/approval/conflict status (faster, shows basic tree) | +| `--branch`, `-b` | Infer stack from this branch instead of current | +| `--all`, `-a` | List all stacks and select interactively | +| `--ci` | Non-interactive mode for CI environments | +| `--trunk` | Override trunk branch (default: auto-detect or "main") | +| `--no-checks` | Skip fetching CI/approval/conflict status (faster) | | `--no-color` | Disable colors and Unicode characters | | `--help-legend` | Show status bits legend | | `--json` | Output in JSON format | | `-C, --project ` | Path to local repository | | `-r, --repository ` | Specify repository (owner/repo) | | `-o, --origin ` | Git remote to use (default: origin) | -| `-e, --excl ` | Exclude PR by number (can be used multiple times) | +| `-e, --excl ` | Exclude PR by number (repeatable) | + +## CI Usage + +In CI environments, use `--ci` to disable interactive prompts: + +```bash +# Must provide branch explicitly +gh-stack status --branch $GITHUB_HEAD_REF --ci + +# Or use identifier +gh-stack status 'STACK-ID' --ci + +# JSON output for parsing +gh-stack status --branch $GITHUB_HEAD_REF --ci --json +``` + +The `--ci` flag will: +- Fail with an error if no identifier or branch is provided +- Fail if on a trunk branch without an identifier +- Never prompt for user input ## JSON Output ```bash -gh-stack status STACK-123 --json +gh-stack status --json ``` ```json @@ -113,41 +161,41 @@ gh-stack status STACK-123 --json The legend is shown automatically on first run. To see it again: ```bash -gh-stack status STACK-123 --help-legend +gh-stack status --help-legend ``` The legend marker is stored in `~/.gh-stack-legend-seen`. ## Examples -### Basic usage +### Infer from current branch ```bash -gh-stack status JIRA-1234 +gh-stack status ``` -### Skip API calls for faster output +### Infer from specific branch ```bash -gh-stack status JIRA-1234 --no-checks +gh-stack status --branch feat/my-feature ``` -### Specify repository explicitly +### Skip API calls for faster output ```bash -gh-stack status JIRA-1234 -r owner/repo +gh-stack status --no-checks ``` -### Output as JSON for scripting +### Specify repository explicitly ```bash -gh-stack status JIRA-1234 --json | jq '.stack[].status.ci' +gh-stack status -r owner/repo ``` -### Use with log command +### Output as JSON for scripting ```bash -gh-stack log --status JIRA-1234 +gh-stack status --json | jq '.stack[].status.ci' ``` ## See Also