difit Documentation

The difit project uses Vitest for its testing framework. The testing strategy is divided into two main categories:

1. Unit Tests: Run in isolation with all dependencies mocked. They focus on logic and edge cases with fast execution and no side effects.
2. Integration Tests: Mock only external dependencies (like Git or the file system) to test component interactions and actual HTTP communication.

Safety Measures during testing:

• No actual Git operations are performed (they are fully mocked).
• Random ports are used for server tests to avoid conflicts.
• All resources are cleaned up in afterEach.
• No modifications are made to the working directory.

difit is composed of the following architectural components:

• CLI: Argument parsing powered by Commander.js with comprehensive validation.
• Backend: An Express server utilizing simple-git for diff processing.
• GitHub Integration: Uses GitHub CLI (gh pr diff --patch) to retrieve PR patches.
• Frontend: Built with React 18, TypeScript, and Vite.
• Styling: Tailwind CSS v4 with a GitHub-like dark theme.
• Syntax Highlighting: Prism.js with dynamic language loading.
• Testing: Vitest unit tests located alongside source files.
• Quality Control: Uses oxlint, oxfmt, and lefthook pre-commit hooks.

You can add difit skills to your AI agent to allow it to request code reviews or launch difit with preloaded findings.

Run the following command to add the skills:

npx skills add yoshiko-pg/difit

Available Skills:

• difit: Asks the user for a review through difit after code changes.
• difit-review: Reviews a specific diff or PR and launches difit with findings or explanations preloaded as comments.

You can review GitHub Pull Requests directly in the difit web interface using the --pr flag.

To enable this, difit requires access to the GitHub API via @octokit/rest. You must provide authentication using one of the following methods:

1. Set the GITHUB_TOKEN environment variable.
2. Use an existing GitHub CLI session (gh auth token).

Once authenticated, difit resolves the PR commits locally after fetching the necessary metadata.

The difit-review skill allows you to launch a git diff in a human-readable viewer while preloading findings or code explanations as comments. This is ideal for reviewing branch diffs, commit diffs, or GitHub PRs.

Command Selection Rule

Before running commands, determine the correct command to use:

1. If command -v difit succeeds, use difit.
2. Otherwise, use npx difit.

Note: If using npx difit in a sandboxed environment without network access, you must request escalated permissions and user approval.

To use difit, ensure your environment meets the following requirements:

• Node.js: version 21.0.0 or higher.
• Git Repository: A local Git repository containing the commits you wish to review.
• GitHub CLI: Required if using the --pr mode to fetch Pull Request patches.

You can pipe unified diff formats from any tool into difit.

Usage Rules:

• If - is provided, it always uses stdin mode.
• If positional arguments (<target> or [compare-with]) or --pr are present, it uses Git/PR mode and will NOT automatically read stdin.
• If no explicit mode is specified, it automatically switches to stdin mode if stdin is a pipe, file, or socket.

Examples:

# View diff from another tool
diff -u file1.txt file2.txt | difit

# Review a saved patch
cat changes.patch | difit

# Compare against merge base
git diff --merge-base main feature | difit

# Explicitly use stdin mode
git diff --cached | difit -

The review system allows you to create comments that can be easily copied as structured prompts for AI coding agents.

Prompt Formats:

• Single line: `path/to/file.ext:L<line_number>

<instruction>`

• Range selection: `path/to/file.ext:L<start>-L<end>

<instruction>`

Users can click "Copy Prompt" on a single comment or "Copy All Prompts" to get all comments in a structured format.

Use the following command patterns to review git changes:

Single Commit Review

• difit: Shows the diff of the latest commit (HEAD).
• difit <commit_hash>: Shows a specific commit.
• difit <branch_name>: Shows the latest commit of a specific branch.

Compare Two Commits/Branches

• difit <target> [compare-with]: Compares two points.
• difit @ main: Compares HEAD with the main branch (@ is an alias for HEAD).
• difit feature main: Compares two branches.
• difit . origin/main: Compares the working directory with a remote branch.

Use the --pr <url> flag to review a GitHub PR. This mode uses the GitHub CLI (gh) to fetch the patch and imports unresolved inline review threads as initial comments in the difit UI.

Prerequisites:

1. Authenticate with GitHub CLI: gh auth login.
2. For Enterprise Server, use gh auth login --hostname YOUR-ENTERPRISE-SERVER or set GH_HOST and GH_TOKEN environment variables.

difit --pr https://github.com/owner/repo/pull/123