# git-branch-diff

**Repository Path**: ycyplus163/git-branch-diff

## Basic Information

- **Project Name**: git-branch-diff
- **Description**: 代码合并提交后，用来精确比对分支差异
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-07-29
- **Last Updated**: 2025-09-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# git-branch-check-diff-commits

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

## ✨ 核心特性

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

## 🚀 快速开始

### 安装

```bash
# 全局安装
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
```

### 基本使用

```bash
# 对比当前分支与目标分支
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. **功能分支开发完成后**
```bash
# 检查是否可以合并到主分支
gbd main
```

### 2. **自动化发布流程后**
```bash
# 检查发布流程是否成功
gbd feature/user-login
```

### 3. **代码同步检查**
```bash
# 检查本地分支是否落后
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
```json
{
  "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 集成
```yaml
# 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 使用

```javascript
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); // 是否检测到自动化流程
```

### 返回数据结构
```typescript
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` 发布流程
- 显示具体的合并链路和提交哈希
- 区分自动化合并和手动操作
- 支持复杂的分支合并模式检测

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

## 🔍 高级功能

### 详细模式
```bash
gbd main --verbose
```
显示额外的调试信息：
- 提交数量统计
- 文件差异详情
- 合并基础点信息
- Git 命令执行状态

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

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

## 🔧 常见使用模式

```bash
# 开发流程检查
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: 提示 "分支不存在" 但分支确实存在**
```bash
# 先手动fetch然后重试
git fetch --all
gbd target-branch
```

**Q: 网络问题导致检查失败**
```bash
# 使用 --no-fetch 跳过网络操作
gbd main --no-fetch
```

**Q: 输出显示与实际不符**
```bash
# 使用详细模式查看调试信息
gbd main --verbose
```

**Q: 无法确定代码状态**
```bash
# 检查Git仓库状态
git status
git log --oneline --graph -10
```

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

### 开发设置
```bash
git clone https://github.com/your-repo/git-branch-check-diff-commits
cd git-branch-check-diff-commits
npm install
npm run dev
```

### 测试
```bash
npm test
npm run test:integration
```

## 📄 License

MIT

---

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