https://github.com/bayuagpr/gitloom-diff
Generate beautiful, searchable, IDE-friendly git diffs in markdown format
https://github.com/bayuagpr/gitloom-diff
changelog code-review developer-tools documentation git gitdiff markdown merge-request pull-request
Last synced: 3 months ago
JSON representation
Generate beautiful, searchable, IDE-friendly git diffs in markdown format
- Host: GitHub
- URL: https://github.com/bayuagpr/gitloom-diff
- Owner: bayuagpr
- Created: 2024-11-12T04:57:31.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2024-11-15T09:58:22.000Z (about 1 year ago)
- Last Synced: 2025-10-12T16:04:57.072Z (3 months ago)
- Topics: changelog, code-review, developer-tools, documentation, git, gitdiff, markdown, merge-request, pull-request
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/gitloom-diff
- Size: 2.09 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# GitLoom Diff
[](https://www.npmjs.com/package/gitloom-diff)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)
**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
```bash
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
```markdown
# 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
```bash
# 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:
```json
{
"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:
```bash
# 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
```bash
# 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
```bash
Options:
-s, --start-ref Starting reference (newer state)
-e, --end-ref Ending reference (older state)
-o, --output Output directory (default: "git-diffs")
--exclude Additional file patterns to exclude
-m, --mode Comparison mode: pr|commit|tag (default: "pr")
--light-mode Use light mode theme
-h, --help Display help
```
### Advanced Examples
```bash
# 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
```javascript
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
```javascript
// 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](https://www.npmjs.com/package/commander)
- [ora](https://www.npmjs.com/package/ora)