DiffShow

Turn local Git changes into a polished, self-contained before-and-after HTML report.

npm · GitHub · Report a bug · Request a feature

---

DiffShow is a small CLI for creating portable review artifacts from a Git working tree or from two branches. Run one command inside a repository, open the generated HTML file, and share the result when you need a clean walkthrough, handoff, or review aid.

No server. No account. No telemetry. No AI API. No source-code upload.

Table of Contents

• Why DiffShow
• Features
• Branch Comparison
• Requirements
• Installation
• Usage
• Demo Command Sequence
• Privacy and Security
• Limitations
• Development
• Contributing
• Maintainer
• License

Why DiffShow

Terminal diffs are excellent for day-to-day work, but they are not always ideal for presenting a change to someone else. DiffShow creates a readable report that shows what changed, where it changed, and how the before-and-after code compares.

Use it when you want to:

• Review local changes before committing
• Walk through a feature or refactor
• Share a self-contained HTML report
• Compare work between two branches
• Keep review output local and easy to inspect

Features

• Generates a standalone HTML report from Git changes
• Shows changed-file navigation, statuses, and line totals
• Displays changed hunks with before and after line numbers
• Includes a collapsible unified patch
• Handles binary-file metadata
• Supports responsive layouts
• Includes accessible controls
• Supports light and dark color schemes
• Reminds users to review sensitive code before sharing

Branch Comparison

DiffShow can also compare two branches and generate a report from that difference.

Requirements

• Node.js 20 or newer
• Git available on PATH
• A Git working tree

Installation

Install Globally

If you plan to use DiffShow regularly, install it globally:

npm install -g diffshow

Then run it from any Git repository:

diffshow

Update the global installation:

npm update -g diffshow

Uninstall it:

npm uninstall -g diffshow

One-Time Usage

To run DiffShow without keeping a global installation:

npx diffshow

npx downloads DiffShow if necessary and immediately runs the CLI.

Usage

Generate a Report From Local Changes

Run DiffShow inside a Git repository:

diffshow

DiffShow reads the current working tree changes and generates a local HTML report.

Compare Two Branches

Compare a base branch with another branch:

diffshow compare main feature/s7-prompt-registry

Replace main and feature/s7-prompt-registry with the branches you want to compare.

Check the Installed Version

diffshow --version

Show Help

diffshow --help

Demo Command Sequence

This is a short sequence suitable for a terminal demo or product video:

which diffshow
diffshow --version

npm install -g diffshow

diffshow --version

diffshow

diffshow compare main feature/s7-prompt-registry

diffshow --help

Privacy and Security

DiffShow is designed to work locally.

• It does not require an account
• It does not start a hosted review service
• It does not upload source code
• It does not use telemetry
• It does not call an AI API
• It generates a local HTML artifact that you control

Before sharing a generated report, review it for secrets, credentials, internal URLs, proprietary source code, or other sensitive information. The report may include code from your local changes or branch comparison.

Limitations

• DiffShow depends on Git being available in the environment where it runs
• The generated report reflects the diff data available from the local repository
• Large diffs can produce large HTML files
• Binary files are represented by metadata rather than rendered content
• The output is intended as a review artifact, not as a replacement for a full hosted code review system

Development

Clone the repository, install dependencies, and run the CLI locally:

git clone https://github.com/ziyad455/diffshow.git
cd diffshow
npm install
npm run build

Run the local CLI from the repository:

node dist/cli.js

If the project uses a different local script in your checkout, prefer the script defined in package.json.

Contributing

Contributions are welcome.

Good contributions include:

• Bug fixes
• Documentation improvements
• Accessibility improvements
• Better handling for edge-case Git diffs
• UI refinements that keep the report readable and lightweight
• Tests for CLI behavior and generated output

Before opening a pull request:

1. Keep the change focused.
2. Run the available checks.
3. Update documentation when behavior changes.
4. Avoid adding network requirements or hosted-service dependencies.

Maintainer

Created and maintained by Ziyad Tber.

License

This project is licensed under the terms included in the LICENSE file.