ado-commit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ADO Commit

ADO 提交

Create a conventional commit on an Azure DevOps-hosted repository: $ARGUMENTS

在Azure DevOps托管的仓库中创建约定式提交：$ARGUMENTS

Current state

当前状态

Git status: !
```
git status --porcelain
```
Current branch: !
```
git branch --show-current
```
Staged diff (stat): !
```
git diff --cached --stat
```
Unstaged diff (stat): !
```
git diff --stat
```
Recent commits: !
```
git log --oneline -5
```

Git状态：!
```
git status --porcelain
```
当前分支：!
```
git branch --show-current
```
暂存差异（统计）：!
```
git diff --cached --stat
```
未暂存差异（统计）：!
```
git diff --stat
```
最近提交：!
```
git log --oneline -5
```

Workflow

工作流程

The only ADO-specific bits are (a) work-item trailers and (b) the conventions this repo has adopted for talking to reviewers who open PRs in Azure DevOps.

Stage. If nothing is staged, stage all modified and new files with
```
git add -A
```
. If specific files are already staged, commit only those.
Diff. Run
```
git diff --cached
```
to understand the actual change. Read the diff — don't just trust the path names — because the message needs to describe what changed and why, not which files changed.
Split if needed. If the staged diff contains multiple unrelated logical changes, propose splitting into separate commits. One commit = one reason to change.
Write the message in Conventional Commits format (see below), then commit via
```
git commit --message "<subject>" [--trailer ...]
```
. Pass trailers with
```
--trailer
```
so git formats them correctly; don't cat-heredoc them into the body.
Don't skip pre-commit hooks. If
```
.pre-commit-config.yaml
```
exists, hooks run automatically and their failures are signal, not noise. Never pass
```
--no-verify
```
.

ADO专属的内容仅包括两点：(a) 工作项尾部信息；(b) 此仓库针对Azure DevOps中PR评审者采用的约定规范。

暂存：如果没有文件被暂存，使用
```
git add -A
```
暂存所有修改和新增文件。如果已有特定文件被暂存，则仅提交这些文件。
查看差异：运行
```
git diff --cached
```
了解实际变更内容。仔细阅读差异内容——不要只依赖文件名——因为提交信息需要描述变更内容及原因，而非哪些文件被变更。
按需拆分：如果暂存的差异包含多个不相关的逻辑变更，建议拆分为多个独立提交。一个提交对应一个变更理由。
编写提交信息：采用约定式提交（Conventional Commits）格式（见下文），然后通过
```
git commit --message "<subject>" [--trailer ...]
```
执行提交。使用
```
--trailer
```
参数传递尾部信息，确保Git正确格式化；不要通过 heredoc 将其写入提交正文。
不要跳过预提交钩子：如果存在
```
.pre-commit-config.yaml
```
文件，钩子会自动运行，其失败是有效信号而非干扰。切勿使用
```
--no-verify
```
参数跳过。

Conventional Commits — quick reference

约定式提交——快速参考

<type>(optional scope): <description>

<optional body>

<optional trailers>

Common types:

feat

fix

docs

style

refactor

perf

test

build

ci

chore

revert

. Append

after type/scope for breaking changes (e.g.

feat(api)!: change response format

). Keep the subject under 72 characters, imperative mood, no trailing period.

Examples:

feat(auth): add JWT refresh endpoint
fix(ui): resolve layout shift on mobile nav
refactor(db): migrate from raw SQL to query builder
chore(deps): bump TypeScript to 5.5
feat(api)!: change pagination response shape

<类型>(可选作用域): <描述>

<可选正文>

<可选尾部信息>

常见类型：

feat

（新功能）、

fix

（缺陷修复）、

docs

（文档更新）、

style

（格式调整，不影响代码逻辑）、

refactor

（代码重构）、

perf

（性能优化）、

test

（测试相关）、

build

（构建流程变更）、

ci

（持续集成配置变更）、

chore

（杂项任务，如依赖更新）、

revert

（回滚提交）。在类型/作用域后添加

表示破坏性变更（例如

feat(api)!: change response format

）。主题部分控制在72字符以内，使用祈使语气，末尾不加句号。

示例：

feat(auth): add JWT refresh endpoint
fix(ui): resolve layout shift on mobile nav
refactor(db): migrate from raw SQL to query builder
chore(deps): bump TypeScript to 5.5
feat(api)!: change pagination response shape

Work-item trailers (ADO-specific)

工作项尾部信息（ADO专属）

Azure DevOps auto-links commits to work items when the message contains

AB#<id>

. Include one whenever you can identify the target work item, because it keeps the board in sync without anyone clicking around.

Where to find the ID:

Branch name — patterns like
```
feature/1234-...
```
,
```
bug/AB1234-...
```
,
```
user/name/1234-...
```
usually encode the work item ID.
User input — if the user mentions "work item 1234" or "this closes 1234", use that.
Prior commits on the branch — run
```
git log --oneline origin/main..HEAD
```
and check if earlier commits reference an ID.
ADO MCP — if the project has the
```
azure-devops
```
MCP server configured and you're still unsure, call
```
wit_my_work_items
```
(or
```
search_workitem
```
with a keyword from the change) to surface likely candidates. Ask the user to confirm rather than guessing.

How to add it — as a trailer, not in the subject:

bash

git commit \
  --message "feat(auth): add JWT refresh endpoint" \
  --trailer "AB#1234" \
  --trailer "Assistant-model: Claude Code"

If you genuinely can't find a work-item ID, skip the trailer rather than inventing one. A missing trailer is recoverable; a wrong one pollutes the board.

Azure DevOps会在提交信息包含

AB#<id>

时自动将提交与工作项关联。只要能确定目标工作项ID，就应添加该信息，这样无需手动操作即可保持看板同步。

查找ID的途径：

分支名称——类似
```
feature/1234-...
```
、
```
bug/AB1234-...
```
、
```
user/name/1234-...
```
的分支命名模式通常包含工作项ID。
用户输入——如果用户提及“工作项1234”或“此提交关闭1234”，则使用该ID。
分支上的历史提交——运行
```
git log --oneline origin/main..HEAD
```
，检查早期提交是否引用了某个ID。
ADO MCP——如果项目配置了
```
azure-devops
```
MCP服务器且仍不确定ID，可调用
```
wit_my_work_items
```
（或使用变更中的关键字调用
```
search_workitem
```
）来查找可能的候选工作项。若无法确定，请询问用户确认，不要猜测。

添加方式——作为尾部信息，而非主题部分：

bash

git commit \
  --message "feat(auth): add JWT refresh endpoint" \
  --trailer "AB#1234" \
  --trailer "Assistant-model: Claude Code"

如果确实无法找到工作项ID，请跳过尾部信息，不要编造。缺失的尾部信息可后续补充，但错误的信息会污染看板数据。

AI authorship trailer

AI创作尾部信息

ADO code reviews often surface in audit contexts, so mark AI-assisted commits honestly. Use an

Assistant-model

trailer rather than

Co-authored-by

— most git tooling validates the latter as an email, and we want to distinguish assistance from authorship:

Assistant-model: Claude Code

Add it every time you commit on the user's behalf.

ADO代码评审常涉及审计场景，因此需如实标注AI辅助的提交。使用

Assistant-model

尾部信息而非

Co-authored-by

——大多数Git工具会验证后者是否为邮箱格式，且我们希望区分辅助创作与实际作者：

Assistant-model: Claude Code

每次代表用户执行提交时都需添加此信息。

Putting it together

整合示例

bash

git add -A
git diff --cached --stat          # sanity check
git commit \
  --message "fix(parser): handle nested escape sequences" \
  --trailer "AB#5678" \
  --trailer "Assistant-model: Claude Code"
git log -1                        # show the user the result

bash

git add -A
git diff --cached --stat          # 合理性检查
git commit \
  --message "fix(parser): handle nested escape sequences" \
  --trailer "AB#5678" \
  --trailer "Assistant-model: Claude Code"
git log -1                        # 向用户展示结果