gbm-cli

v1.0.1

Published

a month ago

Git 分支管理工具 - 交互式查看和清理过期分支

Downloads

0High
0Medium
0Low

liurenkui

git branch cli cleanup fzf 分支管理

🌿 gbm-cli - Git 分支管理工具

一个交互式 Git 分支管理命令行工具，帮助你查看、筛选和清理过期分支。

🎯 解决痛点

你是否遇到过这些问题？

🤯 分支越来越多 - 项目跑了几年，远程分支几十上百个，不知道哪些还有用
❓ 不敢删分支 - 不知道这个分支是否已合并，删除会不会丢失代码
🕐 清理耗时长 - 手动一个个查分支信息、判断是否过期，费时费力
🙋 不知道找谁 - 看到奇怪的分支，不知道是谁创建的，想问都不知道问谁
📊 缺乏全局视图 - 想看未合并分支的统计，按人分组，手动统计太麻烦
🔄 接手项目懵逼 - 新接手一个项目，面对一堆分支不知道从何下手
🧹 季度清理痛苦 - 定期清理过期分支，每次都是重复劳动

gbm-cli 如何解决？

| 痛点 | gbm-cli 方案 | |------|-------------| | 分支太多看不清 | 📋 表格展示所有分支，包含创建时间、创建人、合并状态 | | 不敢删除 | ✅ 明确标识已合并/未合并，未合并分支删除前警告 | | 手动筛选慢 | 🔍 一键筛选过期分支（1年/2年/自定义） | | 不知道找谁 | 👤 按创建人分组统计，快速定位负责人 | | 缺乏全局视图 | 📊 自动统计已合并/未合并数量，按人分组 | | 接手项目懵逼 | 🎯 交互式菜单引导，fzf 预览面板显示详情 | | 季度清理痛苦 | ⚡ 交互式多选，批量删除，30秒搞定 |

典型场景

场景 1：季度清理

# 以前：手动 git branch -a | grep ... 一个个查
# 现在：
$ gbm-cli old     # 筛选过期分支
$ gbm-cli delete  # 交互式批量删除
# 30秒搞定，以前需要30分钟

场景 2：接手新项目

# 以前：git log 翻历史，问同事
# 现在：
$ gbm-cli list      # 看所有分支
$ gbm-cli unmerged  # 重点看未合并的，按人分组
# 5分钟了解全局

✨ 功能特性

📋 查看所有远程分支 - 以表格形式展示分支名、创建日期、创建人、合并状态
🔍 按时间筛选 - 快速找出过期分支（1年以上、2年以上、自定义时间段）
📊 查看未合并分支 - 按创建人分组统计，快速定位未合并的代码
🗑️ 交互式删除 - 基于 fzf 的多选界面，支持预览分支详情
📈 预览面板 - 实时显示分支的最后提交、提交数量、与主分支的差距
🌐 自动检测主分支 - 自动识别 main/master/release 等主分支

📦 安装

npm install -g gbm-cli

🗑️ 卸载

npm uninstall -g gbm-cli

🔧 依赖

git - 版本控制系统（必需）
fzf - 模糊查找工具（必需）

安装 fzf：

# macOS
brew install fzf

# Ubuntu/Debian
sudo apt install fzf

# Windows (Scoop)
scoop install fzf

# 其他
# https://github.com/junegunn/fzf#installation

🚀 使用方法

交互式菜单

不带参数运行，进入交互式菜单：

$ gbm-cli

  ╔══════════════════════════════════╗
  ║       🌿 Git 分支管理工具        ║
  ╠══════════════════════════════════╣
  ║                              ║
  ║  1. 查看所有远程分支          ║
  ║  2. 按时间筛选过期分支        ║
  ║  3. 查看未合并分支            ║
  ║  4. 删除分支                 ║
  ║  5. 退出                     ║
  ║                              ║
  ╚══════════════════════════════════╝

  主分支: release  |  当前日期: 2026-07-16

  请选择 [1-5]:

子命令

直接使用子命令快速操作：

# 查看所有远程分支
gbm-cli list

# 按时间筛选过期分支
gbm-cli old

# 查看未合并分支
gbm-cli unmerged

# 删除分支
gbm-cli delete

帮助和版本

# 显示帮助信息
$ gbm-cli --help

  🌿 gbm-cli - Git 分支管理工具 v1.0.1

  用法:
    gbm-cli [命令]

  命令:
    list      查看所有远程分支
    old       按时间筛选过期分支
    unmerged  查看未合并分支
    delete    删除分支（本地/远程）
    --help    显示帮助信息
    --version 显示版本号

# 显示版本号
$ gbm-cli --version
gbm-cli v1.0.1

📖 详细示例

示例 1：查看所有远程分支

$ gbm-cli list

  所有远程分支（共 88 个）

   # | 分支名                              | 创建日期   | 创建人       | 合并状态
  ---|-------------------------------------|------------|--------------|----------
    1 | dev-ls-lrk-satokenjwt              | 2024-08-09 | lrk          | ❌ 未合并
    2 | master                             | 2024-08-26 | wangzihao    | ❌ 未合并
    3 | prevent-crawlers                   | 2024-12-02 | lrk          | ✅ 已合并
    4 | hotfix-1206                        | 2024-12-06 | lrk          | ✅ 已合并
    5 | toC18-lrk                          | 2024-12-17 | lrk          | ✅ 已合并
    6 | yuan/acc-stop                      | 2024-12-19 | wangzihao    | ✅ 已合并
    7 | small_program                      | 2024-12-19 | 17310618545  | ✅ 已合并
  ...

  汇总: 共 88 个分支 | 已合并: 72 | 未合并: 16 | 最早: 2024-08-09

示例 2：筛选过期分支

$ gbm-cli old

  请输入年限（分支创建时间超过多少年视为过期）
  直接回车默认 1 年

  年限: 1

  筛选创建超过 1 年的分支（共 23 个，截止日期: 2025-07-16）

   # | 分支名                              | 创建日期   | 创建人       | 合并状态
  ---|-------------------------------------|------------|--------------|----------
    1 | dev-ls-lrk-satokenjwt              | 2024-08-09 | lrk          | ❌ 未合并
    2 | master                             | 2024-08-26 | wangzihao    | ❌ 未合并
    3 | feature/old-auth                   | 2024-03-15 | zhangsan     | ✅ 已合并
  ...

示例 3：查看未合并分支

$ gbm-cli unmerged

  未合并到 release 的分支（共 16 个）

   # | 分支名                              | 创建日期   | 创建人       | 合并状态
  ---|-------------------------------------|------------|--------------|----------
    1 | dev-ls-lrk-satokenjwt              | 2024-08-09 | lrk          | ❌ 未合并
    2 | master                             | 2024-08-26 | wangzihao    | ❌ 未合并
    3 | czh/接入dubbo                       | 2025-02-18 | lrk          | ❌ 未合并
  ...

  按创建人分组统计:
      lrk                     8 个
      wangzihao               4 个
      xiongle                 2 个
      17310618545             2 个

示例 4：删除本地分支（完整流程）

$ gbm-cli delete

  请选择删除类型:

    1) 删除本地分支
    2) 删除远程分支
    0) 返回主菜单

  请选择 [0-2]: 1

  📅 请选择时间范围过滤

    1) 所有分支
    2) 1年以上
    3) 2年以上
    4) 自定义时间段
    0) 返回

  请选择 [0-4]: 2

  ┌ 分支列表 ──────────────────────────────────────────────────────┐
  │ TAB多选 | 空格切换 | 回车确认 | q返回 | 共45个（已合并:38）    │
  │                                                                │
  │ > feature/login    | 2024-01-15 | 张三 | ✅ 已合并             │
  │   feature/payment  | 2024-03-20 | 李四 | ❌ 未合并             │
  │   hotfix/bug-123   | 2025-06-01 | 王五 | ✅ 已合并             │
  │   old/test-branch  | 2023-05-10 | 赵六 | ✅ 已合并             │
  └────────────────────────────────────────────────────────────────┘

  # 按 TAB 选择要删除的分支，按回车确认

  即将删除以下 3 个本地分支:

    feature/login
    hotfix/bug-123
    old/test-branch

  确认删除？ [y/N]: y

  ✅ 已删除: feature/login
  ✅ 已删除: hotfix/bug-123
  ✅ 已删除: old/test-branch

  结果: 成功 3 个

示例 5：删除远程分支

$ gbm-cli delete

  请选择删除类型:

    1) 删除本地分支
    2) 删除远程分支
    0) 返回主菜单

  请选择 [0-2]: 2

  即将删除以下 2 个远程分支:

    origin/feature/login
    origin/hotfix/bug-123

  将执行: git push origin --delete <branch>

  确认删除？ [y/N]: y

  ✅ 已删除: origin/feature/login
  ✅ 已删除: origin/hotfix/bug-123

  结果: 成功 2 个

示例 6：指定主分支

# 临时指定主分支
$ GBM_MAIN_BRANCH=develop gbm-cli list

# 永久设置（添加到 ~/.bashrc 或 ~/.zshrc）
$ export GBM_MAIN_BRANCH=develop
$ gbm-cli list

🔧 常见使用场景

场景 1：季度分支清理

每季度末清理过期分支，保持仓库整洁：

# 1. 查看超过 1 年的过期分支
$ gbm-cli old
# 输入: 1

# 2. 删除已合并的过期本地分支
$ gbm-cli delete
# 选择 1 (本地) → 选择 2 (1年以上) → 选择已合并的分支 → 确认删除

# 3. 删除已合并的过期远程分支
$ gbm-cli delete
# 选择 2 (远程) → 选择 2 (1年以上) → 选择已合并的分支 → 确认删除

场景 2：项目接手时了解分支状况

新接手一个项目，快速了解分支状况：

# 1. 查看所有分支概览
$ gbm-cli list

# 2. 重点看未合并的分支（可能有未完成的工作）
$ gbm-cli unmerged

# 3. 查看每个未合并分支的详情（fzf 预览面板）
# 在 fzf 界面中按方向键浏览，右侧显示每个分支的最后提交和详情

场景 3：清理自己的旧分支

清理自己创建的旧分支：

# 1. 查看未合并分支，按创建人分组找到自己的
$ gbm-cli unmerged
# 输出中会按创建人统计，找到自己的名字

# 2. 使用 fzf 过滤自己的分支
$ gbm-cli delete
# 在 fzf 界面中输入自己的名字进行过滤
# 选择要删除的分支 → 确认删除

⚠️ 错误处理

不在 Git 仓库中运行

$ gbm-cli list

  ❌ 当前目录不是 Git 仓库
  当前目录: /home/user

  💡 当前目录及其父目录中未找到 Git 仓库

  你可以:
     1. cd 到你的项目目录（包含 .git 的目录）
     2. 如果是新项目，运行 git init 初始化

如果附近有 Git 仓库

$ gbm-cli list

  ❌ 当前目录不是 Git 仓库
  当前目录: /home/user/projects/myapp/src

  💡 发现附近的 Git 仓库:
     /home/user/projects/myapp

  建议操作:
     cd /home/user/projects/myapp
     gbm-cli list

未安装 fzf

$ gbm-cli list

  ❌ 错误: 需要安装 fzf

  gbm-cli 使用 fzf 提供交互式分支选择功能。

  安装方法:
    macOS:     brew install fzf
    Ubuntu:    sudo apt install fzf
    Windows:   scoop install fzf
    通用:      https://github.com/junegunn/fzf#installation

  安装完成后重新运行 gbm-cli 即可。

⚙️ 配置

通过环境变量配置：

# 指定主分支名称
GBM_MAIN_BRANCH=main gbm-cli list

# 也可以导出环境变量
export GBM_MAIN_BRANCH=develop
gbm-cli list

主分支检测优先级：

环境变量 GBM_MAIN_BRANCH
自动检测（origin/HEAD）
常见名称推断（main → master → release → develop）
默认值 main

📸 预览

fzf 交互式选择

使用 TAB 多选、空格切换、回车确认：

TAB多选 | 空格切换 | 回车确认 | q返回 | 共25个（已合并:18）

> feature/login    | 2024-01-15 | 张三 | ✅ 已合并
  feature/payment  | 2024-03-20 | 李四 | ❌ 未合并
  hotfix/bug-123   | 2025-06-01 | 王五 | ✅ 已合并

预览面板

右侧实时显示分支详情：

┌─ 分支信息 ─────────────────┐
│ feature/login              │
│                            │
│ 创建人: 张三               │
│ 创建日期: 2024-01-15       │
│ 合并状态: ✅ 已合并        │
│ ─────────────────────────  │
│ 最后提交: 2024-01-15       │
│ 提交信息: feat: add login  │
│ 提交数量: 12 个            │
│ 与主分支: 已合并 (3↑ 0↓)   │
└─────────────────────────────┘

📝 删除分支

删除本地分支

gbm-cli delete
# 选择 1 - 删除本地分支

自动排除当前分支
未合并分支会显示警告
已合并分支使用 git branch -d 安全删除
未合并分支使用 git branch -D 强制删除

删除远程分支

gbm-cli delete
# 选择 2 - 删除远程分支

自动排除主分支（main/master/release）
执行 git push origin --delete <branch>
删除前需要确认

⚠️ 注意事项

请在 Git 仓库目录中运行 - 工具需要在 Git 仓库内使用
删除操作不可逆 - 远程分支删除后无法恢复，请谨慎操作
未合并分支 - 删除前请确认代码已合并或不再需要

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

Apache-2.0