ship-it

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ship: Branch, Commit, Push & PR

交付操作：创建分支、提交、推送与发起Pull Request

Arguments

参数

Optional text to derive branch name, commit message, or PR title (e.g.

fix login timeout

可选文本，用于生成分支名称、提交信息或PR标题（例如

fix login timeout

）。

Process

流程

1. Preflight Checks

1. 预检检查

bash

git status
git branch --show-current
DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')

bash

git status
git branch --show-current
DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')

Fallback if origin/HEAD is unset

if [ -z "$DEFAULT_BRANCH" ]; then DEFAULT_BRANCH=$(git remote show origin 2>/dev/null | grep 'HEAD branch' | sed 's/.*: //') fi git diff --stat git diff --stat --cached gh auth status


Determine:
- What is the default branch? (detect from remote ref, do not assume `main`)
- Are there changes to commit? (If no staged or unstaged changes, abort with message)
- Are we on the default branch? (If so, need to create a branch)
- Are we already on a feature branch?
- Is `gh` CLI installed and authenticated? (If not, abort: "Install and authenticate the GitHub CLI: https://cli.github.com")
- Are we in detached HEAD state? (If so, create a branch before proceeding)

if [ -z "$DEFAULT_BRANCH" ]; then DEFAULT_BRANCH=$(git remote show origin 2>/dev/null | grep 'HEAD branch' | sed 's/.*: //') fi git diff --stat git diff --stat --cached gh auth status


确认以下信息：
- 默认分支是什么？（从远程引用中检测，不要默认是`main`）
- 是否有需要提交的变更？（如果没有暂存或未暂存的变更，终止操作并提示信息）
- 当前是否在默认分支上？（如果是，需要创建新分支）
- 当前是否已经在功能分支上？
- `gh` CLI是否已安装并完成认证？（如果没有，终止操作："请安装并认证GitHub CLI：https://cli.github.com"）
- 是否处于分离HEAD状态？（如果是，先创建分支再继续）

2. Create Branch (if needed)

2. 创建分支（如有需要）

Skip this step if already on a feature branch — use the current branch.

If on the default branch or in detached HEAD, create and switch to a new branch:

bash

git checkout -b <branch-name>

Branch naming:

If user provided
```
$ARGUMENTS
```
, derive branch name from it (kebab-case, e.g.
```
fix/handle-null-response
```
)
Otherwise, analyze the changes and generate a descriptive branch name
Use prefixes:
```
feat/
```
,
```
fix/
```
,
```
refactor/
```
,
```
docs/
```
,
```
chore/
```
,
```
test/
```
based on change type
If a remote branch with the same name already exists, append a short suffix (e.g.
```
-2
```
)

如果已经在功能分支上，则跳过此步骤——使用当前分支即可。

如果当前在默认分支或处于分离HEAD状态，创建并切换到新分支：

bash

git checkout -b <branch-name>

分支命名规则：

如果用户提供了
```
$ARGUMENTS
```
，从中派生分支名称（使用短横线分隔的小写格式，例如
```
fix/handle-null-response
```
）
否则，分析变更内容生成描述性分支名称
根据变更类型使用前缀：
```
feat/
```
（功能）、
```
fix/
```
（修复）、
```
refactor/
```
（重构）、
```
docs/
```
（文档）、
```
chore/
```
（杂项）、
```
test/
```
（测试）
如果远程仓库中已存在同名分支，添加简短后缀（例如
```
-2
```
）

3. Stage & Commit

3. 暂存与提交

Stage specific files rather than using

git add -A

bash

git add <file1> <file2> ...
git diff --cached --name-only

Analyze the diff and generate a conventional commit message. If user provided

$ARGUMENTS

that looks like a commit message, use it directly.

bash

git commit -m "type: description"

Commit fallbacks:

If commit fails due to GPG signing errors (sandbox or keyring issues), retry with
```
--no-gpg-sign
```
If heredoc syntax (
```
$(cat <<'EOF'...)
```
) fails with "can't create temp file", use multiple
```
-m
```
flags instead (e.g.
```
git commit -m "subject" -m "body"
```
)

暂存指定文件，而非使用

git add -A

。

bash

git add <file1> <file2> ...
git diff --cached --name-only

分析差异内容并生成符合规范的提交信息。如果用户提供的

$ARGUMENTS

看起来像提交信息，则直接使用。

bash

git commit -m "type: description"

提交失败的 fallback 方案：

如果因GPG签名错误导致提交失败（沙箱或密钥环问题），使用
```
--no-gpg-sign
```
参数重试
如果here文档语法（
```
$(cat <<'EOF'...)
```
）因"无法创建临时文件"失败，改用多个
```
-m
```
参数替代（例如
```
git commit -m "subject" -m "body"
```
）

4. Push

4. 推送代码

bash

git push -u origin <branch-name>

If push fails due to branch protection or permissions, report the error to the user and stop.

bash

git push -u origin <branch-name>

如果因分支保护或权限问题导致推送失败，向用户报告错误并终止操作。

5. Create Pull Request

5. 发起Pull Request

Gather context for the PR description:

bash

git log <default-branch>..HEAD --oneline
git diff <default-branch>..HEAD --stat

Check for an existing PR on this branch:

bash

if gh pr view --json url,title,body > /dev/null 2>&1; then
  gh pr view --json url,title,body
fi

If a PR already exists:

Compare the current PR title and body against all commits on the branch (
```
git log <default-branch>..HEAD --oneline
```
)
If the title or body no longer reflects the full set of changes (e.g. new commits were added), update them with
```
gh pr edit <number> --title "<new title>" --body "<new body>"
```
Report the PR URL and any updates made, then jump to Step 6

Otherwise, create the PR:

bash

gh pr create --title "<title>" --body "$(cat <<'EOF'

收集PR描述的上下文信息：

bash

git log <default-branch>..HEAD --oneline
git diff <default-branch>..HEAD --stat

检查当前分支是否已有PR：

bash

if gh pr view --json url,title,body > /dev/null 2>&1; then
  gh pr view --json url,title,body
fi

如果PR已存在：

将当前PR的标题和正文与分支上的所有提交（
```
git log <default-branch>..HEAD --oneline
```
）进行对比
如果标题或正文不再反映所有变更内容（例如添加了新的提交），使用
```
gh pr edit <number> --title "<new title>" --body "<new body>"
```
更新
报告PR链接及所有更新内容，然后跳至第6步

否则，创建PR：

bash

gh pr create --title "<title>" --body "$(cat <<'EOF'

Summary

摘要

[2-3 bullet points describing the changes]

[2-3个描述变更的要点]

Test Plan

测试方案

[How to test these changes]

Generated with [agent name and link, per agent conventions] EOF )"


If `gh pr create` fails, report the error to the user (common causes: missing repo permissions, network issues, branch protection rules).

**Title:** If user provided `$ARGUMENTS`, use as PR title. Otherwise generate from the commit(s).

[如何测试这些变更]

由[Agent名称及链接，遵循Agent约定]生成 EOF )"


如果`gh pr create`执行失败，向用户报告错误（常见原因：缺少仓库权限、网络问题、分支保护规则）。

**标题规则：**如果用户提供了`$ARGUMENTS`，则将其用作PR标题。否则从提交信息中生成。

6. Report

6. 结果报告

Output:

Branch name
Commit hash and message
PR URL

输出以下信息：

分支名称
提交哈希值及提交信息
PR链接

Rules

规则

Never commit files that look like secrets (.env, credentials, keys, tokens, private keys, build artifacts)
If there are merge conflicts with the default branch, warn the user before creating the PR

绝对不要提交看起来像敏感信息的文件（.env、凭证、密钥、令牌、私钥、构建产物）
如果与默认分支存在合并冲突，在创建PR前先向用户发出警告