git-branch-check-diff-commits

🚀 智能 Git 分支对比分析工具 - 提供清晰的可视化输出、自动化流程检测和精准的代码差异分析。

✨ 核心特性

• 🎯 智能代码状态分析 - 准确识别代码差异状态（高亮显示）
• 🌊 自动化流程检测 - 自动识别 feature → dev → main 发布流程
• 📊 真实差异计算 - 排除合并提交，只关注实际功能代码差异
• 🔀 合并历史追溯 - 显示具体的合并链路和操作历史
• 🎨 精美可视化输出 - 彩色图标和清晰的层级结构
• 💡 智能操作建议 - 基于分析结果提供精准的下一步操作

🚀 快速开始

安装

# 全局安装
npm install -g git-branch-check-diff-commits
# 或
bun add -g git-branch-check-diff-commits

# 项目内安装
npm install -D git-branch-check-diff-commits
# 或
bun add -D git-branch-check-diff-commits

基本使用

# 对比当前分支与目标分支
gbd main
gbd develop  
gbd origin/feature/user-auth

# 完整命令
git-branch-check-diff-commits main

# 选项
gbd main --json        # JSON格式输出
gbd main --no-fetch    # 跳过自动fetch
gbd main --verbose     # 显示详细调试信息

📋 使用场景

1. 功能分支开发完成后

# 检查是否可以合并到主分支
gbd main

2. 自动化发布流程后

# 检查发布流程是否成功
gbd feature/user-login

3. 代码同步检查

# 检查本地分支是否落后
gbd origin/develop

🎨 输出示例

场景1：有新代码需要推送

╭─ 🔍 Git 分支智能对比分析 ─╮
├─ 🧹 工作区状态
✅ 工作区干净，可以安全进行分支操作

├─ 🌿 分支信息
  │ 当前分支: feature/awesome
  │ 最新提交: abc1234 Add awesome feature (2 hours ago)
  ├──────────────────────────────────────────────────
  │ 对比分支: main
  │ 最新提交: def5678 Update docs (1 day ago)

├─ 📊 代码状态
 ⚠️  有新代码未同步 - 领先 3 个提交 
  │ 实际功能提交: 3 个
  │ 变更文件: 8 个

├─ 📄 详细代码差异
  │ 当前分支的新功能: 3 个提交
  │ 有文件变更差异
  │ 共同基础: def5678

├─ 🎯 智能建议
ℹ️ 推送新代码到远程
  │ git push origin feature/awesome
  │ 或者创建合并请求/PR
╰────────────────────────────────────────────────────╯

场景2：自动化流程检测

╭─ 🔍 Git 分支智能对比分析 ─╮
├─ 🧹 工作区状态
✅ 工作区干净，可以安全进行分支操作

├─ 🌊 自动化流程分析
🔀 检测到可能的自动化发布流程
  │ 1️⃣ feature/user-login → dev (f8299de)
  │ 2️⃣ dev → main (d7fdf79)

├─ 🌿 分支信息
  │ 当前分支: main
  │ 最新提交: d7fdf79 Merge pull request #12 from dev (2 minutes ago)
  ├──────────────────────────────────────────────────
  │ 对比分支: dev
  │ 最新提交: abc1234 chore(robot-admin-env-manager): version update (5 minutes ago)

├─ 📊 代码状态
 🎯 代码基本一致 - 主要是合并提交差异 
  │ 合并相关提交: 2 个

├─ 🎯 智能建议
✅ 代码内容一致 - 只是提交历史不同
  │ 可以选择性推送或保持现状
╰────────────────────────────────────────────────────╯

场景3：代码完全一致

╭─ 🔍 Git 分支智能对比分析 ─╮
├─ 🧹 工作区状态
✅ 工作区干净，可以安全进行分支操作

├─ 🌿 分支信息
  │ 当前分支: main
  │ 最新提交: d7fdf79 Latest updates (1 hour ago)
  ├──────────────────────────────────────────────────
  │ 对比分支: develop
  │ 最新提交: d7fdf79 Latest updates (1 hour ago)

├─ 📊 代码状态
 🎯 代码完全一致 

├─ 🎯 智能建议
✅ 无需操作 - 代码完全同步
╰────────────────────────────────────────────────────╯

场景4：代码分叉需要合并

╭─ 🔍 Git 分支智能对比分析 ─╮
├─ 🧹 工作区状态
⚠️ 有 2 个文件待处理
  │ 修改 src/index.js
  │ 新增 README.md

├─ 🌿 分支信息
  │ 当前分支: feature/conflict
  │ 最新提交: abc1234 Add conflicting changes (1 hour ago)
  ├──────────────────────────────────────────────────
  │ 对比分支: main
  │ 最新提交: def5678 Update same files (2 hours ago)

├─ 📊 代码状态
🔀 代码有分歧 - 领先 2 个，落后 3 个提交
  │ 实际代码差异: 领先 2 个，落后 3 个功能提交
  │ 文件冲突风险: 5 个文件有差异

├─ 📄 详细代码差异
  │ 目标分支的新功能: 3 个提交
  │ 当前分支的新功能: 2 个提交
  │ 有文件变更差异
  │ 共同基础: xyz9876

├─ 🎯 智能建议
⚠️ 需要合并分支
  │ ⚠️ 文件冲突风险较高，建议:
  │ 1. 先备份当前工作
  │ 2. git merge main # 合并并解决冲突
  │ 3. 或使用: git rebase main # 变基方式
╰────────────────────────────────────────────────────╯

🔧 项目集成

package.json scripts

{
  "scripts": {
    "check-main": "gbd main",
    "check-dev": "gbd develop", 
    "check-branch": "gbd",
    "sync-status": "gbd origin/main --json",
    "check-verbose": "gbd main --verbose"
  }
}

CI/CD 集成

# GitHub Actions 示例
- name: 检查分支状态
  run: |
    npm install -g git-branch-check-diff-commits
    gbd main --json > branch-status.json
    
- name: 分析结果
  run: |
    RELATION_TYPE=$(gbd main --json | jq -r '.relationship.type')
    HAS_REAL_DIFF=$(gbd main --json | jq -r '.realCodeDiff.realDiff')
    
    if [ "$RELATION_TYPE" = "ahead" ] && [ "$HAS_REAL_DIFF" = "true" ]; then
      echo "分支有新代码，可以合并"
    elif [ "$RELATION_TYPE" = "synchronized" ]; then
      echo "代码已同步"
    else
      echo "需要检查分支状态: $RELATION_TYPE"
    fi

📚 API 使用

import { analyzeBranches } from "git-branch-check-diff-commits";

// 基本分析
const result = await analyzeBranches("main");

// 带选项的分析
const result = await analyzeBranches("develop", { 
  json: true,
  noFetch: false,
  verbose: true
});

// 获取分析结果
console.log(result.relationship.type);    // "ahead" | "behind" | "synchronized" | "diverged"
console.log(result.realCodeDiff.realDiff); // true/false - 是否有真实代码差异
console.log(result.realCodeDiff.aheadCommits); // 领先的功能提交数
console.log(result.realCodeDiff.fileDiffCount); // 变更文件数量
console.log(result.mergeHistory.hasAutomatedFlow); // 是否检测到自动化流程

返回数据结构

interface AnalysisResult {
  currentBranch: string;
  targetBranch: string;
  relationship: {
    type: "synchronized" | "ahead" | "behind" | "diverged";
    confidence: "high" | "medium" | "low";
  };
  realCodeDiff: {
    realDiff: boolean;
    behindCommits: number;
    aheadCommits: number;
    hasFileDiff: boolean;
    fileDiffCount: number;
    mergeBase: string;
  };
  mergeHistory: {
    hasAutomatedFlow: boolean;
    flowDescription: string | null;
    flowChain: Array<{
      step: number;
      from: string;
      to: string;
      hash: string;
      message: string;
    }>;
  };
  workingDirectory: {
    isClean: boolean;
    changedFiles: Array<{file: string, status: string}>;
  };
  basicStats: {
    ahead: number;
    behind: number;
  };
}

🎯 智能分析功能

代码状态识别（修复版）

• 🎯 代码完全一致 - 分支指向同一提交
• 🎯 代码基本一致 - 主要是合并提交差异 - 代码内容相同，只是提交历史不同
• ⚠️ 有新代码未同步 - 存在真实的功能差异，需要推送
• ⚠️ 代码落后 - 需要同步功能提交
• 🔀 代码有分歧 - 两个分支都有对方没有的提交

自动化流程检测

• 自动识别 feature → dev → main 发布流程
• 显示具体的合并链路和提交哈希
• 区分自动化合并和手动操作
• 支持复杂的分支合并模式检测

智能建议系统

• 基于真实代码差异提供精准建议
• 区分"需要推送"、"需要合并"和"无需操作"
• 自动识别高风险操作并提供安全建议
• 支持远程分支和本地分支的不同处理策略

🔍 高级功能

详细模式

gbd main --verbose

显示额外的调试信息：

• 提交数量统计
• 文件差异详情
• 合并基础点信息
• Git 命令执行状态

错误处理和边界情况

• 网络错误: 自动降级到本地分支检查
• 分支不存在: 清晰的错误提示和建议
• 权限问题: 友好的错误信息
• 空仓库: 适当的处理和提示

安全特性

• 高风险操作预警（如直接推送到主分支）
• 文件冲突风险评估
• 工作区状态检查
• 操作建议的安全等级划分

🔧 常见使用模式

# 开发流程检查
gbd main              # 检查是否可以合并到主分支
gbd develop           # 检查开发分支状态
gbd main --verbose    # 详细模式检查

# 发布后验证  
gbd feature/xxx       # 验证功能分支状态
gbd origin/main       # 检查与远程主分支的关系

# 同步状态检查
gbd origin/main       # 检查远程主分支状态
gbd upstream/develop  # 检查上游开发分支

# 批量检查（结合其他工具）
git branch | grep feature | xargs -I {} gbd {}

# CI/CD 中使用
gbd main --json --no-fetch  # 适合CI环境的检查

🐛 故障排除

常见问题

Q: 提示 "分支不存在" 但分支确实存在

# 先手动fetch然后重试
git fetch --all
gbd target-branch

Q: 网络问题导致检查失败

# 使用 --no-fetch 跳过网络操作
gbd main --no-fetch

Q: 输出显示与实际不符

# 使用详细模式查看调试信息
gbd main --verbose

Q: 无法确定代码状态

# 检查Git仓库状态
git status
git log --oneline --graph -10

🤝 贡献

欢迎提交 Issue 和 Pull Request！

开发设置

git clone https://github.com/your-repo/git-branch-check-diff-commits
cd git-branch-check-diff-commits
npm install
npm run dev

测试

npm test
npm run test:integration

📄 License

MIT

让分支对比变得简单而智能！ 🚀