配置文件详解

Git Workflow 使用 JSON 格式的配置文件来自定义工具行为，支持全局配置和项目配置两种模式。

📁 配置文件位置

查找顺序

Git Workflow 按以下顺序查找配置文件：

当前目录 - ./gwrc.json
Git 仓库根目录 - <git-root>/.gwrc.json
用户主目录 - ~/.gwrc.json
内置默认配置

支持的文件名

项目配置支持多种文件名：

bash

.gwrc.json          # 推荐，JSON 格式
.gwrc               # 简化文件名
gw.config.json      # 明确的配置文件名

全局配置固定为：

bash

~/.gwrc.json        # 用户主目录下的全局配置

🔧 完整配置示例

基础配置

json

{
  "baseBranch": "develop",
  "featurePrefix": "feature",
  "hotfixPrefix": "hotfix",
  "requireId": true,
  "featureIdLabel": "Story ID",
  "hotfixIdLabel": "Issue ID",
  "defaultTagPrefix": "v",
  "autoPush": true,
  "autoStage": true,
  "useEmoji": true
}

完整配置

json

{
  "baseBranch": "develop",
  "featurePrefix": "feature",
  "hotfixPrefix": "hotfix",
  "requireId": true,
  "featureIdLabel": "Story ID",
  "hotfixIdLabel": "Issue ID",
  "defaultTagPrefix": "v",
  "autoPush": true,
  "autoStage": true,
  "useEmoji": true,
  "commitEmojis": {
    "feat": "✨",
    "fix": "🐛",
    "docs": "📝",
    "style": "💄",
    "refactor": "♻️",
    "perf": "⚡️",
    "test": "✅",
    "build": "📦",
    "ci": "👷",
    "chore": "🔧",
    "revert": "⏪"
  },
  "aiCommit": {
    "enabled": true,
    "provider": "github",
    "apiKey": "",
    "model": "gpt-4o-mini",
    "language": "zh-CN",
    "maxTokens": 200,
    "detailedDescription": true,
    "temperature": 0.7,
    "customPrompt": ""
  },
  "release": {
    "autoCommit": false,
    "autoTag": false,
    "commitMessage": "chore: release v{version}",
    "tagMessage": "Release v{version}"
  },
  "hooks": {
    "preCommit": "",
    "postCommit": "",
    "preTag": "",
    "postTag": ""
  }
}

📋 配置项详解

分支配置

baseBranch

类型： string
默认值： 自动检测
说明： 默认基础分支，不设置则自动检测 main/master

json

{
  "baseBranch": "develop"
}

效果：

所有新分支都基于 develop 创建
除非使用 --base 参数覆盖

featurePrefix

类型： string
默认值： "feature"
说明： feature 分支前缀

json

{
  "featurePrefix": "feat"
}

效果：

生成分支名：feat/20260111-PROJ-123-add-login

hotfixPrefix

类型： string
默认值： "hotfix"
说明： hotfix 分支前缀

json

{
  "hotfixPrefix": "fix"
}

效果：

生成分支名：fix/20260111-BUG-456-fix-crash

requireId

类型： boolean
默认值： false
说明： 是否强制要求填写 ID

json

{
  "requireId": true
}

效果：

创建分支时必须填写 ID，不能跳过
确保每个分支都能追溯到具体需求

featureIdLabel

类型： string
默认值： "Story ID"
说明： feature 分支 ID 提示文字

json

{
  "featureIdLabel": "Jira ID"
}

效果：

提示文字变为："请输入 Jira ID (可跳过):"

hotfixIdLabel

类型： string
默认值： "Issue ID"
说明： hotfix 分支 ID 提示文字

json

{
  "hotfixIdLabel": "Bug ID"
}

效果：

提示文字变为："请输入 Bug ID (可跳过):"

autoPush

类型： boolean
默认值： 不设置（每次询问）
说明： 创建分支后是否自动推送到远程

json

{
  "autoPush": true
}

选项说明：

true - 自动推送，不询问
false - 不推送，不询问
不设置 - 每次询问（默认行为）

版本配置

defaultTagPrefix

类型： string
默认值： 不设置
说明： 默认 tag 前缀，设置后跳过选择步骤

json

{
  "defaultTagPrefix": "v"
}

效果：

创建 tag 时直接使用 v 前缀
跳过前缀选择界面

提交配置

autoStage

类型： boolean
默认值： true
说明： commit 时是否自动暂存所有更改

json

{
  "autoStage": false
}

效果：

true - 自动暂存所有更改
false - 手动选择要暂存的文件

useEmoji

类型： boolean
默认值： true
说明： commit 时是否使用 emoji

json

{
  "useEmoji": false
}

效果：

true - ✨ feat(auth): 添加登录功能
false - feat(auth): 添加登录功能

commitEmojis

类型： object
默认值： 内置 emoji 映射
说明： 自定义各类型 commit 的 emoji

json

{
  "commitEmojis": {
    "feat": "🎉",
    "fix": "🔧",
    "docs": "📚"
  }
}

效果：

只覆盖指定的类型
未指定的类型使用默认 emoji

AI 配置

aiCommit.enabled

类型： boolean
默认值： true
说明： 是否启用 AI commit 功能

json

{
  "aiCommit": {
    "enabled": false
  }
}

aiCommit.provider

类型： string
默认值： "github"
说明： AI 提供商

json

{
  "aiCommit": {
    "provider": "openai"
  }
}

支持的提供商：

github - GitHub Models
openai - OpenAI
claude - Anthropic Claude
ollama - 本地 Ollama

aiCommit.apiKey

类型： string
默认值： 空字符串
说明： API key，留空使用内置 key（仅 GitHub Models）

json

{
  "aiCommit": {
    "apiKey": "your-api-key-here"
  }
}

aiCommit.model

类型： string
默认值： 根据提供商
说明： 模型名称

json

{
  "aiCommit": {
    "provider": "openai",
    "model": "gpt-4o-mini"
  }
}

常用模型：

GitHub: gpt-4o-mini, gpt-4o
OpenAI: gpt-4o-mini, gpt-3.5-turbo
Claude: claude-3-haiku-20240307
Ollama: llama3.2:3b, qwen2.5:7b

aiCommit.language

类型： string
默认值： "zh-CN"
说明： 生成语言

json

{
  "aiCommit": {
    "language": "en-US"
  }
}

支持的语言：

zh-CN - 中文
en-US - 英文

aiCommit.maxTokens

类型： number
默认值： 200（简洁模式）/ 400（详细模式）
说明： 最大 token 数

json

{
  "aiCommit": {
    "maxTokens": 150
  }
}

aiCommit.detailedDescription

类型： boolean
默认值： true
说明： 是否生成详细的修改点描述

json

{
  "aiCommit": {
    "detailedDescription": true
  }
}

效果对比：

简洁模式（detailedDescription: false）：

feat(auth): 添加用户登录功能

详细模式（detailedDescription: true）：

feat(auth): 添加用户登录功能

- 实现用户名密码登录接口
- 添加登录状态验证中间件
- 完善登录错误处理逻辑
- 更新用户认证相关文档

注意： 详细模式会自动使用更大的 maxTokens（400）和更长的 diff 长度限制（6000 字符）。

aiCommit.temperature

类型： number
默认值： 0.7
说明： 创造性参数（0-1）

json

{
  "aiCommit": {
    "temperature": 0.3
  }
}

参数说明：

0.0-0.3 - 保守，结果一致性高
0.4-0.7 - 平衡（推荐）
0.8-1.0 - 创造性高，结果多样

aiCommit.customPrompt

类型： string
默认值： 空字符串
说明： 自定义提示词

json

{
  "aiCommit": {
    "customPrompt": "请生成简洁的中文 commit message，格式为：类型(范围): 描述"
  }
}

发布配置

release.autoCommit

类型： boolean
默认值： false
说明： 版本更新后是否自动提交

json

{
  "release": {
    "autoCommit": true
  }
}

release.autoTag

类型： boolean
默认值： false
说明： 版本更新后是否自动创建标签

json

{
  "release": {
    "autoTag": true
  }
}

release.commitMessage

类型： string
默认值： "chore: release v{version}"
说明： 版本提交的消息模板

json

{
  "release": {
    "commitMessage": "🔖 chore: 发布版本 v{version}"
  }
}

release.tagMessage

类型： string
默认值： "Release v{version}"
说明： 标签消息模板

json

{
  "release": {
    "tagMessage": "发布版本 v{version}"
  }
}

钩子配置

hooks.preCommit

类型： string
默认值： 空字符串
说明： 提交前执行的命令

json

{
  "hooks": {
    "preCommit": "npm run lint"
  }
}

hooks.postCommit

类型： string
默认值： 空字符串
说明： 提交后执行的命令

json

{
  "hooks": {
    "postCommit": "npm run build"
  }
}

hooks.preTag

类型： string
默认值： 空字符串
说明： 创建标签前执行的命令

json

{
  "hooks": {
    "preTag": "npm test"
  }
}

hooks.postTag

类型： string
默认值： 空字符串
说明： 创建标签后执行的命令

json

{
  "hooks": {
    "postTag": "npm run changelog"
  }
}

🎯 配置场景示例

个人开发者配置

json

{
  "autoStage": true,
  "useEmoji": true,
  "requireId": false,
  "aiCommit": {
    "enabled": true,
    "provider": "github",
    "language": "zh-CN"
  }
}

团队协作配置

json

{
  "baseBranch": "develop",
  "requireId": true,
  "featureIdLabel": "Jira ID",
  "hotfixIdLabel": "Bug ID",
  "autoPush": true,
  "useEmoji": false,
  "autoStage": false
}

企业级配置

json

{
  "featurePrefix": "feat",
  "hotfixPrefix": "fix",
  "requireId": true,
  "featureIdLabel": "需求编号",
  "hotfixIdLabel": "缺陷编号",
  "useEmoji": false,
  "autoStage": false,
  "aiCommit": {
    "enabled": false
  },
  "hooks": {
    "preCommit": "npm run lint && npm test",
    "preTag": "npm run build"
  }
}

开源项目配置

json

{
  "baseBranch": "main",
  "requireId": false,
  "useEmoji": true,
  "aiCommit": {
    "enabled": true,
    "language": "en-US"
  },
  "release": {
    "autoCommit": true,
    "commitMessage": "chore: release v{version}"
  }
}

🔧 配置管理

创建配置文件

bash

# 交互式创建
gw init

# 手动创建
touch .gwrc.json

验证配置文件

bash

# 检查配置语法
node -e "console.log(JSON.parse(require('fs').readFileSync('.gwrc.json', 'utf8')))"

# 或使用在线 JSON 验证工具

配置文件模板

bash

# 复制配置模板
cp ~/.gwrc.json .gwrc.json

# 或从其他项目复制
cp ../other-project/.gwrc.json .

配置合并规则

当存在多个配置文件时，Git Workflow 会按优先级合并：

项目配置 覆盖 全局配置
全局配置 覆盖 默认配置
对象类型 进行深度合并
基本类型 直接覆盖

示例：

全局配置：

json

{
  "useEmoji": true,
  "aiCommit": {
    "enabled": true,
    "provider": "github",
    "language": "zh-CN"
  }
}

项目配置：

json

{
  "requireId": true,
  "aiCommit": {
    "provider": "openai"
  }
}

最终生效配置：

json

{
  "useEmoji": true,
  "requireId": true,
  "aiCommit": {
    "enabled": true,
    "provider": "openai",
    "language": "zh-CN"
  }
}

🚨 常见问题

配置文件语法错误

bash

❌ 配置文件语法错误: Unexpected token } in JSON

解决方案：

使用 JSON 验证工具检查语法
检查是否有多余的逗号
确保字符串使用双引号

配置项不生效

bash

❌ 配置项 'unknownOption' 不被识别

解决方案：

检查配置项名称是否正确
查看文档确认支持的配置项
更新到最新版本

权限问题

bash

❌ 无法写入配置文件: Permission denied

解决方案：

检查文件权限：ls -la .gwrc.json
修改权限：chmod 644 .gwrc.json
检查目录权限

配置冲突

bash

⚠️ 项目配置与全局配置存在冲突

解决方案：

项目配置优先级更高
检查合并结果是否符合预期
根据需要调整配置

📚 相关文档

AI 配置 - 详细的 AI commit 配置
分支配置 - 分支管理相关配置
提交配置 - 提交相关配置
配置示例 - 更多实际配置案例

通过合理配置，Git Workflow 可以完美适应你的工作流程。配置文件是工具的核心，掌握配置文件的使用是高效使用 Git Workflow 的关键。

配置文件详解 ​

📁 配置文件位置 ​

查找顺序 ​

支持的文件名 ​

🔧 完整配置示例 ​

基础配置 ​

完整配置 ​

📋 配置项详解 ​

分支配置 ​

baseBranch ​

featurePrefix ​

hotfixPrefix ​

requireId ​

featureIdLabel ​

hotfixIdLabel ​

autoPush ​

版本配置 ​

defaultTagPrefix ​

提交配置 ​

autoStage ​

useEmoji ​

commitEmojis ​

AI 配置 ​

aiCommit.enabled ​

aiCommit.provider ​

aiCommit.apiKey ​

aiCommit.model ​

aiCommit.language ​

aiCommit.maxTokens ​

aiCommit.detailedDescription ​

aiCommit.temperature ​

aiCommit.customPrompt ​

发布配置 ​

release.autoCommit ​

release.autoTag ​

release.commitMessage ​

release.tagMessage ​

钩子配置 ​

hooks.preCommit ​

hooks.postCommit ​

hooks.preTag ​

hooks.postTag ​

🎯 配置场景示例 ​

个人开发者配置 ​

团队协作配置 ​

企业级配置 ​

开源项目配置 ​

🔧 配置管理 ​

创建配置文件 ​

验证配置文件 ​

配置文件模板 ​

配置合并规则 ​

🚨 常见问题 ​

配置文件语法错误 ​

配置项不生效 ​

权限问题 ​

配置冲突 ​

📚 相关文档 ​

配置文件详解

📁 配置文件位置

查找顺序

支持的文件名

🔧 完整配置示例

基础配置

完整配置

📋 配置项详解

分支配置

baseBranch

featurePrefix

hotfixPrefix

requireId

featureIdLabel

hotfixIdLabel

autoPush

版本配置

defaultTagPrefix

提交配置

autoStage

useEmoji

commitEmojis

AI 配置

aiCommit.enabled

aiCommit.provider

aiCommit.apiKey

aiCommit.model

aiCommit.language

aiCommit.maxTokens

aiCommit.detailedDescription

aiCommit.temperature

aiCommit.customPrompt

发布配置

release.autoCommit

release.autoTag

release.commitMessage

release.tagMessage

钩子配置

hooks.preCommit

hooks.postCommit

hooks.preTag

hooks.postTag

🎯 配置场景示例

个人开发者配置

团队协作配置

企业级配置

开源项目配置

🔧 配置管理

创建配置文件

验证配置文件

配置文件模板

配置合并规则

🚨 常见问题

配置文件语法错误

配置项不生效

权限问题

配置冲突

📚 相关文档