# git-plugin

**Repository Path**: jerrycode-ai/git-plugin

## Basic Information

- **Project Name**: git-plugin
- **Description**: claude code 操作git插件
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-03
- **Last Updated**: 2026-06-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Git 工作流自动化插件

kscc 的 Git 工作流自动化插件 — 通过冒号语法快速执行常见 git 操作，内置安全协议。

## 功能特性

- **25+ 快捷命令** — 一条冒号前缀命令替代多步 git 操作
- **内置安全协议** — 破坏性操作始终需要用户明确确认
- **冲突解决助手** — 逐文件引导式合并冲突解决，支持批量操作
- **恢复工具集** — 通过 reflog 恢复已删除的分支、丢失的暂存和误操作的 reset
- **历史改写** — 从 git 历史中移除大文件或敏感数据，并提示团队协调
- **规范约束** — 分支命名（英文，见名知义：`type/YYYYMMDD-description`）与约定式提交消息（中文主题/正文）

## 安装

### 前置条件

- 已安装 kscc (Claude Code CLI)
- 本机已安装 git

### 方式一：通过 Marketplace 安装（推荐）

1. 将本仓库克隆到本地：

```bash
git clone <repo-url> /path/to/plugins/git
```

2. 在 kscc 中添加本地 Marketplace：

```
/plugin marketplace add /path/to/plugins/git
```

3. 安装插件：

```
/plugin install git@my-dev
```

> `my-dev` 为 `marketplace.json` 中定义的 marketplace 名称，可根据实际配置调整。

4. 重启 kscc 使插件生效。

### 方式二：手动安装

将插件目录复制到 kscc 插件目录：

```bash
# Linux / macOS
cp -r git/ ~/.claude/plugins/git/

# Windows (PowerShell)
Copy-Item -Recurse git/ "$env:USERPROFILE\.claude\plugins\git\"
```

### 验证安装

```
/plugin
```

输出中应能看到 `git` 插件及其状态。安装成功后，命令可通过以下方式调用：

- 全限定格式：`/git:undo-commit`
- 插件激活时缩写：`:undo-commit`

## 卸载

```
/plugin uninstall git@my-dev
```

或手动删除插件目录：

```bash
# Linux / macOS
rm -rf ~/.claude/plugins/git/

# Windows (PowerShell)
Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\plugins\git\"
```

卸载后重启 kscc 即可完全移除。

## 常见安装问题

| 问题 | 解决方案 |
|------|---------|
| 安装后命令不生效 | 重启 kscc，或运行 `/reload-plugins` |
| `/plugin` 中看不到插件 | 检查 `plugin.json` 是否在 `.claude-plugin/` 目录下，且 JSON 格式正确 |
| Marketplace 添加失败 | 确认路径为绝对路径，且目录下存在 `.claude-plugin/marketplace.json` |
| 命令触发但无响应 | 运行 `/plugin info git@my-dev` 查看插件详情和错误信息 |

## 命令参考

### 撤销类

| 命令 | 说明 |
|------|------|
| `:undo-commit` | 撤销上次提交，保留变更在暂存区（`git reset --soft`） |
| `:undo-commit-hard` | 撤销上次提交，**丢弃所有变更** — 破坏性操作，需确认 |
| `:undo-push` | 安全撤销已推送的提交（通过 `git revert`） |
| `:undo-reset` | 通过 reflog 恢复误执行的 `git reset --hard` |

### 分支类

| 命令 | 说明 |
|------|------|
| `:new-feature <描述>` | 从最新 main 创建功能分支 |
| `:new-hotfix <描述>` | 从最新 main 创建热修复分支 |
| `:finish-feature [远程]` | 变基到 main，推送，提醒创建 PR |
| `:sync-branch [基分支]` | 将当前分支变基到最新 origin/main |
| `:sync-fork [上游URL]` | 从上游仓库同步 fork 仓库 |

### 修复类

| 命令 | 说明 |
|------|------|
| `:fix-detached-head` | 脱离游离 HEAD 状态 — 保留工作到新分支或丢弃 |
| `:fix-push-rejected` | 修复非快进推送被拒绝的问题 |
| `:fix-rebase-mess` | 通过 reflog 中止或撤销异常变基 |
| `:resolve-conflict` | 逐文件引导式合并冲突解决 |

### 恢复类

| 命令 | 说明 |
|------|------|
| `:recover-branch <名称>` | 通过 reflog 恢复已删除的分支 |
| `:recover-stash` | 从悬空提交中恢复已丢弃的暂存 |

### 清理类

| 命令 | 说明 |
|------|------|
| `:clean-branches` | 删除已合并到 main 的本地分支 |
| `:clean-remote-branches` | 删除已合并到 main 的远程分支 |
| `:clean-stash` | 列出并清理旧的暂存条目 |
| `:prune-remotes` | 清理过时的远程跟踪引用 |

### 提交类

| 命令 | 说明 |
|------|------|
| `:commit-all [消息]` | 暂存所有变更并使用约定式消息提交 |
| `:squash-commits [N 或 "main"]` | 将多个提交压缩为一个 |

### 推送类

| 命令 | 说明 |
|------|------|
| `:push` | 智能推送 — 自动检测 upstream，新分支自动 `-u` |
| `:push-tags [标签名]` | 推送标签到远程，省略则推送所有标签 |
| `:force-push [远程]` | 安全强制推送（`--force-with-lease`），需确认 |

### 历史类

| 命令 | 说明 |
|------|------|
| `:remove-large-file <路径>` | 从 git 历史中移除大文件（会改写历史） |
| `:remove-sensitive <模式>` | 从历史中移除敏感数据（请先轮换凭据！） |

## 使用技巧

### 传递参数

大部分命令支持内联传参：

```
:new-feature add-user-auth          # 创建 feature/20260531-add-user-auth
:squash-commits 3                   # 压缩最近 3 个提交
:undo-commit 2                       # 撤销最近 2 个提交（软撤销）
:recover-branch my-lost-branch       # 恢复指定分支
```

### 安全默认值

插件始终优先选择更安全的替代方案：

- 优先使用 `--force-with-lease` 而非 `--force`
- 优先使用 `git revert` 而非 `git reset --hard` 处理共享提交
- 优先使用 `git reset --soft` 而非 `--mixed`/`--hard` 以保留工作
- 风险操作前自动 `git stash`
- 破坏性操作前必须用户确认

### 分支命名规范

分支格式：`<类型>/<yyyyMMdd>-<英文描述>`

- **描述必须使用英文**，采用 kebab-case，做到见名知义
- 如用户输入中文描述，自动翻译为英文

```
# 用户输入 "添加用户认证" → 自动翻译
feature/20260531-add-user-auth

# 用户输入 "修复启动崩溃" → 自动翻译
hotfix/20260531-fix-crash-on-start
```

### 提交消息规范

```
<类型>(<范围>): <中文主题>

<中文正文>
```

类型：`feat`、`fix`、`docs`、`style`、`refactor`、`perf`、`test`、`chore`、`ci`

规则：类型和范围保持英文，**主题和正文必须使用中文**；主题使用祈使语气，不超过 50 字符，不加句号。

示例：`feat(auth): 添加用户登录功能`

### 冲突解决

`:resolve-conflict` 提供引导式工作流：

1. 列出所有冲突文件
2. 逐文件展示冲突标记并解释双方内容
3. 提供批量解决方案（`--ours` / `--theirs`）或逐文件手动编辑
4. 暂存已解决的文件并继续 merge/rebase
5. 卡住时可选择 `--abort`

### 通过 Reflog 恢复

出错时，reflog 是你的安全网：

```bash
git reflog                    # 找到灾难发生前的提交
git reset --hard <hash>       # 恢复到该状态
```

`:recover-branch`、`:recover-stash`、`:undo-reset` 和 `:fix-rebase-mess` 命令都在底层使用 reflog 实现。

## 项目结构

```
git/
├── SKILL.md                          # 技能定义：安全规则、决策指南、规范约定
├── commands/                         # 子命令定义（冒号语法）
│   ├── undo-commit.md
│   ├── undo-commit-hard.md
│   ├── undo-push.md
│   ├── undo-reset.md
│   ├── new-feature.md
│   ├── new-hotfix.md
│   ├── finish-feature.md
│   ├── sync-branch.md
│   ├── sync-fork.md
│   ├── fix-detached-head.md
│   ├── fix-push-rejected.md
│   ├── fix-rebase-mess.md
│   ├── resolve-conflict.md
│   ├── recover-branch.md
│   ├── recover-stash.md
│   ├── clean-branches.md
│   ├── clean-remote-branches.md
│   ├── clean-stash.md
│   ├── prune-remotes.md
│   ├── commit-all.md
│   ├── squash-commits.md
│   ├── push.md
│   ├── push-tags.md
│   ├── force-push.md
│   ├── remove-large-file.md
│   └── remove-sensitive.md
├── references/                       # 参考文档（按需加载）
│   ├── commands.md                   # Git 命令速查表
│   └── troubleshooting.md            # Git 问题排查与恢复策略
└── .claude-plugin/
    ├── plugin.json                   # 插件元数据
    └── marketplace.json              # Marketplace 注册信息
```

## 工作原理

### 架构设计

插件在两个层面运行：

1. **技能层**（`SKILL.md`）— 定义安全规则、决策指南（merge vs rebase）、分支命名规范和提交消息格式。插件激活时此上下文会被加载，指导所有 git 相关操作，即使未通过特定命令触发。

2. **命令层**（`commands/*.md`）— 每个 `.md` 文件定义特定 git 操作的分步工作流。命令声明其允许使用的工具（如 `Bash`、`Read`、`Edit`）和可选的参数提示。通过 `:命令名` 调用时，将执行对应工作流并内置安全检查。

### 安全协议

任何破坏性操作前，插件会执行以下步骤：

1. 运行 `git status` 检查未提交的变更
2. 检查 `git stash list` 确认是否有需要保留的暂存
3. 展示 `git log --oneline -5` 让你了解当前位置
4. 询问是否可以使用非破坏性替代方案
5. 要求用户明确确认后才继续执行

### 命令执行流程

```
用户输入 :undo-commit
       ↓
插件匹配命令定义
       ↓
从 .md 文件读取命令步骤
       ↓
按顺序执行步骤，穿插安全检查
       ↓
向用户报告结果
```

### 参考文档按需加载

`references/` 目录包含补充文档，仅在 AI 需要更深上下文时按需加载 — 例如建议高级 git 操作或诊断异常问题时。这种设计保持默认上下文轻量，同时在需要时提供详细知识。