GitLoom Diff

Stop squinting at those git provider diff views.
Generate beautiful, searchable, IDE-friendly git diffs in markdown format.

⚠️ Early Stage Project: GitLoom Diff is currently in active development and not yet production-ready. Expect frequent breaking changes and major updates as we evolve the tool. Use with caution in production environments.

Quick Start

npm install -g gitloom-diff

# Basic usage
gitloom-diff 

# Compare branches
gitloom-diff -s feature/awesome -e main

Why You'll Love This

GitHub, GitLab, or any other git provider diffs are often overwhelming - endless scrolling, no search, and hard to navigate between files. This tool generates clean markdown diffs that you can:

• 🚀 Open in Your Favorite IDE/Editor

  • Use your IDE's search & navigation
  • Navigate diffs with familiar codebase structure (follows original file paths)
  • Get proper syntax highlighting
  • Review diffs comfortably

• 🤖 Feed Directly to AI

  • Share diffs directly with any LLM (e.g. ChatGPT, Claude, etc)
  • Review changes with integrated AI in your preferred editor (No more copy-paste hell)
  • Let AI help you:
    • Generate PR summaries instantly
    • Generate commit messages, changelog, or release notes from changes
    • Get code review suggestions and explanations
    • Analyze changes for potential bugs and improvements

• 🧹 Focus on What Matters

  • Auto-skips node_modules, build files, and junk
  • Shows only relevant changes
  • Customize exclusion patterns

• 📤 Share & Reference

  • Share clean diffs with team members and stakeholders
  • Attach as context in tickets and documentation
  • Create permanent snapshots of changes for future reference
  • Use in async discussions and code reviews

Core Features

• 💡 Compare Anything: branches (local or remote), commits, tags
• 📊 Rich Statistics: changes per file, summaries, commit history
• 📝 Markdown Output: readable, searchable, navigable, shareable

Output Structure

📁 git-diffs/
├── 📊 DIFF_INDEX.md     # Overview of all changes
├── src/
│   ├── 📝 api.js.md    # Per-file diffs with syntax highlighting
│   └── components/
│       └── 📝 Button.js.md

Sample Diff Output

# Changes in `src/components/Button.js`

## File Statistics
 src/components/Button.js | 25 +++++++++++++++++--------

## Changes
```diff
- import React from 'react';
+ import React, { useState } from 'react';

 const Button = ({ label }) => {
+  const [isHovered, setIsHovered] = useState(false);

Usage

Installation

# Global installation (accessible everywhere)
npm install -g gitloom-diff

# Local installation (project-specific)
npm install gitloom-diff

When installed locally, you can add it to your package.json scripts for common workflows:

{
  "scripts": {
    "diff:main": "gitloom-diff -s HEAD -e main",
    "diff:staged": "gitloom-diff -s HEAD -e --staged",
    "pr:diff": "gitloom-diff -s $npm_config_branch -e main"
  }
}

Then run:

# Compare current branch with main
npm run diff:main

# Review staged changes
npm run diff:staged

# Compare specific branch with main
npm run pr:diff --branch=feature/awesome

Basic Commands

# Compare branches (PR mode - default)
gitloom-diff -s feature/branch -e main

# Compare tags (use tag mode)
gitloom-diff -s v1.1.0 -e v1.0.0 -m tag

# Compare commits (use commit mode)
gitloom-diff -s abc123 -e def456 -m commit

# Compare with remote
gitloom-diff -s origin/main -e main

# Compare staged changes
gitloom-diff -s HEAD -e --staged

Configuration

Options:
  -s, --start-ref <ref>      Starting reference (newer state)
  -e, --end-ref <ref>        Ending reference (older state)
  -o, --output <dir>         Output directory (default: "git-diffs")
  --exclude <patterns...>    Additional file patterns to exclude
  -m, --mode <mode>         Comparison mode: pr|commit|tag (default: "pr")
  --light-mode              Use light mode theme
  -h, --help                Display help

Advanced Examples

# Tag comparison
gitloom-diff -s v2.0.0 -e v1.0.0 -m tag

# Exclude patterns with commit comparison
gitloom-diff -s abc123 -e def456 -m commit --exclude "*.test.js" "docs/**"

# Multiple options
gitloom-diff \
  -s feature/new-ui \
  -e develop \
  -m pr \
  -o ui-changes \
  --exclude "*.test.js" "*.snap" \
  --light-mode

Programmatic Usage

const GitLoomDiff = require('gitloom-diff');

const differ = new GitLoomDiff({
  outputDir: 'custom-dir',
  exclusions: ['*.log'],
  darkMode: false,
  mode: 'pr'
});

await differ.run('main', 'feature/branch');

Integration Examples

// Code Review Tool Integration
async function generateReviewDiff(prNumber) {
  const differ = new GitLoomDiff({
    outputDir: `pr-${prNumber}-diff`,
    mode: 'pr'
  });
  await differ.run('main', `pr-${prNumber}`);
}

// Git Hook Integration
async function preCommitHook() {
  const differ = new GitLoomDiff({
    mode: 'commit'
  });
  await differ.run('HEAD', '--staged');
}

// Tag Release Comparison
async function compareReleases(oldTag, newTag) {
  const differ = new GitLoomDiff({
    mode: 'tag',
    exclusions: ['*.lock', 'dist/*']
  });
  await differ.run(newTag, oldTag);
}

Auto-Excluded Files

• Package manager locks (package-lock.json, yarn.lock)
• Dependencies (node_modules/, vendor/)
• Build outputs (dist/, build/, .next/)
• IDE and OS files (.idea/, .vscode/, .DS_Store)
• Logs and environment files

Requirements

• Node.js >= 18
• Git installed and accessible

Contributing

1. Fork and clone
2. npm install
3. Create feature branch
4. Make changes
5. Submit PR

Troubleshooting

Common Issues

1. Git Command Fails

   • Ensure you're in a git repo
   • Check git installation
   • Verify git config

2. No Output

   • Verify changes exist
   • Check exclusion patterns
   • Confirm git range

3. Exclusion Issues

   • Use forward slashes
   • Escape wildcards
   • Use dir/** for directories

License

MIT

Acknowledgments

Built with:

• commander
• ora