规范化 Git 提交与标记管理
VSCode 扩展：规范化 Git 提交信息，管理本地与远程 Git 标记，支持自动版本号和完整的 Git Flow 工作流程。
作者: odinsam
功能特性
- ✅ 支持 Angular 格式提交模板：
<icon> <type>(<scope>): <subject>
- ✅ 支持自定义提交模板
- ✅ 支持自定义提交类型
- ✅ 自动获取版本号（可选）
- ✅ 支持 Emoji 图标（可配置）
- ✅ 交互式提交信息填写
- ✅ 支持多仓库工作区
- ✅ 支持多项目配置（Monorepo）
- ✅ 自动从配置文件读取版本号
- ✅ 支持创建轻量标记和附注标记
- ✅ 支持批量删除本地与远程标记
- ✅ 支持选择远程仓库并推送全部本地标记
- ✅ 提交与标记流程支持逐级返回
- ✅ 完整的 Git Flow 工作流程支持
- ✅ 智能分支检测和操作推荐
安装
从源码安装
- 克隆或下载本项目
- 在项目目录下运行
npm install 安装依赖
- 运行
npm run compile 编译项目
- 按
F5 在扩展开发宿主中运行，或使用 vsce package 打包为 .vsix 文件
使用说明
基本使用
- 在 VSCode 中打开包含 Git 仓库的项目
- 在源代码管理（SCM）面板中，点击提交按钮旁的图标
- 选择“提交代码”或“标记管理”
- 点击 Git Flow 按钮（分支图标）进行 Git Flow 操作
- 或者使用命令面板（
Ctrl+Shift+P / Cmd+Shift+P），输入相关命令
注意：选择“提交代码”后，扩展会检查是否存在 .gitcommit 配置文件。如果不存在，会询问是否创建；标记管理不依赖该配置文件。
Commit 流程
- 选择操作：点击 SCM 面板中的扩展图标，然后选择“提交代码”
- 选择模板：选择提交使用的模板（默认 Angular 格式）
- 选择类型：选择提交类型（feat、fix、docs 等）
- 填写信息：
- Scope（可选）：修改范围
- Subject（必填）：提交概述
- Body（可选）：详细说明
- Footer（可选）：备注信息
- 完成：提交信息会自动填充到 Git 提交输入框，如果启用了
autoVersion，会自动添加版本信息
模板、提交类型和提交详情之间支持逐级返回；在信息输入框中按 Esc 可返回提交详情列表。返回过程中不会生成或提交代码。
Git 标记管理
点击 SCM 面板中的扩展图标，选择“标记管理”，可执行以下操作：
创建标记
- 选择“附注标记”或“轻量标记”
- 选择标记目标：当前分支最新提交（
HEAD）或某个本地分支的最新提交
- 输入符合 Git 命名规则的标记名称，例如
v1.0.0
- 创建附注标记时，继续输入标记说明
如果本地已经存在同名标记，扩展会阻止重复创建。
删除本地标记
- 从本地标记列表中选择一个或多个标记
- 检查待删除的标记名称和数量
- 在确认对话框中执行删除
删除远程标记
- 选择远程仓库
- 扩展实时获取该远程仓库中的全部标记
- 选择一个或多个远程标记
- 确认后仅删除所选远程标记，不会同时删除本地标记
推送全部标记
- 选择目标远程仓库
- 扩展获取远程标记，并显示本地标记总数及远程尚不存在的标记数量
- 确认后推送全部本地标记
远程已存在且指向相同提交的标记会被 Git 跳过；同名但指向不同提交的标记默认不会被覆盖。删除和推送操作执行前均需要二次确认。
所有标记选择列表均在最后提供“返回上一级”，输入框可通过 Esc 返回上一选择步骤。返回过程中不会执行 Git 命令。
Git Flow 工作流程
Git Flow 是一个 Git 分支管理模型，帮助团队更好地管理代码发布流程。
快速开始
初始化 Git Flow：
- 点击 SCM 面板的 Git Flow 按钮
- 选择"初始化 Git Flow"
- 设置主分支名称（master/main）和开发分支名称（develop）
使用 Git Flow：
- 点击 SCM 面板的 Git Flow 按钮
- 根据当前分支类型，扩展会智能显示相关操作
- 选择要执行的操作
分支类型说明
主分支（Master/Main）：
开发分支（Develop）：
Feature 分支：
- 从
develop 分支创建
- 用于开发新功能
- 完成后合并回
develop
Release 分支：
- 从
develop 分支创建
- 用于准备新版本发布
- 完成后合并到
master 和 develop，并在 master 上创建标签
Hotfix 分支：
- 从
master 分支创建
- 用于紧急修复生产环境问题
- 完成后合并到
master 和 develop，并在 master 上创建标签
智能操作推荐
扩展会根据当前所在的分支类型，智能推荐相关操作：
- 在 Feature 分支上：优先显示"完成当前 Feature 分支"
- 在 Release 分支上：优先显示"完成当前 Release 分支"
- 在 Hotfix 分支上：优先显示"完成当前 Hotfix 分支"
- 在其他分支上：显示所有可用操作
操作示例
场景：你在 feature/user-login 分支上开发完成
- 点击 SCM 面板的 Git Flow 按钮
- 选择"完成当前 Feature 分支"
- 选择是否保留分支
- 自动合并到
develop 分支
场景：准备发布新版本
- 点击 SCM 面板的 Git Flow 按钮
- 选择"Release: 开始"
- 输入版本号（如：1.0.0）
- 在 Release 分支上进行测试和修复
- 完成后选择"完成当前 Release 分支"
- 输入 Tag 消息（可选）
- 自动合并到
master 和 develop，并创建标签
配置选项
在 VSCode 设置中搜索 "odinsamGitCommit" 进行配置：
- showEmoji: 是否显示 Emoji 图标（默认：true）
- maxSubjectWords: Subject 的最大长度（默认：50）
- customCommitType: 自定义提交类型
- templates: 自定义提交模板
- autoVersion: 是否在提交信息中自动添加版本号（默认：false）
自定义模板
在设置中配置自定义模板：
{
"odinsamGitCommit.templates": [
{
"templateName": "Angular",
"templateContent": "<icon><space><type>(<scope>):<space><subject><enter><body><enter><footer>"
},
{
"templateName": "git-cz",
"templateContent": "<type>(<scope>):<space><icon><space><subject><enter><body><enter><footer>"
}
]
}
模板占位符说明：
<icon>: 图标（Emoji）<type>: 提交类型<scope>: 修改范围<subject>: 提交概述<body>: 详细说明<footer>: 备注信息<enter>: 换行（两个换行符）<space>: 空格
自动版本号
启用 autoVersion 后，提交信息会自动添加版本号信息。版本号的获取优先级如下：
- 项目配置文件（
.gitcommit）- 最高优先级
- Git Tag - 当前提交的 tag
- 提交哈希 - 当前提交的哈希值（前8位）
使用项目配置文件
在 monorepo 场景下，可以为每个项目创建独立的 .gitcommit 配置文件来指定版本号。
配置文件位置：放在项目根目录（每个子项目的根目录）
配置文件格式（JSON 格式）：
单项目配置：
{
"projectName": "Insurance.Api",
"path": "package.json",
"versionRegex": "\"version\"\\s*:\\s*\"([\\d.]+)\"",
"description": "项目版本号"
}
多项目配置：
{
"config": [
{
"projectName": "Insurance.Api",
"path": "package.json",
"versionRegex": "\"version\"\\s*:\\s*\"([\\d.]+)\"",
"description": "API 项目版本号"
},
{
"projectName": "Insurance.Web",
"path": "package.json",
"versionRegex": "\"version\"\\s*:\\s*\"([\\d.]+)\"",
"description": "Web 项目版本号"
}
]
}
配置说明：
projectName：项目名称path：版本文件路径（相对于 .gitcommit 文件所在目录）versionRegex：用于从文件中提取版本号的正则表达式（第一个捕获组作为版本号）description：项目描述（可选）
支持的版本文件类型及正则表达式示例：
package.json - "version"\\s*:\\s*"([\\d.]+)".csproj - <Version>([\\d.]+)</Version>- 其他文件 - 根据实际格式自定义正则表达式
自动创建配置文件：
首次使用时，如果没有 .gitcommit 配置文件，扩展会询问是否创建：
- 创建单项目配置：生成单项目格式的配置文件
- 创建多项目配置：生成多项目格式的配置文件
多项目配置项目选择：
如果使用多项目配置，在生成提交信息时会提示选择要提交的项目。如果不选择项目，版本号将无效。标记管理不读取多项目版本配置。
示例输出：
如果从配置文件读取：
feat(缓存): 实现分布式缓存功能
版本: 1.0.0 (Insurance.Api)
分支: feature/odin-batchTemplateImport
如果从 Git Tag 读取：
feat(缓存): 实现分布式缓存功能
版本: v1.0.0 (基于 v1.0.0)
分支: feature/odin-batchTemplateImport
如果从提交哈希读取：
feat(缓存): 实现分布式缓存功能
版本: 2a65ad99
分支: feature/odin-batchTemplateImport
常见问题
1. 多项目配置中如何选择项目？
如果使用多项目配置，在生成提交信息时，扩展会显示项目列表供选择。如果不选择项目，版本号将无效，但提交流程可以继续。
2. Git Flow 中的标签是如何创建的？
在完成 Release 或 Hotfix 分支时，扩展会自动创建标签。标签名称格式为：[版本标签前缀]版本号（例如：v1.0.0）。可以在完成分支时输入自定义的 Tag 消息。
3. 如何手动管理 Git 标记？
点击 SCM 面板中的扩展图标，选择“标记管理”。可以创建轻量或附注标记、批量删除本地或远程标记，以及将全部本地标记推送到选定的远程仓库。
4. 如何修改配置文件？
.gitcommit 配置文件是 JSON 格式，可以直接在 VSCode 中编辑。配置文件的路径相对于配置文件所在目录。
5. 版本号正则表达式如何编写？
版本号正则表达式使用 JavaScript 正则表达式语法，第一个捕获组（括号）作为版本号。例如：
"version"\\s*:\\s*"([\\d.]+)" - 匹配 "version": "1.0.0"，提取 1.0.0<Version>([\\d.]+)</Version> - 匹配 <Version>1.0.0</Version>，提取 1.0.0
6. 如何启用自动版本号？
在 VSCode 设置中搜索 odinsamGitCommit.autoVersion，设置为 true 即可。或者在设置文件中添加：
{
"odinsamGitCommit.autoVersion": true
}
7. Git Flow 是否必须初始化？
是的，使用 Git Flow 功能前需要先初始化。初始化会：
- 设置主分支和开发分支名称
- 配置分支前缀（feature/、release/、hotfix/ 等）
- 如果 develop 分支不存在，会自动创建
8. 如果当前不在 Git 仓库中会怎样？
如果当前工作区不是 Git 仓库，扩展会显示友好的提示信息："当前不在 Git 仓库中，请先打开一个 Git 仓库"，不会执行任何操作。
9. 如何完成当前分支？
如果当前在 Feature/Release/Hotfix 分支上，点击 Git Flow 按钮后，会优先显示"完成当前 [分支类型] 分支"选项，选择后可以直接完成当前分支，无需手动输入分支名称。
提交类型
默认支持的提交类型：
- ✨ feat: 添加新特性
- 🐞 fix: 修复bug
- 📃 docs: 仅仅修改文档
- 🌈 style: 代码格式修改
- 🦄 refactor: 代码重构
- 🎈 perf: 性能优化
- 🧪 test: 增加测试用例
- 🔧 build: 依赖相关的内容
- 🐎 ci: CI配置相关
- 🐳 chore: 改变构建流程、或者增加依赖库、工具等
- ↩ revert: 回滚到上一个版本
开发调试
环境准备
# 安装依赖
npm install
# 编译项目
npm run compile
# 监听模式编译（自动重新编译）
npm run watch
调试扩展
- 在 VSCode 中打开本项目
- 按
F5 或点击"运行和调试"面板中的"运行扩展"
- 会打开一个新的 VSCode 窗口（扩展开发宿主）
- 在新窗口中测试扩展功能
打包扩展
npm run package
会在项目根目录生成 .vsix 文件。
项目结构
odinsam-GitCommit/
├── src/
│ ├── config/ # 配置模块
│ │ ├── commit-type.ts # 提交类型配置
│ │ ├── template-type.ts # 模板配置
│ │ ├── commit-detail.ts # 提交详情配置
│ │ └── commit-input.ts # 输入框配置
│ ├── services/ # 服务模块
│ │ ├── versionService.ts # 版本号服务
│ │ ├── configService.ts # 配置服务
│ │ ├── templateService.ts # 模板服务
│ │ ├── gitFlowService.ts # Git Flow 服务
│ │ └── tagService.ts # Git 标记服务
│ ├── types/ # 类型定义
│ │ ├── git.d.ts # Git 类型定义
│ │ └── commit.d.ts # 提交信息类型定义
│ └── extension.ts # 扩展主入口
├── out/ # 编译输出目录
├── package.json # 扩展配置文件
├── tsconfig.json # TypeScript 配置
└── README.md # 说明文档
作者
odinsam
许可证
本项目采用 MIT 许可证。
