@zjex/git-workflow 0.2.24 → 0.3.2

package/docs/config/index.md

@@ -0,0 +1,478 @@
+# 配置概览
+
+Git Workflow 提供了灵活的配置系统，支持全局配置和项目配置，让你可以根据不同的需求自定义工具行为。
+
+## 🎯 配置理念
+
+### 约定优于配置
+
+Git Workflow 遵循"约定优于配置"的原则：
+
+- **零配置开箱即用** - 无需任何配置即可开始使用
+- **合理的默认值** - 提供适合大多数场景的默认配置
+- **渐进式配置** - 可以根据需要逐步添加配置项
+
+### 灵活的配置层级
+
+支持多层级配置，满足不同场景需求：
+
+1. **内置默认配置** - 工具内置的基础配置
+2. **全局配置** - 对所有项目生效的个人配置
+3. **项目配置** - 仅对当前项目生效的团队配置
+
+**配置优先级：** 项目配置 > 全局配置 > 默认配置
+
+## 📁 配置文件位置
+
+### 全局配置
+
+```
+~/.gwrc.json
+```
+
+**特点：**
+- 对所有项目生效
+- 适合个人偏好设置
+- 一次配置，处处使用
+
+**适用场景：**
+- AI commit 配置（API key、提供商等）
+- 个人习惯配置（emoji、自动暂存等）
+- 通用的分支命名规范
+
+### 项目配置
+
+支持多种文件名，按优先级查找：
+
+```
+.gwrc.json          # 推荐，JSON 格式
+.gwrc               # 简化文件名
+gw.config.json      # 明确的配置文件名
+```
+
+**特点：**
+- 仅对当前项目生效
+- 可以提交到版本控制
+- 团队成员共享配置
+
+**适用场景：**
+- 团队统一的分支规范
+- 项目特定的 ID 要求
+- 特殊的分支前缀
+
+### 查找顺序
+
+Git Workflow 按以下顺序查找配置文件：
+
+1. **当前目录** - `./gwrc.json`
+2. **Git 仓库根目录** - `<git-root>/.gwrc.json`
+3. **用户主目录** - `~/.gwrc.json`
+4. **内置默认配置**
+
+## 🚀 快速开始
+
+### 创建全局配置（推荐）
+
+```bash
+gw init
+```
+
+选择配置范围：
+
+```
+⚙️  初始化 git-workflow 配置
+
+? 选择配置范围:
+❯ 全局配置（所有项目生效）      # 推荐！配置一次，所有项目都能用
+  项目配置（仅当前项目）         # 为特定项目自定义配置
+```
+
+选择 **全局配置**，按提示完成配置：
+
+```
+✔ 选择配置范围: 全局配置（所有项目生效）
+
+? Feature 分支前缀: feature
+? Hotfix 分支前缀: hotfix
+? 是否强制要求填写 ID: 否
+? Feature 分支 ID 标签: Story ID
+? Hotfix 分支 ID 标签: Issue ID
+? 提交时是否自动暂存所有更改: 是
+? 是否使用 emoji: 是
+
+? 是否启用 AI commit 功能: 是
+? 选择 AI 提供商: GitHub Models（免费，推荐）
+? 输入你的 GitHub Token: ghp_xxxxxxxxxxxx
+? 选择语言: 中文
+
+✔ 全局配置已保存到: ~/.gwrc.json
+```
+
+### 创建项目配置
+
+在项目根目录运行：
+
+```bash
+cd your-project
+gw init
+```
+
+选择 **项目配置**，配置团队规范：
+
+```
+✔ 选择配置范围: 项目配置（仅当前项目）
+
+? 是否强制要求填写 ID: 是
+? Feature 分支 ID 标签: Jira ID
+? Hotfix 分支 ID 标签: Bug ID
+? 创建分支后是否自动推送到远程: 是
+? 默认基础分支: develop
+
+✔ 项目配置已保存到: .gwrc.json
+```
+
+## 📋 配置项详解
+
+### 完整配置示例
+
+```json
+{
+  "baseBranch": "develop",
+  "featurePrefix": "feature",
+  "hotfixPrefix": "hotfix",
+  "requireId": true,
+  "featureIdLabel": "Jira ID",
+  "hotfixIdLabel": "Bug ID",
+  "defaultTagPrefix": "v",
+  "autoPush": true,
+  "autoStage": true,
+  "useEmoji": true,
+  "commitEmojis": {
+    "feat": "✨",
+    "fix": "🐛",
+    "docs": "📝"
+  },
+  "aiCommit": {
+    "enabled": true,
+    "provider": "github",
+    "apiKey": "ghp_xxxxxxxxxxxx",
+    "model": "gpt-4o-mini",
+    "language": "zh-CN",
+    "maxTokens": 200,
+    "detailedDescription": true
+  }
+}
+```
+
+### 基础配置
+
+| 配置项           | 类型      | 默认值      | 说明                                     |
+| ---------------- | --------- | ----------- | ---------------------------------------- |
+| `baseBranch`     | `string`  | 自动检测    | 默认基础分支，不设置则自动检测 main/master |
+| `featurePrefix`  | `string`  | `"feature"` | feature 分支前缀                         |
+| `hotfixPrefix`   | `string`  | `"hotfix"`  | hotfix 分支前缀                          |
+
+### 分支配置
+
+| 配置项             | 类型      | 默认值       | 说明                                                                            |
+| ------------------ | --------- | ------------ | ------------------------------------------------------------------------------- |
+| `requireId`        | `boolean` | `false`      | 是否强制要求填写 ID。开启后创建分支时必须填写 ID，不能跳过                      |
+| `featureIdLabel`   | `string`  | `"Story ID"` | feature 分支 ID 提示文字                                                        |
+| `hotfixIdLabel`    | `string`  | `"Issue ID"` | hotfix 分支 ID 提示文字                                                         |
+| `autoPush`         | `boolean` | -            | 创建分支后是否自动推送到远程。`true` 自动推送，`false` 不推送，不设置则每次询问 |
+
+### 版本配置
+
+| 配置项             | 类型     | 默认值 | 说明                              |
+| ------------------ | -------- | ------ | --------------------------------- |
+| `defaultTagPrefix` | `string` | -      | 默认 tag 前缀，设置后跳过选择步骤 |
+
+### 提交配置
+
+| 配置项         | 类型      | 默认值 | 说明                          |
+| -------------- | --------- | ------ | ----------------------------- |
+| `autoStage`    | `boolean` | `true` | commit 时是否自动暂存所有更改 |
+| `useEmoji`     | `boolean` | `true` | commit 时是否使用 emoji       |
+| `commitEmojis` | `object`  | -      | 自定义各类型 commit 的 emoji  |
+
+### AI 配置
+
+| 配置项                        | 类型      | 默认值     | 说明                                                 |
+| ----------------------------- | --------- | ---------- | ---------------------------------------------------- |
+| `aiCommit.enabled`            | `boolean` | `true`     | 是否启用 AI commit 功能                              |
+| `aiCommit.provider`           | `string`  | `"github"` | AI 提供商：`github` / `openai` / `claude` / `ollama` |
+| `aiCommit.apiKey`             | `string`  | -          | API key，留空使用内置 key                            |
+| `aiCommit.model`              | `string`  | 根据提供商 | 模型名称                                             |
+| `aiCommit.language`           | `string`  | `"zh-CN"`  | 生成语言：`zh-CN` / `en-US`                          |
+| `aiCommit.maxTokens`          | `number`  | `200`      | 最大 token 数                                        |
+| `aiCommit.detailedDescription` | `boolean` | `true`     | 是否生成详细的修改点描述                             |
+
+## 🎨 配置场景
+
+### 场景一：个人开发者
+
+**需求：**
+- 启用 AI commit
+- 使用 emoji
+- 自动暂存文件
+- 不强制要求 ID
+
+**配置：**
+
+```json
+{
+  "autoStage": true,
+  "useEmoji": true,
+  "requireId": false,
+  "aiCommit": {
+    "enabled": true,
+    "provider": "github",
+    "language": "zh-CN"
+  }
+}
+```
+
+### 场景二：团队协作
+
+**需求：**
+- 统一分支命名规范
+- 强制关联 Issue/Story
+- 自动推送到远程
+- 基于 develop 分支开发
+
+**配置：**
+
+```json
+{
+  "baseBranch": "develop",
+  "requireId": true,
+  "featureIdLabel": "Jira ID",
+  "hotfixIdLabel": "Bug ID",
+  "autoPush": true
+}
+```
+
+### 场景三：企业级项目
+
+**需求：**
+- 严格的分支规范
+- 禁用 emoji（CI/CD 兼容性）
+- 自定义分支前缀
+- 手动选择暂存文件
+
+**配置：**
+
+```json
+{
+  "featurePrefix": "feat",
+  "hotfixPrefix": "fix",
+  "requireId": true,
+  "featureIdLabel": "需求编号",
+  "hotfixIdLabel": "缺陷编号",
+  "useEmoji": false,
+  "autoStage": false,
+  "aiCommit": {
+    "enabled": false
+  }
+}
+```
+
+### 场景四：开源项目
+
+**需求：**
+- 英文提交信息
+- 使用 emoji
+- 不强制 ID
+- 基于 main 分支
+
+**配置：**
+
+```json
+{
+  "baseBranch": "main",
+  "requireId": false,
+  "useEmoji": true,
+  "aiCommit": {
+    "enabled": true,
+    "language": "en-US"
+  }
+}
+```
+
+## 🔧 配置管理
+
+### 查看当前配置
+
+```bash
+# 查看生效的配置
+gw config show
+
+# 查看配置文件位置
+gw config path
+```
+
+### 编辑配置
+
+```bash
+# 编辑全局配置
+gw config edit --global
+
+# 编辑项目配置
+gw config edit --local
+```
+
+### 重置配置
+
+```bash
+# 重置为默认配置
+gw config reset
+
+# 删除配置文件
+gw config clean
+```
+
+### 验证配置
+
+```bash
+# 验证配置文件语法
+gw config validate
+
+# 测试配置效果
+gw config test
+```
+
+## 📚 配置最佳实践
+
+### 1. 分层配置策略
+
+**全局配置（个人偏好）：**
+```json
+{
+  "aiCommit": {
+    "enabled": true,
+    "provider": "github",
+    "apiKey": "your-token"
+  },
+  "useEmoji": true,
+  "autoStage": true
+}
+```
+
+**项目配置（团队规范）：**
+```json
+{
+  "requireId": true,
+  "featureIdLabel": "Jira ID",
+  "autoPush": true,
+  "baseBranch": "develop"
+}
+```
+
+### 2. 版本控制
+
+**提交项目配置：**
+```bash
+git add .gwrc.json
+git commit -m "chore: add git-workflow config"
+```
+
+**忽略敏感信息：**
+```gitignore
+# .gitignore
+.gwrc.local.json  # 本地覆盖配置
+```
+
+### 3. 团队协作
+
+**文档化配置：**
+```markdown
+# 项目配置说明
+
+本项目使用 git-workflow 进行版本管理，配置如下：
+
+- 分支前缀：feature/、hotfix/
+- 必须填写 Jira ID
+- 基于 develop 分支开发
+- 自动推送到远程
+
+## 安装和配置
+
+1. 安装工具：`npm install -g @zjex/git-workflow`
+2. 配置已包含在项目中，无需额外配置
+3. 开始使用：`gw f` 创建功能分支
+```
+
+### 4. 配置迁移
+
+**从旧版本迁移：**
+```bash
+# 备份旧配置
+cp ~/.gwrc.json ~/.gwrc.json.backup
+
+# 重新初始化
+gw init --migrate
+```
+
+**跨项目复制配置：**
+```bash
+# 复制配置到新项目
+cp project-a/.gwrc.json project-b/.gwrc.json
+```
+
+## 🔍 故障排除
+
+### 配置文件语法错误
+
+```bash
+❌ 配置文件语法错误: Unexpected token } in JSON
+```
+
+**解决方案：**
+1. 使用 JSON 验证工具检查语法
+2. 重新运行 `gw init` 生成新配置
+3. 参考文档中的配置示例
+
+### 配置项不生效
+
+```bash
+❌ 配置项 'unknownOption' 不被识别
+```
+
+**解决方案：**
+1. 检查配置项名称是否正确
+2. 查看文档确认支持的配置项
+3. 更新到最新版本
+
+### 权限问题
+
+```bash
+❌ 无法写入配置文件: Permission denied
+```
+
+**解决方案：**
+1. 检查文件权限：`ls -la ~/.gwrc.json`
+2. 修改权限：`chmod 644 ~/.gwrc.json`
+3. 使用 sudo（不推荐）
+
+### 配置冲突
+
+```bash
+⚠️ 项目配置与全局配置存在冲突
+```
+
+**解决方案：**
+1. 项目配置优先级更高，会覆盖全局配置
+2. 检查配置合并结果：`gw config show`
+3. 根据需要调整配置
+
+## 📖 深入学习
+
+- [**配置文件详解**](/config/config-file) - 了解所有配置项的详细说明
+- [**AI 配置**](/config/ai-config) - 深入配置 AI commit 功能
+- [**分支配置**](/config/branch-config) - 自定义分支管理行为
+- [**提交配置**](/config/commit-config) - 配置提交相关功能
+- [**配置示例**](/config/examples) - 查看更多实际配置案例
+
+---
+
+通过合理的配置，Git Workflow 可以完美适应你的工作流程。从简单的个人项目到复杂的企业级应用，都能找到合适的配置方案。

package/docs/features/git-wrapped.md

@@ -0,0 +1,199 @@
+# 🎉 Git Wrapped - 年度编程回顾
+
+> 将你的Git活动转化为精美的年度报告，让编程成就可视化
+
+## 📋 功能概述
+
+Git Wrapped 是一个受 Spotify Wrapped 启发的功能，它分析你的Git提交历史，生成一份精美的年度编程报告。这不仅是对过去一年编程工作的总结，更是对个人成长的庆祝。
+
+## 🎯 核心功能
+
+### 基础命令
+```bash
+gw wrapped              # 生成当前年份报告
+gw wrapped 2024         # 生成指定年份报告
+gw wrapped --share      # 生成可分享的图片版本
+gw wrapped --format png # 指定输出格式 (png/svg/pdf)
+gw wrapped --theme dark # 指定主题风格
+```
+
+### 高级选项
+```bash
+gw wrapped --repo ./my-project    # 分析特定仓库
+gw wrapped --author "张三"        # 分析特定作者
+gw wrapped --range 2024-01-01..2024-12-31  # 自定义时间范围
+gw wrapped --compare 2023         # 与去年对比
+gw wrapped --team                  # 生成团队报告
+```
+
+## 📊 报告内容
+
+### 1. 📈 基础统计
+- **总提交数**: 今年的总提交次数
+- **活跃天数**: 有提交活动的天数
+- **最长连击**: 连续提交的最长天数
+- **代码行数**: 新增/删除的代码行数统计
+- **文件变更**: 修改的文件总数
+
+### 2. 🏆 年度亮点
+- **最忙碌的月份**: 提交最多的月份
+- **最活跃时间**: 最常提交的时间段
+- **最大单日提交**: 单日最多提交次数
+- **里程碑时刻**: 重要的提交节点
+- **项目贡献**: 贡献最多的项目
+
+### 3. 💻 技术分析
+- **编程语言分布**: 各语言使用占比
+- **文件类型统计**: 最常修改的文件类型
+- **提交类型分析**: feat/fix/docs等类型分布
+- **项目活跃度**: 各项目的贡献分布
+
+### 4. ⏰ 时间模式
+- **编程习惯**: 早鸟 vs 夜猫子分析
+- **工作日 vs 周末**: 工作时间分布
+- **月度趋势**: 全年活跃度变化曲线
+- **季节性模式**: 不同季节的编程活跃度
+
+### 5. 🎨 个性化洞察
+- **编程风格**: 基于提交信息的风格分析
+- **专注度**: 单次提交的平均文件数
+- **完美主义指数**: 小提交 vs 大提交的比例
+- **探索精神**: 新项目/新语言的尝试次数
+
+## 🎨 视觉设计
+
+### 终端版本
+```
+╭─────────────────────────────────────────────────────────────╮
+│                    🎉 2024 Git Wrapped 🎉                    │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  📊 你的编程年度数据                                          │
+│  ├─ 总提交数: 1,247 次 (+23% vs 2023)                       │
+│  ├─ 活跃天数: 287 天 (78.6% 的日子)                         │
+│  ├─ 最长连击: 45 天 🔥                                       │
+│  └─ 代码贡献: +15,432 / -8,901 行                           │
+│                                                             │
+│  🏆 年度亮点                                                 │
+│  ├─ 最忙月份: 三月 (156 次提交)                             │
+│  ├─ 夜猫子指数: 68% (你更喜欢夜晚编程)                       │
+│  ├─ 最爱语言: TypeScript (42.3%)                            │
+│  └─ 主力项目: git-workflow (312 次提交)                     │
+│                                                             │
+│  🎯 成就解锁                                                 │
+│  ├─ 🔥 连击大师 (连续30天提交)                               │
+│  ├─ 🌙 夜猫子 (凌晨提交超过100次)                            │
+│  ├─ 🚀 效率之王 (单日最多23次提交)                           │
+│  └─ 📝 文档达人 (docs类型提交占15%)                          │
+│                                                             │
+╰─────────────────────────────────────────────────────────────╯
+```
+
+### 分享版本 (图片)
+- **卡片式设计**: 类似Instagram Story的竖版布局
+- **渐变背景**: 根据主要编程语言生成配色
+- **图表可视化**: 饼图、柱状图、热力图等
+- **个人头像**: 集成GitHub头像
+- **二维码**: 链接到个人GitHub或项目
+
+## 🛠️ 技术实现
+
+### 数据收集
+```typescript
+interface GitWrappedData {
+  year: number;
+  totalCommits: number;
+  activeDays: number;
+  longestStreak: number;
+  linesAdded: number;
+  linesDeleted: number;
+  languages: LanguageStats[];
+  repositories: RepoStats[];
+  timePatterns: TimePattern;
+  commitTypes: CommitTypeStats;
+  achievements: Achievement[];
+}
+```
+
+### 分析算法
+1. **Git日志解析**: 使用`git log`命令获取提交历史
+2. **语言检测**: 分析文件扩展名和Git属性
+3. **时间模式**: 统计提交时间分布
+4. **趋势分析**: 计算月度、季度变化
+5. **成就系统**: 基于规则检测特殊成就
+
+### 图片生成
+- **Canvas API**: 使用Node.js的canvas库
+- **SVG生成**: 矢量图形支持
+- **模板系统**: 可配置的设计模板
+- **字体支持**: 中英文字体兼容
+
+## 🎨 主题风格
+
+### 预设主题
+1. **GitHub风格**: 绿色系，类似GitHub贡献图
+2. **暗黑模式**: 深色背景，霓虹色彩
+3. **彩虹主题**: 渐变色彩，活泼风格
+4. **极简风格**: 黑白灰，简洁设计
+5. **节日主题**: 根据生成时间的节日风格
+
+### 自定义选项
+```bash
+gw wrapped --theme custom \
+  --bg-color "#1a1a1a" \
+  --accent-color "#00ff88" \
+  --font-family "JetBrains Mono"
+```
+
+## 📱 分享功能
+
+### 社交媒体优化
+- **Twitter**: 1200x675 横版卡片
+- **Instagram**: 1080x1920 竖版故事
+- **LinkedIn**: 1200x627 专业风格
+- **微信朋友圈**: 正方形 1080x1080
+
+### 导出格式
+- **PNG**: 高质量位图，适合分享
+- **SVG**: 矢量图形，可编辑
+- **PDF**: 打印友好格式
+- **HTML**: 交互式网页版本
+
+## 🔮 未来扩展
+
+### v1.0 增强功能
+- [ ] **AI洞察**: 使用AI分析编程模式并给出建议
+- [ ] **团队对比**: 与团队成员的数据对比
+- [ ] **目标设定**: 基于今年数据设定明年目标
+- [ ] **历史对比**: 多年数据的趋势分析
+
+### v2.0 高级功能
+- [ ] **Web仪表板**: 在线查看和分享
+- [ ] **实时更新**: 年度数据的实时追踪
+- [ ] **集成API**: 与其他平台的数据整合
+- [ ] **团队版本**: 企业级团队分析
+
+## 💡 使用场景
+
+### 个人用途
+- **年终总结**: 个人技术成长回顾
+- **简历亮点**: 展示编程活跃度
+- **社交分享**: 在社交媒体展示成就
+- **自我激励**: 通过数据可视化保持动力
+
+### 团队用途
+- **团队回顾**: 团队年度技术总结
+- **绩效展示**: 可视化团队贡献
+- **文化建设**: 增强团队凝聚力
+- **招聘宣传**: 展示团队技术实力
+
+## 🎯 成功指标
+
+- **用户参与度**: 生成报告的用户数量
+- **分享率**: 用户分享图片的比例
+- **回访率**: 用户重复使用的频率
+- **社交影响**: 在社交媒体的传播效果
+
+---
+
+*这个功能将让Git Workflow不仅仅是一个工具，更是一个让开发者为自己的编程旅程感到骄傲的平台。*