pdf-vdiff

A fast, standalone CLI tool for side-by-side visual PDF diffing, designed primarily to inspect and verify changes between a base resume/CV and an AI-tailored version while preserving 100% vector fidelity and text searchability. It is used by JobGitOps to inspect resume diffs before submission.

pdf-vdiff compares two PDF documents (such as your canonical base resume/CV and an AI-customized version for a job application) and generates a single side-by-side landscape PDF with IntelliJ/GitHub-style visual diff highlighting. It allows you to immediately spot reworded bullet points, added keywords, and omitted sections before submitting your application.

Features

• 📄 100% Vector Fidelity: Embeds native PDF page objects directly—no lossy rasterization or blurry text.
• 🔍 Full Text Searchability: Diff output maintains searchable and selectable text layers.
• 🧠 Intelligent Hierarchical Diffing: Extracts text tokens with exact bounding boxes via PDFium, clusters lines and columns spatially, and computes Myers sequence diffs at word, line, or character granularity.
• 🎨 Multiple Color Themes: Choose between intellij (default), github, classic, and high-contrast palettes.
• ⚡ Zero-Friction CLI: Automatically opens output in your system default PDF viewer (--open), supports custom gutter widths, optional header banners, and structured exit codes.
• 🛡️ Hardened Ingestion: Pre-flight dimension and page count validation, with PDFium V8 script execution explicitly disabled for security.

Example

An example comparison of a base resume against a tailored resume is provided in the example/ directory:

• example/resume_base.pdf — Base document
• example/resume_tailored.pdf — Modified / tailored document
• example/resume_diff.pdf — Generated side-by-side visual diff

To generate the diff for this example:

pdf-vdiff example/resume_base.pdf example/resume_tailored.pdf -o example/resume_diff.pdf

To automatically open the diff in your system viewer after generation:

pdf-vdiff example/resume_base.pdf example/resume_tailored.pdf -o example/resume_diff.pdf --open

Installation & Setup

CLI via Cargo (Crates.io)

cargo install pdf-vdiff

As a Rust Library

Add pdf-vdiff to your Cargo.toml:

cargo add pdf-vdiff

Or manually:

[dependencies]
pdf-vdiff = "0.1.3" # x-release-please-version

Programmatic usage in Rust:

use pdf_vdiff::{diff_documents, DiffGranularity, PageText};

// Diff page tokens with configurable granularity (Word, Line, Character)
let diff_result = diff_documents(&base_pages, &tailored_pages, DiffGranularity::Word);

println!(
    "Detected {} difference(s) across {} page(s)",
    diff_result.total_differences,
    diff_result.pages.len()
);

Using Nix Flakes

pdf-vdiff provides full Nix Flake support (requires Nix 2.4+ with flakes and nix-command enabled). You can run it instantly without manual installation or dependencies:

# Run directly from GitHub
nix run github:menil/pdf-vdiff -- base.pdf tailored.pdf --open

# Install to your global Nix profile ($PATH)
nix profile install github:menil/pdf-vdiff

In Another Repository's flake.nix

Add pdf-vdiff as an input to include it in your developer shells or packages:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    pdf-vdiff.url = "github:menil/pdf-vdiff";
    pdf-vdiff.inputs.nixpkgs.follows = "nixpkgs";
  };

  outputs = { self, nixpkgs, pdf-vdiff, ... }:
    let
      system = "aarch64-darwin"; # or "x86_64-linux", etc.
      pkgs = nixpkgs.legacyPackages.${system};
    in {
      devShells.${system}.default = pkgs.mkShell {
        packages = [
          pdf-vdiff.packages.${system}.default
        ];
      };
    };
}

Traditional Nix Shell

If you are developing inside this repository, enter the pre-configured developer shell:

nix-shell # or nix develop

Building from Source

# Clone the repository
git clone https://github.com/menil/pdf-vdiff.git
cd pdf-vdiff

# Build release binary
cargo build --release

# Binary will be available at ./target/release/pdf-vdiff

Usage

pdf-vdiff [OPTIONS] <BASE_PDF> <TAILORED_PDF>

Options & Flags

Examples

# Compare two documents and open immediately in system default PDF viewer
pdf-vdiff original.pdf modified.pdf --open

# Use GitHub color theme with line-level diff granularity
pdf-vdiff original.pdf modified.pdf --theme github --granularity line

# Custom output destination and overwrite if target exists
pdf-vdiff base.pdf tailored.pdf -o ./output/diff.pdf --force

# Remove the top metadata banner and adjust gutter width
pdf-vdiff v1.pdf v2.pdf --no-header --gutter-width 32.0

Shell Completions & Man Pages

Pre-built shell completions and Unix man pages are maintained in completions/ and man/:

Shell Completions

Generate or source completions on the fly for your active shell:

# Bash (add to ~/.bashrc)
eval "$(pdf-vdiff --generate-completions bash)"

# Zsh (add to ~/.zshrc)
eval "$(pdf-vdiff --generate-completions zsh)"

# Fish (add to ~/.config/fish/config.fish)
pdf-vdiff --generate-completions fish | source

Man Pages & TLDR

• Unix Man Page: Installed automatically with package managers (man pdf-vdiff), or view directly:
  • macOS: pdf-vdiff --generate-man | mandoc
  • Linux: pdf-vdiff --generate-man | man -l -
  • Direct file: man man/pdf-vdiff.1
• TLDR Cheatsheet: Available in man/pdf-vdiff.tldr.md.

Exit Codes

Development

A Justfile task runner is included for common development workflows:

# List available recipes
just

# Run test suite
just test

# Check formatting and linting
just lint

# Run all validations (tests, linter, format check, coverage)
just validate

For comprehensive guidelines on Nix environment setup, Git hooks, Beads issue tracking, and AI ignore policies, see the Development Guide.

License

This project is licensed under the MIT License.