@zjex/git-workflow 0.0.1 → 0.0.2

package/README.md

@@ -27,20 +27,22 @@
 
 - 🤔 每次创建分支都要手动输入一长串命名规范？
 - 😫 发布版本时总是忘记当前版本号是多少？
+- 📝 提交信息格式不统一，难以生成 CHANGELOG？
 - 🔄 删除分支时需要分别处理本地和远程？
-- 📝 团队成员的分支命名风格五花八门？
+- 📋 团队成员的分支命名风格五花八门？
 
 **git-workflow** 就是为解决这些痛点而生的。它提供了一套简洁的命令，让你专注于编码，而不是 Git 操作。
 
 ## 特性
 
-- ⚡️ **极速上手** - 零配置开箱即用，一个命令搞定分支创建
+- ⚡️ **极速上手** - 零配置开箱即用，交互式菜单引导操作
 - 🎯 **规范命名** - 自动生成带日期的规范分支名，告别命名混乱
 - 🏷️ **智能版本** - 自动识别当前版本，交互式选择下一版本（支持 semver + 预发布）
+- 📝 **规范提交** - 遵循 Conventional Commits + Gitmoji，提交信息更清晰
 - 🗑️ **批量清理** - 一键删除本地+远程分支，按最近使用排序
 - ⚙️ **灵活配置** - 支持项目级配置文件，不同项目不同规范
 - 🎨 **优雅交互** - 友好的命令行界面，支持键盘快捷操作
-- 📦 **轻量依赖** - 打包体积仅 12KB，安装快速无负担
+- 📦 **轻量依赖** - 打包体积小，安装快速无负担
 
 ## 快速开始
 
@@ -57,15 +59,41 @@ pnpm add -g @zjex/git-workflow
 yarn global add @zjex/git-workflow
 ```
 
+### 初次使用
+
+```bash
+# 1. 初始化配置（可选，使用默认配置可跳过）
+gw init
+
+# 2. 运行交互式菜单
+gw
+
+# 3. 或直接使用命令
+gw f    # 创建 feature 分支
+gw c    # 提交代码
+gw t    # 创建 tag
+```
+
 ### 30 秒上手
 
 ```bash
+# 交互式菜单（推荐新手）
+gw
+# 显示 ZJEX Logo 和操作菜单，选择你要执行的操作
+
+# 或直接使用命令
 # 创建 feature 分支
 gw f
 # ? 请输入 Story ID (可跳过): PROJ-123
 # ? 请输入描述: add-user-login
 # ✔ 分支创建成功: feature/20260107-PROJ-123-add-user-login
 
+# 提交代码
+gw c
+# ? 选择提交类型: ✨ feat 新功能
+# ? 输入简短描述: add user login
+# ✔ 提交成功
+
 # 创建 tag
 gw t
 # ? 选择 tag 前缀: v (最新: v1.2.0)
@@ -82,6 +110,36 @@ gw d
 
 ## 命令详解
 
+### 交互式菜单
+
+直接运行 `gw` 显示交互式菜单，适合新手快速上手：
+
+```bash
+gw
+
+ ███████╗     ██╗███████╗██╗  ██╗
+ ╚══███╔╝     ██║██╔════╝╚██╗██╔╝
+   ███╔╝      ██║█████╗   ╚███╔╝
+  ███╔╝  ██   ██║██╔══╝   ██╔██╗
+ ███████╗╚█████╔╝███████╗██╔╝ ██╗
+ ╚══════╝ ╚════╝ ╚══════╝╚═╝  ╚═╝
+
+  git-workflow v0.0.1
+
+? 选择操作:
+  [1] ✨ 创建 feature 分支      gw f
+  [2] 🐛 创建 hotfix 分支       gw h
+  [3] 🗑️  删除分支               gw d
+  [4] 📝 提交代码               gw c
+  [5] 🏷️  创建 tag               gw t
+  [6] 📋 列出 tags              gw ts
+  [7] 📦 发布版本               gw r
+  [8] 💾 管理 stash             gw s
+  [9] ⚙️  初始化配置             gw init
+  [0] ❓ 帮助
+  [q] 退出
+```
+
 ### 分支命令
 
 | 命令                           | 别名              | 说明              |
@@ -101,6 +159,19 @@ gw f --base develop
 gw fix --base release/1.0
 ```
 
+如果检测到未提交的更改，会询问是否自动暂存 (stash)：
+
+```bash
+gw f
+# 检测到未提交的更改:
+#  M src/index.ts
+# ────────────────────────────────────────
+# ? 是否暂存 (stash) 这些更改后继续?
+#   是
+#   否，取消操作
+# ✔ 更改已暂存，切换分支后可用 gw s 恢复
+```
+
 分支命名格式：
 
 ```
@@ -151,6 +222,18 @@ gw t
 gw t v
 ```
 
+如果仓库没有任何 tag，会引导创建初始版本：
+
+```bash
+gw t
+# 当前仓库没有 tag，请输入前缀 (如 v): v
+# ? 选择初始版本号:
+#   v0.0.1
+#   v0.1.0
+#   v1.0.0
+#   自定义...
+```
+
 支持的版本类型：
 
 | 当前版本        | 可选操作                                                                                                                             |
@@ -239,6 +322,79 @@ gw st
 
 创建 stash 时，如果检测到未跟踪的新文件，会询问是否一并 stash。
 
+### Commit 命令
+
+| 命令        | 别名            | 说明                                        |
+| ----------- | --------------- | ------------------------------------------- |
+| `gw commit` | `gw c`, `gw cm` | 交互式提交 (Conventional Commits + Gitmoji) |
+
+遵循 [Conventional Commits](https://www.conventionalcommits.org/zh-hans/) 规范，并自动添加 [Gitmoji](https://gitmoji.dev/) 表情：
+
+```bash
+gw c
+# 已暂存的文件:
+#   src/index.ts
+#   src/utils.ts
+# ────────────────────────────────────────
+# ? 选择提交类型:
+#   ✨  feat       新功能
+#   🐛  fix        修复 Bug
+#   📝  docs       文档更新
+#   💄  style      代码格式 (不影响功能)
+#   ♻️  refactor   重构 (非新功能/修复)
+#   ⚡️  perf       性能优化
+#   ✅  test       测试相关
+#   📦  build      构建/依赖相关
+#   👷  ci         CI/CD 相关
+#   🔧  chore      其他杂项
+#   ⏪  revert     回退提交
+# ? 输入影响范围 scope (可跳过): auth
+# ? 输入简短描述: add login validation
+# ? 输入详细描述 (可跳过):
+# ? 是否包含破坏性变更 (BREAKING CHANGE)? No
+# ? 关联 Issue (如 #123, 可跳过): #42
+# ────────────────────────────────────────
+# 提交信息预览:
+# ✨ feat(auth): add login validation
+#
+# #42
+# ────────────────────────────────────────
+# ? 确认提交? Yes
+# ✔ 提交成功
+# commit: a1b2c3d
+```
+
+如果没有暂存的更改，根据配置决定行为：
+
+**默认行为（`autoStage: true`）：**
+
+```bash
+gw c
+# 没有暂存的更改
+# ────────────────────────────────────────
+# 未暂存的文件:
+#   M src/index.ts
+#   M src/utils.ts
+# ────────────────────────────────────────
+# ✔ 已自动暂存所有更改
+```
+
+**手动选择文件（`autoStage: false`）：**
+
+```bash
+gw c
+# 没有暂存的更改
+# ────────────────────────────────────────
+# 未暂存的文件:
+#   M src/index.ts
+#   M src/utils.ts
+# ────────────────────────────────────────
+# ? 选择要暂存的文件: (使用空格选择)
+#   ◉ M src/index.ts
+#   ◉ M src/utils.ts
+# ✔ 已暂存 2 个文件
+```
+
 ## 配置文件
 
 在项目根目录创建配置文件，可自定义工具行为。不同项目可以有不同配置，满足多样化需求。
@@ -258,7 +414,9 @@ gw st
   "featureIdLabel": "Story ID",
   "hotfixIdLabel": "Issue ID",
   "defaultTagPrefix": "v",
-  "autoPush": true
+  "autoPush": true,
+  "autoStage": true,
+  "useEmoji": true
 }
 ```
 
@@ -274,6 +432,9 @@ gw st
 | `hotfixIdLabel`    | `string`  | `"Issue ID"` | hotfix 分支 ID 提示文字                    |
 | `defaultTagPrefix` | `string`  | -            | 默认 tag 前缀，设置后跳过选择步骤          |
 | `autoPush`         | `boolean` | -            | 创建分支后是否自动推送，不设置则询问       |
+| `autoStage`        | `boolean` | `true`       | commit 时是否自动暂存所有更改              |
+| `useEmoji`         | `boolean` | `true`       | commit 时是否使用 emoji                    |
+| `commitEmojis`     | `object`  | -            | 自定义各类型 commit 的 emoji               |
 
 ### 常见配置场景
 
@@ -314,6 +475,45 @@ gw st
 
 </details>
 
+<details>
+<summary><b>场景四：禁用 Emoji（适合严格的 CI/CD 环境）</b></summary>
+
+```json
+{
+  "useEmoji": false,
+  "autoStage": false
+}
+```
+
+提交信息格式变为：`feat(scope): description` 而不是 `✨ feat(scope): description`
+
+</details>
+
+<details>
+<summary><b>场景五：自定义 Commit Emoji</b></summary>
+
+```json
+{
+  "commitEmojis": {
+    "feat": "🎉",
+    "fix": "🔧",
+    "docs": "📚",
+    "style": "🎨",
+    "refactor": "🔨",
+    "perf": "🚀",
+    "test": "🧪",
+    "build": "📦",
+    "ci": "👷",
+    "chore": "🔧",
+    "revert": "⏪"
+  }
+}
+```
+
+可以只覆盖部分类型，未配置的使用默认 emoji。
+
+</details>
+
 ## 最佳实践
 
 ### 团队协作
@@ -362,6 +562,22 @@ npm run build
 npm link
 ```
 
+## 发布
+
+```bash
+# 自动化发布（推荐）
+npm run release
+
+# 手动发布
+npm run build
+npm run changelog
+npm version patch  # 或 minor/major
+git push origin main --tags
+npm publish
+```
+
+详见 [发布脚本文档](./scripts/README.md)
+
 ## 贡献
 
 欢迎提交 Issue 和 Pull Request！