ship-it

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ship It

一键发布

Automate the full PR lifecycle: commit changes, create a PR, wait for CI/CD, and squash merge into main.

自动化PR全生命周期流程：提交更改、创建PR、等待CI/CD检查、完成后 squash 合并至main分支。

Workflow

工作流程

Follow each step sequentially. Stop and report to the user if any step fails.

按顺序执行以下步骤。若任何步骤失败，立即停止并向用户报告问题。

Step 1: Pre-flight Checks

步骤1：前置检查

Run these checks before anything else. If any fail, stop and tell the user why.

Branch check: Run
```
git branch --show-current
```
. If in detached HEAD state, stop — tell the user to check out a named branch.
Remote check: Run
```
git remote -v
```
. If no remote is configured, stop — tell the user to add a remote.
GitHub CLI check: Run
```
gh auth status
```
. If not authenticated, stop — tell the user to run
```
gh auth login
```
.

Save the current branch name for later use.

在执行任何操作前先运行以下检查。若任意检查失败，停止操作并告知用户原因。

分支检查：执行
```
git branch --show-current
```
。若处于分离HEAD状态，停止操作——告知用户需切换到命名分支。
远程仓库检查：执行
```
git remote -v
```
。若未配置远程仓库，停止操作——告知用户需添加远程仓库。
GitHub CLI检查：执行
```
gh auth status
```
。若未通过认证，停止操作——告知用户需执行
```
gh auth login
```
完成认证。

保存当前分支名称供后续使用。

Step 2: Handle Uncommitted Changes

步骤2：处理未提交更改

Run
```
git status --porcelain
```
to check for uncommitted changes (staged, unstaged, and untracked).
If the working tree is clean (no output) and not on
```
main
```
, skip to Step 3. If the working tree is clean and on
```
main
```
, stop — there is nothing to ship.
If there are changes, display the list of changed files and ask the user:
- A) Include all changes — stage everything shown
- B) Select individual files — present a numbered list and let the user pick which files to include (e.g., "1, 3, 5")
- C) Cancel — abort the entire workflow
Stage the selected files using
```
git add <file1> <file2> ...
```
with explicit file paths. Never use
git add -A
or
git add .
.

Run

git diff --cached --stat

and

git diff --cached

to understand the changes.

Generate a clear, descriptive commit message based on the diff.
Create the commit.

执行
```
git status --porcelain
```
检查未提交更改（已暂存、未暂存和未追踪文件）。
若工作区无更改（无输出）且当前分支不是
```
main
```
，直接跳至步骤3。若工作区无更改且当前分支是
```
main
```
，停止操作——没有可发布的内容。
若存在更改，展示已更改文件列表并询问用户：
- A) 包含所有更改 —— 暂存所有列出的文件
- B) 选择单个文件 —— 展示编号列表，让用户选择需要包含的文件（例如："1, 3, 5"）
- C) 取消 —— 终止整个工作流程
使用
```
git add <file1> <file2> ...
```
命令暂存用户选择的文件，禁止使用
git add -A
或
git add .
。

执行

git diff --cached --stat

和

git diff --cached

查看更改内容。

根据diff内容生成清晰、描述性的提交信息。
创建提交。

Step 2b: Create Feature Branch (if on main)

步骤2b：创建功能分支（若当前为main分支）

If the current branch is

main

, create a feature branch before proceeding:

Generate a descriptive branch name from the staged changes (e.g.,
```
feat/add-user-validation
```
,
```
fix/null-pointer-in-parser
```
). Use kebab-case with a conventional prefix (
```
feat/
```
,
```
fix/
```
,
```
chore/
```
,
```
refactor/
```
, etc.).
Run
```
git checkout -b <branch-name>
```
to create and switch to the new branch. The commit made in Step 2 comes along automatically.
Save this branch name for cleanup in Step 6.

若当前分支是

main

，需先创建功能分支再继续：

根据暂存的更改生成描述性分支名称（例如：
```
feat/add-user-validation
```
、
```
fix/null-pointer-in-parser
```
）。使用短横线分隔格式（kebab-case），并添加规范前缀（
```
feat/
```
、
```
fix/
```
、
```
chore/
```
、
```
refactor/
```
等）。
执行
```
git checkout -b <branch-name>
```
创建并切换到新分支。步骤2中创建的提交会自动同步到新分支。
保存该分支名称，供步骤6清理使用。

Step 3: Push and Create PR

步骤3：推送分支并创建PR

Run
```
git push -u origin HEAD
```
to push the branch to the remote.
Check if a PR already exists:
```
gh pr view --json number,url 2>/dev/null
```
.
- If a PR exists, display its URL and skip to Step 4.
If no PR exists:
- Review the commits with
```
git log main..HEAD --oneline
```
  .
- Generate a concise PR title (under 70 characters) and a body summarizing the changes.
- Create the PR:
```
gh pr create --base main --title "<title>" --body "<body>"
```
  .
Display the PR URL to the user.

执行
```
git push -u origin HEAD
```
将分支推送到远程仓库。
检查是否已存在PR：
```
gh pr view --json number,url 2>/dev/null
```
。
- 若PR已存在，展示其URL并跳至步骤4。
若PR不存在：
- 执行
```
git log main..HEAD --oneline
```
  查看提交记录。
- 生成简洁的PR标题（不超过70字符）和总结更改内容的PR正文。
- 创建PR：
```
gh pr create --base main --title "<title>" --body "<body>"
```
  。
向用户展示PR的URL。

Step 4: Poll CI/CD Checks

步骤4：轮询CI/CD检查状态

Wait 10 seconds before the first check to give CI time to start.
Run
```
gh pr checks
```
to get check status.
Parse the results:
- All checks pass → proceed to Step 5.
- Any check fails → stop and report the failure to the user. Include the check name, status, and link. Do not proceed.
- Checks still pending → wait 30 seconds, then poll again.
- No checks configured (empty output) → ask the user whether to proceed with merge anyway or stop.
If checks are still pending after 15 minutes of polling, stop and tell the user. Provide the PR URL so they can monitor manually.

首次检查前等待10秒，给CI启动留出时间。
执行
```
gh pr checks
```
获取检查状态。
解析检查结果：
- 所有检查通过 → 继续执行步骤5。
- 任意检查失败 → 停止操作并向用户报告失败信息，包括检查名称、状态和链接。不再继续执行后续步骤。
- 检查仍在进行中 → 等待30秒后再次轮询。
- 未配置检查（输出为空）→ 询问用户是否继续合并或停止操作。
若轮询15分钟后检查仍在进行中，停止操作并告知用户。提供PR URL供用户手动监控。

Step 5: Squash Merge

步骤5：Squash合并

Run
```
gh pr merge --squash --delete-branch
```
to squash merge and delete the remote branch.
If the merge fails (merge conflicts, branch protection rules, etc.), report the specific error to the user and stop.

执行
```
gh pr merge --squash --delete-branch
```
执行squash合并并删除远程分支。
若合并失败（如存在合并冲突、分支保护规则限制等），向用户报告具体错误并停止操作。

Step 6: Clean Up

步骤6：清理操作

Run
```
git checkout main
```
.
Run
```
git pull origin main
```
to get the merged changes.
Delete the local feature branch:
```
git branch -d <branch-name>
```
(using the branch name saved in Step 1).
Report success with a summary:
- PR URL
- Merge status
- Branches cleaned up

执行
```
git checkout main
```
切换到main分支。
执行
```
git pull origin main
```
获取合并后的最新代码。
删除本地功能分支：
```
git branch -d <branch-name>
```
（使用步骤1中保存的分支名称）。
向用户报告成功信息，包括：
- PR URL
- 合并状态
- 已清理的分支信息

Edge Cases

异常场景处理

On main with changes: Create a feature branch automatically (Step 2b) after committing.
On main with no changes: Stop — nothing to ship.
Detached HEAD: Stop immediately with a message to check out a named branch.
PR already exists: Use the existing PR. Skip PR creation, proceed to CI polling.
No CI checks configured: Ask the user whether to merge without checks.
CI timeout (15 min): Report PR URL for manual monitoring. Do not merge.
Merge conflicts: Report the error. Do not attempt to resolve automatically.
Branch protection rules block merge: Report the specific error from
```
gh
```
.
User cancels during file selection: Abort the entire workflow gracefully.

当前为main分支且存在更改：提交后自动创建功能分支（步骤2b）。
当前为main分支且无更改：停止操作——没有可发布的内容。
分离HEAD状态：立即停止操作，告知用户需切换到命名分支。
PR已存在：使用现有PR，跳过PR创建步骤，直接进入CI状态轮询。
未配置CI检查：询问用户是否跳过检查直接合并。
CI检查超时（15分钟）：提供PR URL供用户手动监控，不执行合并操作。
合并冲突：报告错误信息，不自动尝试解决冲突。
分支保护规则阻止合并：报告
```
gh
```
工具返回的具体错误信息。
用户在文件选择阶段取消：优雅终止整个工作流程。