|
|
|
|
@@ -1,35 +1,118 @@
|
|
|
|
|
---
|
|
|
|
|
name: git-commit-push-pr
|
|
|
|
|
description: Commit, push, and open a PR with an adaptive, value-first description. Use when the user says "commit and PR", "push and open a PR", "ship this", "create a PR", "open a pull request", "commit push PR", or wants to go from working changes to an open pull request in one step. Produces PR descriptions that scale in depth with the complexity of the change, avoiding cookie-cutter templates.
|
|
|
|
|
description: Commit, push, and open a PR with an adaptive, value-first description. Use when the user says "commit and PR", "push and open a PR", "ship this", "create a PR", "open a pull request", "commit push PR", or wants to go from working changes to an open pull request in one step. Also use when the user says "update the PR description", "refresh the PR description", "freshen the PR", or wants to rewrite an existing PR description. Produces PR descriptions that scale in depth with the complexity of the change, avoiding cookie-cutter templates.
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
# Git Commit, Push, and PR
|
|
|
|
|
|
|
|
|
|
Go from working tree changes to an open pull request in a single workflow. The key differentiator of this skill is PR descriptions that communicate *value and intent* proportional to the complexity of the change.
|
|
|
|
|
Go from working tree changes to an open pull request in a single workflow, or update an existing PR description. The key differentiator of this skill is PR descriptions that communicate *value and intent* proportional to the complexity of the change.
|
|
|
|
|
|
|
|
|
|
## Workflow
|
|
|
|
|
## Mode detection
|
|
|
|
|
|
|
|
|
|
If the user is asking to update, refresh, or rewrite an existing PR description (with no mention of committing or pushing), this is a **description-only update**. The user may also provide a focus for the update (e.g., "update the PR description and add the benchmarking results"). Note any focus instructions for use in DU-3.
|
|
|
|
|
|
|
|
|
|
For description-only updates, follow the Description Update workflow below. Otherwise, follow the full workflow.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Description Update workflow
|
|
|
|
|
|
|
|
|
|
### DU-1: Confirm intent
|
|
|
|
|
|
|
|
|
|
Ask the user to confirm: "Update the PR description for this branch?" Use the platform's blocking question tool (`AskUserQuestion` in Claude Code, `request_user_input` in Codex, `ask_user` in Gemini). If no question tool is available, present the question and wait for the user's reply.
|
|
|
|
|
|
|
|
|
|
If the user declines, stop.
|
|
|
|
|
|
|
|
|
|
### DU-2: Find the PR
|
|
|
|
|
|
|
|
|
|
Run these commands to identify the branch and locate the PR:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
git branch --show-current
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
If empty (detached HEAD), report that there is no branch to update and stop.
|
|
|
|
|
|
|
|
|
|
Otherwise, check for an existing open PR:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
gh pr view --json url,title,state
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Interpret the result. Do not treat every non-zero exit as a fatal error here:
|
|
|
|
|
|
|
|
|
|
- If it returns PR data with `state: OPEN`, an open PR exists for the current branch.
|
|
|
|
|
- If it returns PR data with a non-OPEN state (CLOSED, MERGED), treat this as "no open PR." Report that no open PR exists for this branch and stop.
|
|
|
|
|
- If it exits non-zero and the output indicates that no pull request exists for the current branch, treat that as the normal "no PR for this branch" state. Report that no open PR exists for this branch and stop.
|
|
|
|
|
- If it errors for another reason (auth, network, repo config), report the error and stop.
|
|
|
|
|
|
|
|
|
|
### DU-3: Write and apply the updated description
|
|
|
|
|
|
|
|
|
|
Read the current PR description:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
gh pr view --json body --jq '.body'
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Follow the "Detect the base branch and remote" and "Gather the branch scope" sections of Step 6 to get the full branch diff. Use the PR found in DU-2 as the existing PR for base branch detection. Then write a new description following the writing principles in Step 6. If the user provided a focus, incorporate it into the description alongside the branch diff context.
|
|
|
|
|
|
|
|
|
|
Compare the new description against the current one and summarize the substantial changes for the user (e.g., "Added coverage of the new caching layer, updated test plan, removed outdated migration notes"). If the user provided a focus, confirm it was addressed. Ask the user to confirm before applying. Use the platform's blocking question tool (`AskUserQuestion` in Claude Code, `request_user_input` in Codex, `ask_user` in Gemini). If no question tool is available, present the summary and wait for the user's reply.
|
|
|
|
|
|
|
|
|
|
If confirmed, apply:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
gh pr edit --body "$(cat <<'EOF'
|
|
|
|
|
Updated description here
|
|
|
|
|
EOF
|
|
|
|
|
)"
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Report the PR URL.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Full workflow
|
|
|
|
|
|
|
|
|
|
### Step 1: Gather context
|
|
|
|
|
|
|
|
|
|
Run these commands. Use `command git` to bypass aliases and RTK proxies.
|
|
|
|
|
Run these commands.
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
command git status
|
|
|
|
|
command git diff HEAD
|
|
|
|
|
command git branch --show-current
|
|
|
|
|
command git log --oneline -10
|
|
|
|
|
command git rev-parse --abbrev-ref origin/HEAD
|
|
|
|
|
git status
|
|
|
|
|
git diff HEAD
|
|
|
|
|
git branch --show-current
|
|
|
|
|
git log --oneline -10
|
|
|
|
|
git rev-parse --abbrev-ref origin/HEAD
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The last command returns the remote default branch (e.g., `origin/main`). Strip the `origin/` prefix to get the branch name. If the command fails or returns a bare `HEAD`, try:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
command gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'
|
|
|
|
|
gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
If both fail, fall back to `main`.
|
|
|
|
|
|
|
|
|
|
If there are no changes, report that and stop.
|
|
|
|
|
Run `git branch --show-current`. If it returns an empty result, the repository is in detached HEAD state. Explain that a branch is required before committing and pushing. Ask whether to create a feature branch now. Use the platform's blocking question tool (`AskUserQuestion` in Claude Code, `request_user_input` in Codex, `ask_user` in Gemini). If no question tool is available, present the options and wait for the user's reply.
|
|
|
|
|
|
|
|
|
|
- If the user agrees, derive a descriptive branch name from the change content, create it with `git checkout -b <branch-name>`, then run `git branch --show-current` again and use that result as the current branch name for the rest of the workflow.
|
|
|
|
|
- If the user declines, stop.
|
|
|
|
|
|
|
|
|
|
If the `git status` result from this step shows a clean working tree (no staged, modified, or untracked files), check whether there are unpushed commits or a missing PR before stopping:
|
|
|
|
|
|
|
|
|
|
1. Run `git branch --show-current` to get the current branch name.
|
|
|
|
|
2. Run `git rev-parse --abbrev-ref --symbolic-full-name @{u}` to check whether an upstream is configured.
|
|
|
|
|
3. If the command succeeds, run `git log <upstream>..HEAD --oneline` using the upstream name from the previous command.
|
|
|
|
|
4. If an upstream is configured, check for an existing PR using the method in Step 3.
|
|
|
|
|
|
|
|
|
|
- If the current branch is `main`, `master`, or the resolved default branch from Step 1 and there is **no upstream** or there are **unpushed commits**, explain that pushing now would use the default branch directly. Ask whether to create a feature branch first. Use the platform's blocking question tool (`AskUserQuestion` in Claude Code, `request_user_input` in Codex, `ask_user` in Gemini). If no question tool is available, present the options and wait for the user's reply.
|
|
|
|
|
- If the user agrees, derive a descriptive branch name from the change content, create it with `git checkout -b <branch-name>`, then continue from Step 5 (push).
|
|
|
|
|
- If the user declines, report that this workflow cannot open a PR from the default branch directly and stop.
|
|
|
|
|
- If there is **no upstream**, treat the branch as needing its first push. Skip Step 4 (commit) and continue from Step 5 (push).
|
|
|
|
|
- If there are **unpushed commits**, skip Step 4 (commit) and continue from Step 5 (push).
|
|
|
|
|
- If all commits are pushed but **no open PR exists** and the current branch is `main`, `master`, or the resolved default branch from Step 1, report that there is no feature branch work to open as a PR and stop.
|
|
|
|
|
- If all commits are pushed but **no open PR exists**, skip Steps 4-5 and continue from Step 6 (write the PR description) and Step 7 (create the PR).
|
|
|
|
|
- If all commits are pushed **and an open PR exists**, report that and stop -- there is nothing to do.
|
|
|
|
|
|
|
|
|
|
### Step 2: Determine conventions
|
|
|
|
|
|
|
|
|
|
@@ -41,22 +124,24 @@ Follow this priority order for commit messages *and* PR titles:
|
|
|
|
|
|
|
|
|
|
### Step 3: Check for existing PR
|
|
|
|
|
|
|
|
|
|
Before committing, check whether a PR already exists for the current branch:
|
|
|
|
|
Run `git branch --show-current` to get the current branch name. If it returns an empty result here, report that the workflow is still in detached HEAD state and stop.
|
|
|
|
|
|
|
|
|
|
Then check for an existing open PR:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
command gh pr view --json url,title,state
|
|
|
|
|
gh pr view --json url,title,state
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Interpret the result:
|
|
|
|
|
Interpret the result. Do not treat every non-zero exit as a fatal error here:
|
|
|
|
|
|
|
|
|
|
- If it **returns PR data with `state: OPEN`**, note the URL and continue to Step 4 (commit) and Step 5 (push). Then skip to Step 7 (existing PR flow) instead of creating a new PR.
|
|
|
|
|
- If it **returns PR data with a non-OPEN state** (CLOSED, MERGED), treat this the same as "no PR exists" -- the previous PR is done and a new one is needed.
|
|
|
|
|
- If it **errors with "no pull requests found"**, no PR exists. Continue to Step 4 through Step 8 as normal.
|
|
|
|
|
- If it **errors for another reason** (auth, network, repo config), report the error to the user and stop.
|
|
|
|
|
- If it **returns PR data with `state: OPEN`**, an open PR exists for the current branch. Note the URL and continue to Step 4 (commit) and Step 5 (push). Then skip to Step 7 (existing PR flow) instead of creating a new PR.
|
|
|
|
|
- If it **returns PR data with a non-OPEN state** (CLOSED, MERGED), treat this the same as "no PR exists" -- the previous PR is done and a new one is needed. Continue to Step 4 through Step 8 as normal.
|
|
|
|
|
- If it **exits non-zero and the output indicates that no pull request exists for the current branch**, no PR exists. Continue to Step 4 through Step 8 as normal.
|
|
|
|
|
- If it **errors** (auth, network, repo config), report the error to the user and stop.
|
|
|
|
|
|
|
|
|
|
### Step 4: Branch, stage, and commit
|
|
|
|
|
|
|
|
|
|
1. If on `main`, `master`, or the resolved default branch from Step 1, create a descriptive feature branch first (`command git checkout -b <branch-name>`). Derive the branch name from the change content.
|
|
|
|
|
1. Run `git branch --show-current`. If it returns `main`, `master`, or the resolved default branch from Step 1, create a descriptive feature branch first with `git checkout -b <branch-name>`. Derive the branch name from the change content.
|
|
|
|
|
2. Before staging everything together, scan the changed files for naturally distinct concerns. If modified files clearly group into separate logical changes (e.g., a refactor in one set of files and a new feature in another), create separate commits for each group. Keep this lightweight -- group at the **file level only** (no `git add -p`), split only when obvious, and aim for two or three logical commits at most. If it's ambiguous, one commit is fine.
|
|
|
|
|
3. Stage relevant files by name. Avoid `git add -A` or `git add .` to prevent accidentally including sensitive files.
|
|
|
|
|
4. Commit following the conventions from Step 2. Use a heredoc for the message.
|
|
|
|
|
@@ -64,7 +149,7 @@ Interpret the result:
|
|
|
|
|
### Step 5: Push
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
command git push -u origin HEAD
|
|
|
|
|
git push -u origin HEAD
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Step 6: Write the PR description
|
|
|
|
|
@@ -79,26 +164,26 @@ Use this fallback chain. Stop at the first that succeeds:
|
|
|
|
|
|
|
|
|
|
1. **PR metadata** (if an existing PR was found in Step 3):
|
|
|
|
|
```bash
|
|
|
|
|
command gh pr view --json baseRefName,url
|
|
|
|
|
gh pr view --json baseRefName,url
|
|
|
|
|
```
|
|
|
|
|
Extract `baseRefName` as the base branch name. The PR URL contains the base repository (`https://github.com/<owner>/<repo>/pull/...`). Determine which local remote corresponds to that repository:
|
|
|
|
|
```bash
|
|
|
|
|
command git remote -v
|
|
|
|
|
git remote -v
|
|
|
|
|
```
|
|
|
|
|
Match the `owner/repo` from the PR URL against the fetch URLs. Use the matching remote as the base remote. If no remote matches, fall back to `origin`.
|
|
|
|
|
2. **`origin/HEAD` symbolic ref:**
|
|
|
|
|
```bash
|
|
|
|
|
command git symbolic-ref --quiet --short refs/remotes/origin/HEAD
|
|
|
|
|
git symbolic-ref --quiet --short refs/remotes/origin/HEAD
|
|
|
|
|
```
|
|
|
|
|
Strip the `origin/` prefix from the result. Use `origin` as the base remote.
|
|
|
|
|
3. **GitHub default branch metadata:**
|
|
|
|
|
```bash
|
|
|
|
|
command gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'
|
|
|
|
|
gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'
|
|
|
|
|
```
|
|
|
|
|
Use `origin` as the base remote.
|
|
|
|
|
4. **Common branch names** -- check `main`, `master`, `develop`, `trunk` in order. Use the first that exists on the remote:
|
|
|
|
|
```bash
|
|
|
|
|
command git rev-parse --verify origin/<candidate>
|
|
|
|
|
git rev-parse --verify origin/<candidate>
|
|
|
|
|
```
|
|
|
|
|
Use `origin` as the base remote.
|
|
|
|
|
|
|
|
|
|
@@ -110,23 +195,23 @@ Once the base branch and remote are known:
|
|
|
|
|
|
|
|
|
|
1. Verify the remote-tracking ref exists locally and fetch if needed:
|
|
|
|
|
```bash
|
|
|
|
|
command git rev-parse --verify <base-remote>/<base-branch>
|
|
|
|
|
git rev-parse --verify <base-remote>/<base-branch>
|
|
|
|
|
```
|
|
|
|
|
If this fails (ref missing or stale), fetch it:
|
|
|
|
|
```bash
|
|
|
|
|
command git fetch --no-tags <base-remote> <base-branch>
|
|
|
|
|
git fetch --no-tags <base-remote> <base-branch>
|
|
|
|
|
```
|
|
|
|
|
2. Find the merge base:
|
|
|
|
|
```bash
|
|
|
|
|
command git merge-base <base-remote>/<base-branch> HEAD
|
|
|
|
|
git merge-base <base-remote>/<base-branch> HEAD
|
|
|
|
|
```
|
|
|
|
|
2. List all commits unique to this branch:
|
|
|
|
|
```bash
|
|
|
|
|
command git log --oneline <merge-base>..HEAD
|
|
|
|
|
git log --oneline <merge-base>..HEAD
|
|
|
|
|
```
|
|
|
|
|
3. Get the full diff a reviewer will see:
|
|
|
|
|
```bash
|
|
|
|
|
command git diff <merge-base>...HEAD
|
|
|
|
|
git diff <merge-base>...HEAD
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Use the full branch diff and commit list as the basis for the PR description -- not the working-tree diff from Step 1.
|
|
|
|
|
@@ -157,6 +242,7 @@ Use this to select the right description depth:
|
|
|
|
|
- **Lead with value**: The first sentence should tell the reviewer *why this PR exists*, not *what files changed*. "Fixes timeout errors during batch exports" beats "Updated export_handler.py and config.yaml".
|
|
|
|
|
- **No orphaned opening paragraphs**: If the description uses `##` section headings anywhere, the opening summary must also be under a heading (e.g., `## Summary`). An untitled paragraph followed by titled sections looks like a missing heading. For short descriptions with no sections, a bare paragraph is fine.
|
|
|
|
|
- **Describe the net result, not the journey**: The PR description is about the end state -- what changed and why. Do not include work-product details like bugs found and fixed during development, intermediate failures, debugging steps, iteration history, or refactoring done along the way. Those are part of getting the work done, not part of the result. If a bug fix happened during development, the fix is already in the diff -- mentioning it in the description implies it's a separate concern the reviewer should evaluate, when really it's just part of the final implementation. Exception: include process details only when they are critical for a reviewer to understand a design choice (e.g., "tried approach X first but it caused Y, so went with Z instead").
|
|
|
|
|
- **When commits conflict, trust the final diff**: The commit list is supporting context, not the source of truth for the final PR description. If commit messages describe intermediate steps that were later revised or reverted (for example, "switch to gh pr list" followed by a later change back to `gh pr view`), describe the end state shown by the full branch diff. Do not narrate contradictory commit history as if all of it shipped.
|
|
|
|
|
- **Explain the non-obvious**: If the diff is self-explanatory, don't narrate it. Spend description space on things the diff *doesn't* show: why this approach, what was considered and rejected, what the reviewer should pay attention to.
|
|
|
|
|
- **Use structure when it earns its keep**: Headers, bullet lists, and tables are tools -- use them when they aid comprehension, not as mandatory template sections. An empty "## Breaking Changes" section adds noise.
|
|
|
|
|
- **Markdown tables for data**: When there are before/after comparisons, performance numbers, or option trade-offs, a table communicates density well. Example:
|
|
|
|
|
@@ -218,7 +304,7 @@ Fill in at PR creation time:
|
|
|
|
|
#### New PR (no existing PR from Step 3)
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
command gh pr create --title "the pr title" --body "$(cat <<'EOF'
|
|
|
|
|
gh pr create --title "the pr title" --body "$(cat <<'EOF'
|
|
|
|
|
PR description here
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
@@ -238,7 +324,7 @@ The new commits are already on the PR from the push in Step 5. Report the PR URL
|
|
|
|
|
- If **yes** -- write a new description following the same principles in Step 6 (size the full PR, not just the new commits), including the Compound Engineering badge unless one is already present in the existing description. Apply it:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
command gh pr edit --body "$(cat <<'EOF'
|
|
|
|
|
gh pr edit --body "$(cat <<'EOF'
|
|
|
|
|
Updated description here
|
|
|
|
|
EOF
|
|
|
|
|
)"
|
|
|
|
|
@@ -249,7 +335,3 @@ The new commits are already on the PR from the push in Step 5. Report the PR URL
|
|
|
|
|
### Step 8: Report
|
|
|
|
|
|
|
|
|
|
Output the PR URL so the user can navigate to it directly.
|
|
|
|
|
|
|
|
|
|
## Important: Use `command git` and `command gh`
|
|
|
|
|
|
|
|
|
|
Always invoke git as `command git` and gh as `command gh` in shell commands. This bypasses shell aliases and tools like RTK (Rust Token Killer) that proxy commands.
|
|
|
|
|
|
Trevin Chow