git-automation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git Automation

Git自动化

Automate complex Git workflows with atomic commit enforcement, Beads integration, and real-time synchronization.

通过原子提交强制、Beads集成和实时同步来自动化复杂的Git工作流。

When to use this skill

何时使用该技能

Use this skill when:

Creating commits with proper message formatting
Managing feature branches and releases
Syncing Git state with task tracking systems
Implementing atomic commits across multiple files
Detecting and auto-committing completed work
Validating changes before committing

在以下场景使用该技能：

创建符合格式规范的提交信息
管理功能分支与版本发布
同步Git状态与任务追踪系统
在多文件间实现原子提交
检测并自动提交已完成的工作
提交前验证变更内容

Core Concepts

核心概念

Atomic Commits

原子提交

An atomic commit is a single, self-contained change that:

Fixes ONE issue or implements ONE feature
Can be reverted without breaking other changes
Passes all tests and validation
Has a clear, descriptive commit message

Benefits:

Easy to understand changes
Simpler debugging and rollbacks
Better code history
Easier to cherry-pick changes

Enforcement Rules:

Maximum ONE issue/task per commit
Strict validation before commit
Dependency checking
No bypassing atomic commit requirement

原子提交是单一、自包含的变更，需满足：

仅修复一个问题或实现一个功能
可回滚且不影响其他变更
通过所有测试与验证
拥有清晰、描述性的提交信息

优势：

变更内容易于理解
调试与回滚更简单
代码历史更清晰
更易挑选特定变更

强制规则：

每次提交最多关联一个问题/任务
提交前必须严格验证
依赖检查
不得绕过原子提交要求

Conventional Commits

约定式提交

Format:

{type}({scope}): {issue_id} {title}

Types:

```
feat
```
: New feature
```
fix
```
: Bug fix
```
refactor
```
: Code refactor
```
docs
```
: Documentation
```
test
```
: Test additions/updates
```
chore
```
: Build, dependencies, tooling

Examples:

feat(auth): TASK-42 Add JWT token validation
fix(api): ISSUE-123 Handle null responses correctly
docs(readme): Update installation instructions
test(utils): Add tests for date formatting

格式：

{type}({scope}): {issue_id} {title}

类型：

```
feat
```
: 新功能
```
fix
```
: 修复Bug
```
refactor
```
: 代码重构
```
docs
```
: 文档更新
```
test
```
: 测试用例新增/更新
```
chore
```
: 构建、依赖、工具相关变更

示例：

feat(auth): TASK-42 Add JWT token validation
fix(api): ISSUE-123 Handle null responses correctly
docs(readme): Update installation instructions
test(utils): Add tests for date formatting

Beads Integration

Beads集成

Real-time synchronization with Beads task tracking:

Sync Git commits with task status
Auto-update task status on commit
Track issue references in commits
Validate task completion before merge

与Beads任务追踪系统实时同步：

同步Git提交与任务状态
提交时自动更新任务状态
追踪提交中的问题引用
合并前验证任务完成情况

Step-by-Step Workflow

分步工作流

1. Create a Feature Branch

1. 创建功能分支

bash

undefined

bash

undefined

Create branch from main

git checkout main && git pull git checkout -b feat/TASK-42-description

Branch naming: {type}/{issue-id}-{short-description}

undefined

undefined

2. Make Changes

2. 进行变更

Edit files for a single feature/fix:

bash

undefined

编辑单个功能/修复相关的文件：

bash

undefined

Edit files

vim src/feature.ts

Stage changes

git add src/feature.ts

Check status

git status

undefined

git status

undefined

3. Validate Before Committing

3. 提交前验证

Ensure quality before commit:

bash

undefined

提交前确保质量：

bash

undefined

Run tests

npm test

Check linting

npm run lint

Type check

npm run type-check

Validate changes meet atomic commit rules

(Max files, single issue, proper formatting)

undefined

undefined

4. Create Atomic Commit

4. 创建原子提交

bash

undefined

bash

undefined

Commit with proper format

git commit -m "feat(module): TASK-42 Add new feature"

The commit will:

1. Validate message format

2. Check file count (< 50 files)

3. Verify single issue reference

4. Update Beads task status

5. Run pre-commit hooks

undefined

undefined

5. Sync with Beads (if using task tracking)

5. 与Beads同步（若使用任务追踪）

bash

undefined

bash

undefined

Auto-sync happens on commit, but manual sync available:

git beads-sync TASK-42

Updates: task status, linked commits, dependencies

undefined

undefined

6. Create Pull Request & Merge

6. 创建拉取请求并合并

bash

undefined

bash

undefined

Push to remote

git push -u origin feat/TASK-42-description

Create PR (on GitHub/GitLab)

Reference task: "Closes TASK-42"

Wait for reviews and CI

Merge when approved

git merge feat/TASK-42-description

undefined

git merge feat/TASK-42-description

undefined

Common Scenarios

常见场景

Scenario 1: Single File Bug Fix

场景1：单文件Bug修复

Task: BUGFIX-89 "Fix null pointer in auth service"

git checkout main && git pull
git checkout -b fix/BUGFIX-89-null-pointer
vim src/auth/service.ts
npm test  # Verify fix works
git add src/auth/service.ts
git commit -m "fix(auth): BUGFIX-89 Handle null user object"

Commit validates:

✅ Single file (< 50 limit)
✅ Proper message format
✅ Single issue reference
✅ Tests passing

Task: BUGFIX-89 "Fix null pointer in auth service"

git checkout main && git pull
git checkout -b fix/BUGFIX-89-null-pointer
vim src/auth/service.ts
npm test  # Verify fix works
git add src/auth/service.ts
git commit -m "fix(auth): BUGFIX-89 Handle null user object"

提交验证结果：

✅ 单个文件（低于50个文件限制）
✅ 提交信息格式合规
✅ 仅关联一个问题
✅ 测试通过

Scenario 2: Feature with Multiple Files

场景2：多文件功能开发

Task: FEAT-156 "Add user preferences UI"

git checkout -b feat/FEAT-156-user-prefs
vim src/components/Preferences.tsx
vim src/api/preferences.ts
vim src/styles/preferences.css
npm test
git add src/components/Preferences.tsx src/api/preferences.ts src/styles/preferences.css
git commit -m "feat(ui): FEAT-156 Add user preferences panel"

Commit validates:

✅ Multiple related files (same feature)
✅ All files for single feature
✅ Single issue reference
✅ Tests passing

Task: FEAT-156 "Add user preferences UI"

git checkout -b feat/FEAT-156-user-prefs
vim src/components/Preferences.tsx
vim src/api/preferences.ts
vim src/styles/preferences.css
npm test
git add src/components/Preferences.tsx src/api/preferences.ts src/styles/preferences.css
git commit -m "feat(ui): FEAT-156 Add user preferences panel"

提交验证结果：

✅ 多个相关文件（同属一个功能）
✅ 所有文件均服务于单一功能
✅ 仅关联一个问题
✅ 测试通过

Scenario 3: Refactor with Tests

场景3：带测试的代码重构

Task: TECH-203 "Refactor date utilities"

git checkout -b refactor/TECH-203-date-utils
vim src/utils/date.ts
vim src/utils/__tests__/date.test.ts
npm test  # Validate refactor doesn't break anything
git add src/utils/date.ts src/utils/__tests__/date.test.ts
git commit -m "refactor(utils): TECH-203 Simplify date formatting"

Commit validates:

✅ Logic and tests together
✅ No functionality change
✅ All tests pass
✅ Proper message format

Task: TECH-203 "Refactor date utilities"

git checkout -b refactor/TECH-203-date-utils
vim src/utils/date.ts
vim src/utils/__tests__/date.test.ts
npm test  # Validate refactor doesn't break anything
git add src/utils/date.ts src/utils/__tests__/date.test.ts
git commit -m "refactor(utils): TECH-203 Simplify date formatting"

提交验证结果：

✅ 逻辑代码与测试代码一同提交
✅ 未改变功能逻辑
✅ 所有测试通过
✅ 提交信息格式合规

Safety Features

安全特性

Pre-Commit Validation

提交前验证

Before every commit:

Syntax check: No syntax errors in code
Lint check: Code follows style rules
Type check: TypeScript types are valid
Secret scan: No credentials committed
Size check: No huge files
Atomic check: Single issue per commit

每次提交前会执行：

语法检查：代码无语法错误
代码风格检查：代码遵循风格规范
类型检查：TypeScript类型有效
敏感信息扫描：无凭据被提交
文件大小检查：无超大文件
原子性检查：每次提交仅关联一个问题

Auto-Commit Detection

自动提交检测

Automatically commit when:

Beads task marked as completed
Agent workflow finishes successfully
Manual trigger requested

Safety checks:

Dry-run mode by default
Requires confirmation for first auto-commit
Validates working tree is clean
Backs up before committing
Logs all auto-commits

在以下情况自动触发提交：

Beads任务标记为已完成
Agent工作流成功完成
手动触发请求

安全检查：

默认启用试运行模式
首次自动提交需确认
验证工作区是否干净
提交前自动备份
记录所有自动提交日志

Dependency Validation

依赖验证

Ensures commits don't break dependencies:

Check package.json changes
Verify lock file consistency
Validate version constraints
Test dependency installations

确保提交不会破坏依赖：

检查package.json变更
验证锁文件一致性
校验版本约束
测试依赖安装

Advanced Workflows

高级工作流

Watch Mode (Continuous Auto-commit)

监听模式（持续自动提交）

Watch for completed tasks every 30 seconds
Auto-commit when task status → closed
Validate each commit before pushing
Stop on errors or after 1 hour

Use for:

Long-running agent workflows
Multiple concurrent tasks
Automated CI/CD pipelines

每30秒检查已完成的任务
当任务状态变为已关闭时自动提交
推送前验证每个提交
出现错误或运行1小时后停止

适用场景：

长时间运行的Agent工作流
多并发任务
自动化CI/CD流水线

Beads Real-Time Sync

Beads实时同步

Keeps Git and task tracking in sync:

Commit detection → Update task status
Task completion → Suggest auto-commit
Branch creation → Link to task
Pull request merge → Mark as done

Sync on:

Commit (post-commit hook)
Branch creation/deletion
Tag creation
PR open/close/merge

保持Git与任务追踪系统同步：

检测提交 → 更新任务状态
任务完成 → 建议自动提交
分支创建 → 关联至任务
拉取请求合并 → 标记任务为已完成

同步触发时机：

提交（提交后钩子）
分支创建/删除
标签创建
拉取请求打开/关闭/合并

Version-Based Branching

基于版本的分支管理

Organize branches by release version:

main              → Production
v1.2.x            → Stable releases
develop           → Development
feat/...          → Features (merge to develop)
bugfix/...        → Bug fixes (merge to v-branch)
release/v1.2.0    → Release candidates

Tagging:

Automatic tags on releases
Version-based branch cleanup
Release note generation

按发布版本组织分支：

main              → Production
v1.2.x            → Stable releases
develop           → Development
feat/...          → Features (merge to develop)
bugfix/...        → Bug fixes (merge to v-branch)
release/v1.2.0    → Release candidates

标签管理：

发布时自动打标签
基于版本清理分支
自动生成发布说明

Troubleshooting

故障排除

Commit Validation Fails

提交验证失败

Problem: "Atomic commit validation failed"

Solution:

Check commit has only one issue reference:
```
git log -1
```
Verify file count < 50:
```
git diff --cached --name-only | wc -l
```
Check message format:
```
{type}({scope}): {issue} {title}
```
Run validation:
```
git validate --strict
```

问题： "Atomic commit validation failed"

解决方案：

检查提交仅关联一个问题：
```
git log -1
```
验证文件数量少于50：
```
git diff --cached --name-only | wc -l
```
检查提交信息格式：
```
{type}({scope}): {issue} {title}
```
运行验证：
```
git validate --strict
```

Beads Sync Not Working

Beads同步失败

Problem: "Beads sync failed"

Solution:

Check Beads is running:
```
beads status
```
Verify issue exists:
```
beads issues list TASK-42
```
Check credentials:
```
echo $BEADS_API_KEY
```
Retry manually:
```
git beads-sync TASK-42
```

问题： "Beads sync failed"

解决方案：

检查Beads是否运行：
```
beads status
```
验证问题存在：
```
beads issues list TASK-42
```
检查凭据：
```
echo $BEADS_API_KEY
```
手动重试：
```
git beads-sync TASK-42
```

Auto-commit Not Triggering

自动提交未触发

Problem: "Auto-commit didn't run"

Solution:

Check task actually completed:
```
beads issues get TASK-42
```
Verify changes exist:
```
git status
```
Run manually:
```
git auto-commit --dry-run=false
```
Check logs:
```
cat .git/auto-commit.log
```

问题： "Auto-commit didn't run"

解决方案：

检查任务是否确实完成：
```
beads issues get TASK-42
```
验证存在变更：
```
git status
```
手动运行：
```
git auto-commit --dry-run=false
```
查看日志：
```
cat .git/auto-commit.log
```

Best Practices

最佳实践

One Issue Per Commit: Never mix multiple issues in one commit
Clear Messages: Include issue ID and descriptive title
Test Before Commit: Always run tests before committing
Small Changes: Smaller atomic commits are easier to review
Linked Tasks: Always reference task/issue ID in commits
Clean History: Use atomic commits to keep history clean
Validate Always: Don't bypass validation checks
Backup Before Auto-commit: Enable backup before auto-commit

一提交一问题：切勿在一个提交中混合多个问题
清晰的提交信息：包含问题ID与描述性标题
提交前测试：提交前务必运行测试
小变更提交：更小的原子提交更易于评审
任务关联：提交中始终引用任务/问题ID
清晰的历史：使用原子提交保持代码历史清晰
始终验证：不得绕过验证检查
自动提交前备份：启用自动提交前的备份功能

Related Skills

Keywords

关键词

git, commits, automation, workflow, atomic-commits, beads, sync, branches, validation, conventional-commits