Skip to content

README.md

Latest commit

 

History

History
226 lines (162 loc) · 6.77 KB

README.md

File metadata and controls

226 lines (162 loc) · 6.77 KB

diffx

A CLI utility for easily diffing Git changes across your working tree, local refs, remote refs, GitHub PRs, GitLab MRs, or any Git URLs.

Quick Start

Install

# npm
npm install -g @jaydenfyi/diffx

# bun
bun add -g @jaydenfyi/diffx

# no install
npx @jaydenfyi/diffx --help

Most useful commands

# 1) Show all current local changes (tracked + untracked)
diffx

# 2) Compare two refs
diffx main..feature

# 3) Diff a GitHub PR
diffx https://github.com/owner/repo/pull/123

# 4) Generate an apply-able patch
diffx main..feature --mode patch

# 5) Quick status view
diffx --name-status

diffx vs git diff

Capability diffx git diff
Full working tree snapshot (tracked + untracked) ✅ ❌
Direct GitHub PR and GitLab MR diffing ✅ ❌
Cross-remote and fork comparisons ✅ ❌
Include/exclude glob filtering ✅ ❌
git diff compatibility ✅ ✅

Command

diffx [range-or-url] [options] [-- <pathspec...>]

Use --index for strict git diff compatibility (index vs worktree behavior).

Input Formats

No range argument (default behavior)

# Uses current worktree first (tracked + untracked)
diffx

# If there are no local changes, falls back to inferred base..HEAD

Local ranges

diffx main..feature
diffx abc123..def456
diffx refs/heads/main..refs/tags/v1.0

Remote shorthand ranges

diffx owner/repo@main..owner/repo@feature
diffx owner/repo@main..feature

Git URL ranges (SSH/HTTPS, any host)

diffx git@github.com:owner/repo.git@main..feature
diffx https://github.com/owner/repo.git@v1.0..v2.0
diffx git@github.com:owner/repo.git@main..git@gitlab.com:owner/fork.git@feature

GitHub refs and URLs

# GitHub ref shorthand
diffx github:owner/repo@main..feature

# PR reference
diffx github:owner/repo#123

# PR URL
diffx https://github.com/owner/repo/pull/123

# PR vs PR
diffx github:owner/repo#123..github:owner/repo#456

# Commit URL
diffx https://github.com/owner/repo/commit/abc123

# PR changes URL
diffx https://github.com/owner/repo/pull/123/changes/abc123..def456

# Compare URL (same repo or cross-fork)
diffx https://github.com/owner/repo/compare/main...feature
diffx https://github.com/owner/repo/compare/main...other-owner:other-repo:feature

GitLab refs

# GitLab shorthand range
diffx gitlab:owner/repo@main..feature

# Merge request ref
diffx gitlab:owner/repo!123

Output Modes

diffx defaults to diff mode.

  • diff: unified diff output.
  • patch: patch output (for git apply style use).
  • stat: per-file histogram + summary line.
  • numstat: tab-delimited additions/deletions per file.
  • shortstat: one summary line only.
  • name-only: changed filenames only.
  • name-status: status + filename (e.g. M, A, D, U).
  • summary: structural summary (create mode, rename, etc.), equivalent to git diff --summary.

Examples:

diffx main..feature --mode patch
diffx https://github.com/owner/repo/pull/123 --stat
diffx --name-status

Filtering

# Include only TypeScript files
diffx main..feature --include "src/**/*.ts"

# Exclude tests
diffx main..feature --exclude "**/*.test.ts"

# Combine include + exclude
diffx main..feature --include "src/**" --exclude "**/*.spec.ts"

# Repeat include/exclude flags (matches any include; excludes any exclude)
diffx --include "*.ts" --include "*.tsx" --exclude "*.js" --exclude "*.jsx"

Pager behavior

  • Diff/patch output auto-pages on TTY (git-like behavior).
  • Honors GIT_PAGER, core.pager, PAGER.
  • Use --pager to force paging.
  • Use --no-pager to disable paging.

Options Reference

Option Short Description
--mode <mode> Select output mode: diff, patch, stat, numstat, shortstat, name-only, name-status, summary
--stat Shortcut for stat output
--numstat Shortcut for numstat output
--summary Structural summary (native git diff --summary)
--shortstat Shortcut for shortstat output
--name-only Show filenames only
--name-status Show status + filename
--include <pattern> -i Include only files matching glob (repeatable)
--exclude <pattern> -e Exclude files matching glob (repeatable)
--pager Force pager
--no-pager Disable pager
--index Strict git diff compatibility mode
--help -h Show help
--version -v Show version

Git Pass-through Compatibility

diffx forwards unknown/standard git diff flags to git when possible, including pathspec support after --.

diffx main..feature -U10 --word-diff

diffx --stat -- src/cli src/utils

This allows existing git diff habits while still using diffx input resolution and workflows.

Exit Codes

Code Meaning
0 Success
1 No files matched filters
2 Invalid input / unsupported range format
3 Git execution/fetch error

Development

This repository uses bun.

bun install
bun run build
bun run test
bun run test:e2e
bun run lint
bun run typecheck

License

MIT