Applicable scenarios
- The user explicitly requests to execute
git commit - The user explicitly requests to execute
git push - The user requests to commit the current local changes and sync them to the remote branch
- Need to first generate a short commit message based on the current diff for the user to confirm
Inapplicable scenarios
- Only writing a commit message, without needing to actually commit or push
- Need to create a GitHub Issue, PR, reply to comments, or check remote collaboration status
- Need to rewrite Git history, such as
rebase、reset、commit --amend、push --force - Currently still on
masterand preparing to start development; in this case, first go throughgithub-worktree
Quick guidance
- First check the branch and working tree status, then decide whether a commit can be made:
git branch --show-currentgit status --shortgit diff/git diff --cached
- Before push, first identify the remote role; do not assume
originis necessarily a fork:git remote -vgit remote get-url --push <remote>- Distinguish which remote is the personal fork and which remote is the upstream main repository
- When currently on
master、main、release-*and other shared branches, do not push directly by default; first remind the user to switch togithub-worktreeor explicitly confirm the risk. - Before commit, first organize the commit boundaries: only commit files directly related to this requirement; when encountering unrelated changes, sensitive files, or suspicious generated artifacts, stop first and confirm with the user.
- First generate one based on the current changesshort preview text, with the default format:
{issue标题或规范化subject} {本次变更一句话摘要}- The summary should only state what was actually added/modified this time, kept within one sentence, and not expanded into a long body
- If the branch can resolve an issue number and the issue title is known, the issue title can be directly reused as the first half; for the second half, add a simple explanation based on the current diff.
- Example:
- issue title:
feat: 新增 GitHub worktree 实践相关 Skill #13062 - Current changes: added
worker-skillfile - Preview display:
feat: 新增 GitHub worktree 实践相关 Skill #13062 新增了 worker-skill 文件。
- issue title:
- Special case: If the user explicitly specifies an issue and explicitly says "push directly", treat this as a one-time authorization for
commit + push:- Directly use current issue title + issue number as the complete commit message
- If the issue title itselfalready contains
#issue号, then use it directly as is - If the issue title itselfdoes not contain
#issue号, then automatically normalize it to:<issue标题> #<issue号> - For example: the current issue title is
feat: 新增 GitHub worktree 实践相关 Skill, and the issue number is13062, then the commit content must be:feat: 新增 GitHub worktree 实践相关 Skill #13062 - Do notappend the supplementary summary of the current diff
- Do notrewrite the wording, add a period, add a body, add a scope, or append any other message besides
#issue号any other message outside - Do notshow the preview to the user again or perform a second confirmation
- After completing the necessary safety checks, directly execute
git commitandgit push
- Under the default path, first show the generated preview content to the user, and after the user explicitly replies with confirmations such as “no problem”, “can submit”, or “push directly”, then execute
git commitandgit push。 - the commit message format, type selection, and Issue number concatenation rules, reuse
git-commit-specification.; this skill only adds the workflow layer of “generate a one-line summary based on the current diff and confirm it first,” as well as the shortcut special case of “specify issue + push directly.” - After a successful commit, then determine the push strategy,the default target is the fork remote:
- the current branch already tracks the fork remote: prefer
git push - no upstream has been established yet: prefer
git push -u <fork-remote> HEAD - If the current tracking points to the main repository remote, do not directly reuse it; first change it to the fork remote or confirm with the user first
- Remote is ahead, diverged, or rejected: stop the default push, first explain to the user and confirm the subsequent synchronization strategy
- After the push is complete, report the actual result to the user: the current branch, the fork remote pushed to, whether upstream has been established, and whether the PR process still needs to be followed.
High-signal rules
commitandpushare both write operations with side effects; do not execute them on your own without the user's explicit authorization- Do not stuff unrelated changes that the user did not ask to commit into this commit
- The preview text shown to the user must be based onthe current actual diff, do not just copy the issue title
- Only when the user explicitly specifies an issue and explicitly says “push directly” is it allowed to skip the second confirmation and directly use the issue title as the complete commit message
- When taking the “direct push” shortcut path, the commit content must include the current
#issue号; if the title lacks an issue number, only adding#issue号 - In the BK-CI repository, if the final segment of the branch name is purely numeric, it usually corresponds to a GitHub Issue number; it can be used for message alignment, but do not invent an issue
- By default, push goes to the personal fork, not to the upstream main repository by default; push to the main repository remote only when the user explicitly requests it
- Push is only responsible for synchronizing the local branch to the remote; it is not equivalent to creating a PR, merging a branch, or closing an Issue
- If files are modified by a hook, the push is rejected, or the remote is already ahead, report the current Git status truthfully; do not secretly rewrite history
- When the user has not explicitly requested it, do not execute
push --force, do not push shared main branches, and do not misuse--no-verify
Key pitfalls
- Commit directly after only looking at the file name, without looking at the diff first
- The generated preview text does not reflect “what was actually changed this time,” and the user still does not know what is being committed after reading it
- The user did not explicitly specify an issue, but the shortcut path of “directly use the issue title to commit and skip confirmation” was mistakenly taken
- The “direct push” shortcut path was triggered, but
#issue号was missed, or in addition to adding#issue号, a summary was also appended - Commit unrelated changes, formatting noise, or sensitive files along the way
- Without first identifying the fork remote, the branch was pushed directly to the main repository remote
- The current branch has no upstream but still uses the normal
git push, causing a misjudgment after failure - After a push fails, directly suggest a force push, skipping investigation of the reason for the remote divergence
- Mistaking “commit and push” for “also create a PR and handle GitHub comments along the way”
Further reading
- Commit message and issue rules:
git-commit-specification - From
masterCreate an issue branch and worktree:github-worktree - PR / Issue / review comment workflow:
github-repository-management