Blend PDF (GO)

Purpose

Turn your single-sided scanner into a double-sided scanning powerhouse!

BlendPDFGo was created from a real-world frustration: digitizing double-sided documents when all you have is a single-sided scanner. If you’ve ever wasted time manually reordering and merging pages, this tool is built for you.

The Problem

When scanning double-sided documents with a single-sided scanner, you usually end up with two files:

Front PDF → pages 1, 3, 5, 7 … (in correct order)

Back PDF → pages 8, 6, 4, 2 … (in reverse order)

Combining them into a clean, properly ordered document is tedious, error-prone, and easy to get wrong.

The Solution

BlendPDFGo does the heavy lifting automatically:

✅ Detects and validates your scanned PDFs

✅ Reverses back-side pages when needed

✅ Merges both files into a perfectly ordered PDF (1, 2, 3, 4 …)

✅ Archives processed files and handles errors gracefully

✅ Shows progress and useful stats in real time

Who It’s For

🏠 Home users digitizing bills, letters, or family documents

🏢 Small offices that don’t have costly duplex scanners

🎓 Students scanning textbooks and research material

📚 Anyone who values speed and accuracy in document management

Why You’ll Love It

No more manual page shuffling. No more mistakes. No more wasted time.

Just scan, run BlendPDFGo, and enjoy perfectly ordered documents every single time.

⚠️ Important Disclaimer

Use at your own risk. Always keep backup copies of your original PDF files before processing. While BlendPDFGo has been thoroughly tested and includes robust error handling, you should never rely on any software as your only copy of important documents.

Recommended workflow:

Create backup copies of your original PDFs
Run BlendPDFGo on the copies
Verify the merged results before deleting originals

History

A Go-based tool for merging and managing PDF files with automatic page reversal and file organization. This is a modern reimplementation of the original bash-based BlendPDF tool with enhanced performance and reliability.

Features

Core Functionality ✅

Single File Processing: Move individual PDF files to output directory
Smart PDF Merging: Merge two PDFs with automatic page reversal of the second file
Intelligent Page Handling: Only reverse multi-page PDFs (single-page PDFs merge directly)
Robust Page Reversal: Individual page extraction and manual merging for correct ordering
File Validation: Automatic PDF validation with comprehensive error handling
Directory Organization: Automatic creation and management of archive, output, and error folders

User Interface ✅

Full-Screen Layout: Professional bordered interface with segmented sections
File Count Display: Real-time display of PDF counts integrated into header
Recent Operations: Single-line operation history with timestamps and status icons
Progress Bars: Animated progress indicators during operations
Terminal Compatibility: Automatic detection and fallback for legacy terminals
Cross-Platform UI: Modern Unicode interface for PowerShell 7/Windows Terminal, basic interface for CMD/PowerShell 5
Persistent Actions: Actions menu remains visible during processing
Real-time Monitoring: Automatic file count updates without user input
Coloured Output: Colour-coded messages for better readability
File Preview: Show available PDF files with sizes in verbose mode
Session Statistics: Track successful operations, errors, and elapsed time
Invalid Choice Handling: Clean error display with interface redraw (no stacking)

Advanced Features ✅

Directory-Specific Lock Files: Prevents multiple instances in same directory, allows multiple instances in different directories
Graceful Shutdown: Proper cleanup and statistics display on exit
Timeout Protection: Automatic exit after period of inactivity (5 minutes)
Command Line Interface: Comprehensive CLI flags and arguments
Debug Mode: Structured logging with performance monitoring

Current Status

Production Ready - All core features implemented and tested.

✅ Implemented Features

Interactive command-line menu with enhanced UI
Smart PDF merging with interleaved pattern
File movement to archive/output/error directories
Page count validation and smart reversal logic
Comprehensive error handling and recovery
Session statistics and performance monitoring
Directory-specific lock file protection and timeout handling
Debug mode with structured logging

🔄 Optional Enhancement

In-Memory Processing: Hybrid approach for performance optimization (See docs/tasks.md)

Installation

Download Pre-built Binaries

Download the latest release for your platform from the Releases page:

Windows (64-bit): blendpdf-{version}-windows-amd64.exe
Linux (64-bit): blendpdf-{version}-linux-amd64
Linux (ARM64): blendpdf-{version}-linux-arm64
macOS (64-bit): blendpdf-{version}-darwin-amd64

Installation Steps

Download the appropriate binary for your platform
Make it executable (Linux/macOS): chmod +x blendpdf-*
Move to your PATH: sudo mv blendpdf-* /usr/local/bin/blendpdf
Verify installation: blendpdf --version

Build from Source

Prerequisites

Go 1.24 or higher
Git
Make (optional, for using Makefile targets)

Quick Build

# Clone the repository
git clone https://github.com/Kristianwhittick/blend-pdf.git
cd blend-pdf

# Build for current platform
go build

# Or use Make
make build

# Run the application
./blendpdf

Multi-Platform Build

# Build for all supported platforms
make build-all

# Or use the build script directly
./build.sh --all --checksums

# Build for specific platform
make linux-amd64
./build.sh linux-amd64

Available Make Targets

make help          # Show all available targets
make build          # Build for current platform
make build-all      # Build for all platforms
make test           # Run tests
make lint           # Run linter
make clean          # Clean build artifacts
make install        # Install to GOPATH/bin
make release        # Create complete release build

Build Script Options

./build.sh --help                    # Show help
./build.sh --all                     # Build all platforms
./build.sh --clean --all             # Clean and build all
./build.sh --checksums linux-amd64   # Build with checksums
./build.sh --verbose windows-amd64   # Verbose output

Usage

Basic Usage

# Run in current directory
./blendpdf

# Show help
./blendpdf -h

# Run in verbose mode
./blendpdf -V

# Run in debug mode (includes verbose + structured logging)
./blendpdf -D

# Disable archiving for this session
./blendpdf --no-archive

# Watch specific folder
./blendpdf /path/to/pdfs

# Combined options
./blendpdf -V --no-archive /path/to/pdfs

Interactive Menu Options

Once running, use these options:

S - Move a single PDF file to the output directory
M - Merge two PDF files (first file + reversed second file)
U - Undo last operation (restore files to main directory)
A - Toggle archive mode (ON/OFF)
H - Show help information
V - Toggle verbose mode
D - Toggle debug mode (structured logging)
Q - Quit the program

Enhanced Keyboard Shortcuts

The application supports multiple input methods for faster navigation:

Operations: S, single, 1 (single file) | M, merge, 2 (merge)
Management: U, undo, Ctrl+Z (undo) | A, archive (toggle archive)
Interface: R, refresh, Space (refresh) | V, verbose (toggle verbose)
Help & Exit: H, help, F1, ? (help) | Q, quit, Ctrl+Q (exit)
Debug: D, debug (toggle debug mode)

Expected Behavior

Single File Mode (S)

Finds the first PDF file in the main directory
Validates the PDF file structure
Archive Mode ON: Copies to archive/ first, then moves to output/
Archive Mode OFF: Moves directly to output/ (no archiving)
Invalid PDF: Moves to error/ directory

Merge Mode (M)

Finds the first two PDF files in the main directory (alphabetically sorted)
Validates both PDF files and checks page count match
Smart Processing:
- Single-page second file: Direct merge (no reversal)
- Multi-page second file: Creates temporary reversed copy, then merges
Creates merged file: file1-file2.pdf in output/
Archive Mode ON: Moves original files to archive/ (default)
Archive Mode OFF: Removes original files without archiving
Failure: Moves original files to error/

Undo Mode (U)

Single File Undo: Restores file from output/ back to main directory
Merge Undo: Restores original files from archive/ back to main directory, removes merged output
Result: Clean "pre-operation" state with files only in main directory
Archive Preservation: Keeps archive copies as backups during undo

Archive Mode Control

Command Line: Use --no-archive to disable archiving for session
Interactive: Use [A] key to toggle archive mode ON/OFF
Default: Archive mode is ON (both operations archive files)

Directory Structure

The tool automatically creates and manages these directories:

your-folder/
├── file1.pdf          # Input files
├── file2.pdf
├── archive/            # Successfully processed files
├── output/             # Single files and merged results
└── error/              # Invalid or problematic files

User Interface Examples

Full-Screen Layout

┌─────────────────────────────────────────────────────────────────────────────┐
│                              BlendPDFGo v1.0.5                              │
├────

Blend Pdf

Install / Use

README