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.

npm install -g gitloom-diff # Basic usage gitloom-diff # Compare branches gitloom-diff -s feature/awesome -e main

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

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

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

# 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);

# 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

# 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

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

# 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

const GitLoomDiff = require('gitloom-diff'); const differ = new GitLoomDiff({ outputDir: 'custom-dir', exclusions: ['*.log'], darkMode: false, mode: 'pr' }); await differ.run('main', 'feature/branch');

// 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); }

• 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

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

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

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

MIT

Built with:

• commander
• ora