🛡️ MergeGuard

Real-time Git merge conflict detection with line-level accuracy.

MergeGuard is a proactive CLI tool that monitors your local workspace and remote repositories. It uses Local AI (Ollama) to analyze potential conflicts in real-time, giving you a risk assessment and resolution strategy before you even run git pull.

🚀 Quick Start

1. Prerequisites

Ensure your environment meets the following requirements:

Requirement	Command to Check	Minimum Version
Node.js	node -v	v20.x.x
Git	git --version	Latest
Ollama	ollama --version	Latest

Prepare the AI Brain:

1. Download Ollama from ollama.com.
2. Run the following in your terminal:

   ollama pull llama3.2

   Note: Ensure Ollama is running in the background.

2. Installation

Clone the repository and link the CLI to your system:

# Clone the repository
git clone https://github.com/ghoshvidip26/MergeGuard
cd MergeGuard

# Install dependencies and build
npm install
npm run build

# Link globally so you can use the 'mergeguard' command anywhere
npm link

Verify Installation:

mergeguard --help

🧪 How to Verify a "High Risk" Conflict

To see MergeGuard’s true power, follow this specific test case:

1. Setup: Run mergeguard -w in your test repo.
2. Action A (Remote): Go to GitHub.com, edit line 10 of README.md, and commit.
3. Action B (Local): Immediately edit line 10 of README.md in your local editor. Do not commit.
4. The Result: MergeGuard will detect you are Behind: 1 and have Local Changes. The AI will flag this as HIGH RISK because the line ranges overlap.

📊 Understanding AI Alerts

Alert Level	Meaning	Suggested Action
NONE	No local or remote changes detected.	Keep coding!
LOW	Remote changes exist, but in different files.	git pull is safe.
MEDIUM	Same file changed, but different lines.	git pull is likely safe (auto-merge).
HIGH	Same lines changed on both sides.	Stop. Coordinate before pulling.

✨ Key Features

• 🔍 Real-time Git monitoring (local + remote)
• 📄 Line-level diff analysis (no coarse file-only checks)
• 🌿 Branch-agnostic (works with any feature branch)
• 🚨 Conflict risk classification:
  • 🔴 RISK=HIGH – Same file AND overlapping line ranges.
  • 🟡 RISK=MEDIUM – Same file, but different line ranges.
  • 🟢 RISK=LOW – Different files entirely.
  • ⚪ RISK=NONE – No changes or branch is up-to-date.
• 🤖 AI-assisted analysis (via Ollama) with strict factual guardrails
• 🔌 CLI + Socket.IO for live alerts
• ⚡ Smart caching to avoid unnecessary recomputation

▶️ Usage

Watch mode (recommended)

Navigate to any active Git repository and run:

mergeguard -w

• Watches the repository continuously.
• Emits alerts on local changes, remote updates, and conflict risks.

One-time analysis

mergeguard -a

Or with a custom prompt:

mergeguard -a "Analyze repository safety"

🧠 How It Works

1. Repository Watcher: Tracks uncommitted local changes and periodically fetches remote updates.
2. Data Collection: Uses git status, git diff, and git log to collect ground-truth data.
3. Line-level analysis: Extracts exact line ranges from diff hunks to match local vs remote changes per file.
4. AI Analysis: Consumes tool output to explain why a conflict may occur and recommends resolution strategies.

📊 Sample Output

MergeGuard provides a clean, fact-based report based on actual Git hunks and AI analysis: Example-1:

🚩 ALERT: LOW (Behind: 0, Ahead: 0)

📍 File Change Details
- src/index.ts
  - Change Type: Local
  - Status: M
  - File Creation Status: Modified
  - Exact Line Numbers: Lines 249–277, Lines 328–328, ...

🧠 Analysis
Found 3 uncommitted files...

Example-2:

🚩 ALERT: HIGH (Behind: 1, Ahead: 0)

📍 File Change Details
- README.md
  - Change Type: Remote | Conflict
  - Exact Line Numbers: Lines 6–64, Lines 66–66
  - File Creation Status: Modified

🧠 Analysis
The analysis indicates that there is a HIGH RISK due to overlapping line ranges in the same file. The remote changes have been detected and are causing this risk.

⚔️ Conflict Resolution Strategy
To resolve this conflict, you can choose one of the following strategies:
- Accept Remote: Run 'git pull' and manually resolve conflict markers in affected files.
- Keep Local: During a merge conflict, run 'git checkout --ours <file>' and add the file. Complete the merge with 'git commit'.
- Manual Merge: Run 'git pull' and manually resolve conflict markers in affected files.

Please note that you should coordinate before pulling to avoid any potential issues.

🔥 Remote vs Local Conflict Detection (Line-Level)

MergeGuard doesn’t just tell you that you’re behind or ahead —
it shows exactly which lines changed on remote vs your local branch.

In this example:

• The remote branch modified README.md at:
  • Lines 103, 106, 111, 113, 118
• The local branch modified the same file at:
  • Lines 249–277 and 328

Because both sides changed the same file, MergeGuard correctly reports: 🚩 RISK = MEDIUM and requires a merge decision.

This prevents blind git pull conflicts before they happen.

🧠 Unified Local + Remote Change Detection

MergeGuard doesn’t just list changed files — it shows exactly which lines were modified locally and on the remote branch in a single unified view.

This allows you to see before pulling whether you are about to hit a merge conflict.

Example

In this example:

• The local branch has uncommitted changes in:

  • src/index.ts
  • tools/gitLocal.ts

• The remote branch has updates in:

  • README.md

🤖 RAG-powered Codebase Q&A

⚙️ Advanced Configuration

To improve remote detection accuracy and avoid GitHub rate limits, add a Personal Access Token:

1. Create a .env file in the MergeGuard root directory.
2. Add your token:

   GITHUB_API=github_pat_your_token_here

3. Restart the watcher.

🌐 GitHub API Integration

The tool uses the GitHub REST API to fetch additional repository metadata (e.g., pull request status, branch protection rules) when a GITHUB_API is provided. This enables more accurate conflict risk assessment and avoids hitting unauthenticated rate limits.

• Set GITHUB_API in your .env as described in the Advanced Configuration section.
• The token must have repo scope for private repositories.
• If no token is set, the tool falls back to unauthenticated API calls with lower rate limits.

🧪 Supported Workflows

• ✅ Feature branch vs remote main
• ✅ Open-source contribution model
• ✅ Local commits ahead of remote
• ✅ Remote commits behind local
• ❌ Does NOT auto-merge or modify files

🛠 Troubleshooting

• Node Version: If you see syntax errors, ensure you are on Node 20+.
• Ollama Connection: If analysis hangs, ensure ollama run llama3.2 works independently.
• Permissions: You may need sudo npm link on some systems.

🛠️ Tech Stack

• TypeScript & Node.js
• simple-git for Git operations
• Socket.IO for live updates
• LangChain & Ollama for AI analysis
• Yargs for CLI management

🧑‍💻 Who This Is For

• Backend / Platform engineers
• Open-source contributors
• Teams with frequent rebases
• Developers tired of surprise merge conflicts