以便捷的方式编辑 Git 提交信息。
特性亮点
默认设置遵循 Conventional Commits 规范。
更多截图
自定义提交信息表单
自定义提交信息表单最简单的方法是使用配置编辑器。要打开配置编辑器，请从命令面板中选择 Commit Message Editor: Open Settings Page 命令，或点击提交信息编辑器标签页右上角的齿轮图标。在这里，你可以导出当前配置或导入其他配置。加载的配置可以保存到用户或工作区设置。
为可移植配置文件格式创建了 JSON schema。这意味着你可以使用 VSCode 工具集手动编辑配置文件。只需创建一个包含以下内容的新 JSON 文件并开始编辑：
{
"$schema": "https://bendera.github.io/vscode-commit-message-editor/schemas/config-v1.schema.json"
}
可移植配置文件的结构
configVersion
当前版本："1"。将来可能会更改。
staticTemplate
文本视图的模板，字符串数组。数组中的每个项都是单独的一行。
dynamicTemplate
表单视图的模板，字符串数组。数组中的每个项都是单独的一行。
表单字段（见下一节）可以在模板中使用 {token_name} 格式引用。
tokens
token 对象数组。它定义了表单字段。下表显示了 token 对象的结构：
| 名称 |
类型 |
描述 |
适用范围 |
| label |
string |
表单项的标签。 |
所有 |
| name |
string |
模板中的 token 名称。 |
所有 |
| value |
string |
布尔 token 为 true 时的值 |
boolean |
| type |
enum |
token 的类型。有效值为：
text: 显示为文本输入
boolean: 显示为复选框
enum: 显示为下拉选择器
dynamic-enum: 显示为从提供者加载选项的下拉选择器 |
所有 |
| description |
string |
表单项下方的较长文本 |
所有 |
| prefix |
string |
值之前的文本。仅在值不为空时应用 |
所有 |
| suffix |
string |
值之后的文本。仅在值不为空时应用 |
所有 |
| multiline |
boolean |
多行文本输入 |
text |
| monospace |
boolean |
在多行模式下使用等宽编辑器 |
text |
| lines |
number |
文本区域初始高度（行数） |
text |
| maxLines |
number |
文本区域最大高度（行数） |
text |
| maxLength |
number |
值的最大长度 |
text |
| maxLineLength |
number |
使用等宽编辑器时垂直标尺的位置 |
text |
| multiple |
boolean |
多个选项 |
enum |
| separator |
string |
选择多个选项时的分隔符 |
enum |
| combobox |
boolean |
选择器是否可过滤 |
enum, dynamic-enum |
| options |
array |
可用选项 |
enum |
| options[{n}].label |
string |
选项的值 |
enum |
| options[{n}].description |
string |
选项的详细描述 |
enum |
| provider |
string |
动态选项提供者的 ID（dynamic-enum 必需） |
dynamic-enum |
| shown |
string |
条件显示表达式。不存在时始终显示；存在时，表达式为 true 才显示。可引用任意其他 token 的值 |
所有 |
shown 条件表达式
shown 字段控制 token 是否在表单中显示：
- 不设置
shown：token 始终显示
- 设置
shown：对表达式求值，true 则显示，false 则隐藏
表达式中可以直接引用其他任意 token 的名称作为变量：
示例（type 为其他 token 的名称）：
type == 'feat'type == 'fix' || type == 'hotfix'type in ['fix', 'hotfix', 'bug']type =~ /^(fix|feat)/issue =~ /customer/ && type == 'fix'
支持的操作符：==、!=、<、>、<=、>=、&&、||、!、in、=~（正则匹配）
示例配置
{
"tokens": [
{
"label": "类型",
"name": "type",
"type": "enum",
"options": [
{ "label": "feat", "value": "feat", "description": "新功能" },
{ "label": "fix", "value": "fix", "description": "错误修复" },
{ "label": "docs", "value": "docs", "description": "文档变更" }
]
},
{
"label": "破坏性变更说明",
"name": "breaking",
"type": "text",
"multiline": true,
"shown": "type == 'feat' || type == 'fix'"
},
{
"label": "问题编号",
"name": "issue",
"type": "text",
"prefix": "Closes #",
"shown": "type in ['fix', 'hotfix']"
}
]
}
在此示例中：
breaking 字段仅在 type 为 feat 或 fix 时显示issue 字段仅在 type 为 fix 或 hotfix 时显示
动态枚举提供者 API
从 0.19.0 版本开始，此扩展提供了一个 API，允许其他 VSCode 扩展注册动态选项提供者。这些提供者可以从外部源（API、Git 信息、文件系统等）动态获取枚举选项，而不是使用静态配置。
使用场景
- 从项目管理系统获取 Jira/GitHub 问题
- 从 Git 分支名称中提取问题编号
- 从代码库中列出项目组件
- 从组织目录加载用户列表
- 任何其他动态数据源
快速示例
import * as vscode from 'vscode';
export function activate(context: vscode.ExtensionContext) {
const cmeExtension = vscode.extensions.getExtension(
'adam-bender.commit-message-editor'
);
if (cmeExtension) {
const cmeAPI = cmeExtension.exports;
const disposable = cmeAPI.registerDynamicOptionsProvider({
id: 'my-provider',
displayName: 'My Provider',
async provideOptions(context, token) {
// 从数据源获取选项
return [
{ value: 'option1', label: 'Option 1', description: 'First option' },
{ value: 'option2', label: 'Option 2', description: 'Second option' },
];
},
});
context.subscriptions.push(disposable);
}
}
文档
完整的文档、示例和最佳实践，请参阅：
示例提供者
文档包含以下完整实现示例：
- Jira Provider: 从当前 sprint 获取问题
- Git Branch Provider: 从分支名称中提取问题编号
- File System Provider: 从项目结构中列出组件
完整示例配置
你可以使用 scripts/gitmoji-config.js 脚本自定义 Gitmoji 配置
