PgnMerger 0.2.0

PGN Merger — Merge Chess PGN Files via Command Line

A fast, lightweight F# command-line tool to merge multiple PGN (Portable Game Notation) chess game files into a single file.

PGN Merger takes a directory of chess game files and combines them into one consolidated merge.pgn. Perfect for building chess databases from Lichess Elite games, tournament archives, or personal game collections.

What is a PGN file?

PGN (Portable Game Notation) is the standard file format for recording chess games. Each .pgn file contains one or more chess games with metadata headers and move history. Chess players, coaches, and analysts frequently need to merge PGN files into a single database for training, opening preparation, or statistical analysis.

Features

• Merge all PGN files in a directory into one merge.pgn
• Custom output path via --output
• Recursive search through subdirectories via --recursive
• Preserves original file encoding (UTF-8)
• Zero dependencies — standalone CLI binary
• Cross-platform — runs on Windows, macOS, and Linux via .NET
• Progress feedback with throughput stats in verbose mode
• Quiet mode for silent operation
• Error handling for missing directories, empty folders, and permission issues

Installation

Option 1: Download Pre-built Binary (Recommended)

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

No runtime required — self-contained executables.

Option 2: .NET Global Tool

Requires .NET 10.0 SDK or later:

dotnet tool install -g PgnMerger

Option 3: Build from Source

git clone https://github.com/CorentinGS/pgn-merger.git
cd pgn-merger
dotnet build
dotnet run -- <folder_path> [options]

Option 3: Build from Source

git clone https://github.com/CorentinGS/pgn-merger.git
cd pgn-merger
dotnet build
dotnet run -- <folder_path> [options]

As a Global .NET Tool (coming soon)

dotnet tool install -g PgnMerger

Usage

Basic

PgnMerger <folder_path> [options]

Options

Examples

Merge all PGN files in a directory:

PgnMerger ./lichess_games

Merge with custom output file:

PgnMerger ./lichess_games --output ./combined_games.pgn

Recursive merge with verbose output:

PgnMerger ./chess_databases --recursive --verbose --output ./all_games.pgn

Quiet mode (errors only):

PgnMerger ./games --quiet --output ./merged.pgn

Comparison: PGN Merger vs. Other Tools

Choose PGN Merger when you want a simple, fast tool to combine PGN databases without extra dependencies or complex merging logic.

FAQ

How do I merge Lichess PGN files?

Download your Lichess games in PGN format, place them in one folder, and run:

PgnMerger ./my_lichess_games

The tool outputs a single merge.pgn with all games combined.

Can I merge PGN files from Chess.com?

Yes. Export your Chess.com games as PGN, place them in a directory, and run the merger.

What is the difference between merging and combining PGN files?

Merging (what this tool does) concatenates multiple games into one file. Combining into a single game tree is a different operation; for that, use tools like pgn-tools.

Does this tool modify game data?

No. PGN Merger concatenates files as-is, preserving all headers, comments, and move text.

Input / Output

• Input: A directory containing one or more .pgn files
• Output: A single merge.pgn file in the same directory with all games concatenated

Error Handling

The application handles common issues:

• Directory doesn't exist
• No PGN files found in the directory
• File access permission issues
• I/O errors during file operations

See Also

• awesome-chess — Curated list of chess resources
• awesome-fsharp — F# ecosystem tools
• python-chess — Python chess library
• Lichess — Free online chess platform
• PGN Standard — PGN specification reference

License

This project is licensed under the MIT License.

Author

Corentin Giaufer Saubert