Back to Details

push

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Push

推送

Prerequisites

前置条件

  • gh
    CLI is installed and available in 
    PATH
    .
  • gh auth status
    succeeds for GitHub operations in this repo.
  • gh
    CLI 已安装且已添加到 
    PATH
    中。
  • 执行 
    gh auth status
    验证通过，可在当前仓库执行GitHub相关操作。

Goals

目标

  • Push current branch changes to 
    origin
    safely.
  • Create a PR if none exists for the branch, otherwise update the existing PR.
  • Keep branch history clean when remote has moved.
  • 安全地将当前分支改动推送到 
    origin
    。
  • 如果当前分支没有对应的PR则新建，否则更新已有PR。
  • 当远端分支有更新时，保持分支历史整洁。

Related Skills

相关技能

  • pull
    : use this when push is rejected or sync is not clean (non-fast-forward, merge conflict risk, or stale branch).
  • pull
    ：当推送被拒绝或同步异常时使用（非快进合并、存在合并冲突风险、分支过期等场景）。

Steps

操作步骤

  1. Identify current branch and confirm remote state.
  2. Run local validation (
    make -C elixir all
    ) before pushing.
  3. Push branch to 
    origin
    with upstream tracking if needed, using whatever remote URL is already configured.
  4. If push is not clean/rejected:
    • If the failure is a non-fast-forward or sync problem, run the 
      pull
      skill to merge 
      origin/main
      , resolve conflicts, and rerun validation.
    • Push again; use 
      --force-with-lease
      only when history was rewritten.
    • If the failure is due to auth, permissions, or workflow restrictions on the configured remote, stop and surface the exact error instead of rewriting remotes or switching protocols as a workaround.
  5. Ensure a PR exists for the branch:
    • If no PR exists, create one.
    • If a PR exists and is open, update it.
    • If branch is tied to a closed/merged PR, create a new branch + PR.
    • Write a proper PR title that clearly describes the change outcome
    • For branch updates, explicitly reconsider whether current PR title still matches the latest scope; update it if it no longer does.
  6. Write/update PR body explicitly using 
    .github/pull_request_template.md
    :
    • Fill every section with concrete content for this change.
    • Replace all placeholder comments (
      <!-- ... -->
      ).
    • Keep bullets/checkboxes where template expects them.
    • If PR already exists, refresh body content so it reflects the total PR scope (all intended work on the branch), not just the newest commits, including newly added work, removed work, or changed approach.
    • Do not reuse stale description text from earlier iterations.
  7. Validate PR body with 
    mix pr_body.check
    and fix all reported issues.
  8. Reply with the PR URL from 
    gh pr view
    .
  1. 识别当前分支，确认远端状态。
  2. 推送前执行本地校验（
    make -C elixir all
    ）。
  3. 按需设置上游跟踪，将分支推送到
    origin
    ，使用已配置的远端URL即可。
  4. 如果推送失败/被拒绝：
    • 如果是因为非快进或同步问题导致失败，运行
      pull
      技能合并
      origin/main
      ，解决冲突后重新执行校验。
    • 再次推送；仅当本地重写了提交历史时才使用
      --force-with-lease
      参数。
    • 如果失败原因是认证、权限或配置的远端工作流限制，直接终止并输出明确错误，不要通过重设远端或切换协议的方式绕过。
  5. 确保当前分支存在对应PR：
    • 没有PR则新建。
    • 已有打开的PR则更新。
    • 如果分支关联的PR已关闭/合并，则新建分支+PR。
    • 编写清晰描述改动效果的PR标题
    • 分支有更新时，需主动检查当前PR标题是否还匹配最新的改动范围，不匹配则更新。
  6. 严格按照
    .github/pull_request_template.md
    编写/更新PR正文：
    • 每个模块都填写本次改动的具体内容。
    • 替换所有占位注释（
      <!-- ... -->
      ）。
    • 保留模板要求的列表/复选框结构。
    • 如果PR已存在，更新正文内容使其反映PR的完整范围（该分支上所有计划的工作），而不仅仅是最新提交，包括新增工作、移除的工作或变更的实现方案。
    • 不要复用之前迭代的过时描述文本。
  7. 用
    mix pr_body.check
    校验PR正文，修复所有上报的问题。
  8. 返回
    gh pr view
    输出的PR URL。

Commands

命令示例

sh
undefined
sh
undefined

Identify branch

Identify branch

branch=$(git branch --show-current)
branch=$(git branch --show-current)

Minimal validation gate

Minimal validation gate

make -C elixir all
make -C elixir all

Initial push: respect the current origin remote.

Initial push: respect the current origin remote.

git push -u origin HEAD
git push -u origin HEAD

If that failed because the remote moved, use the pull skill. After

If that failed because the remote moved, use the pull skill. After

pull-skill resolution and re-validation, retry the normal push:

pull-skill resolution and re-validation, retry the normal push:

git push -u origin HEAD
git push -u origin HEAD

If the configured remote rejects the push for auth, permissions, or workflow

If the configured remote rejects the push for auth, permissions, or workflow

restrictions, stop and surface the exact error.

restrictions, stop and surface the exact error.

Only if history was rewritten locally:

Only if history was rewritten locally:

git push --force-with-lease origin HEAD
git push --force-with-lease origin HEAD

Ensure a PR exists (create only if missing)

Ensure a PR exists (create only if missing)

pr_state=$(gh pr view --json state -q .state 2>/dev/null || true) if [ "$pr_state" = "MERGED" ] || [ "$pr_state" = "CLOSED" ]; then echo "Current branch is tied to a closed PR; create a new branch + PR." >&2 exit 1 fi
pr_state=$(gh pr view --json state -q .state 2>/dev/null || true) if [ "$pr_state" = "MERGED" ] || [ "$pr_state" = "CLOSED" ]; then echo "Current branch is tied to a closed PR; create a new branch + PR." >&2 exit 1 fi

Write a clear, human-friendly title that summarizes the shipped change.

Write a clear, human-friendly title that summarizes the shipped change.

pr_title="<clear PR title written for this change>" if [ -z "$pr_state" ]; then gh pr create --title "$pr_title" else

Reconsider title on every branch update; edit if scope shifted.

gh pr edit --title "$pr_title" fi
pr_title="<clear PR title written for this change>" if [ -z "$pr_state" ]; then gh pr create --title "$pr_title" else

Reconsider title on every branch update; edit if scope shifted.

gh pr edit --title "$pr_title" fi

Write/edit PR body to match .github/pull_request_template.md before validation.

Write/edit PR body to match .github/pull_request_template.md before validation.

Example workflow:

Example workflow:

1) open the template and draft body content for this PR

1) open the template and draft body content for this PR

2) gh pr edit --body-file /tmp/pr_body.md

2) gh pr edit --body-file /tmp/pr_body.md

3) for branch updates, re-check that title/body still match current diff

3) for branch updates, re-check that title/body still match current diff

tmp_pr_body=$(mktemp) gh pr view --json body -q .body > "$tmp_pr_body" (cd elixir && mix pr_body.check --file "$tmp_pr_body") rm -f "$tmp_pr_body"
tmp_pr_body=$(mktemp) gh pr view --json body -q .body > "$tmp_pr_body" (cd elixir && mix pr_body.check --file "$tmp_pr_body") rm -f "$tmp_pr_body"

Show PR URL for the reply

Show PR URL for the reply

gh pr view --json url -q .url
undefined
gh pr view --json url -q .url
undefined

Notes

注意事项

  • Do not use 
    --force
    ; only use 
    --force-with-lease
    as the last resort.
  • Distinguish sync problems from remote auth/permission problems:
    • Use the 
      pull
      skill for non-fast-forward or stale-branch issues.
    • Surface auth, permissions, or workflow restrictions directly instead of changing remotes or protocols.
  • 不要使用
    --force
    参数；仅作为最后手段使用
    --force-with-lease
    。
  • 区分同步问题和远端认证/权限问题：
    • 非快进或分支过期问题使用
      pull
      技能处理。
    • 直接上报认证、权限或工作流限制问题，不要修改远端配置或切换协议。