Skip to content

Readme #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
idigdoug merged 6 commits into from
Mar 6, 2026
Merged

Readme #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
ed028f4
README changes iteration 1
idigdoug Mar 6, 2026
0a90169
README iteration 2
idigdoug Mar 6, 2026
0924eae
Fix hallucinations
idigdoug Mar 6, 2026
eb3415d
README tweaks
idigdoug Mar 6, 2026
e2f0aaa
Formatting
idigdoug Mar 6, 2026
0126d62
PR Feedback
idigdoug Mar 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CheckSums.sln
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ EndProject
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{8EC462FD-D22E-90A8-E5CE-7E832BA40C5D}"
ProjectSection(SolutionItems) = preProject
.github\workflows\build-and-test.yml = .github\workflows\build-and-test.yml
README.md = README.md
.github\workflows\release.yml = .github\workflows\release.yml
EndProjectSection
EndProject
Expand Down
181 changes: 151 additions & 30 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,33 +1,137 @@
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Build](https://github.com/idigdoug/CheckSums/actions/workflows/release.yml/badge.svg)](https://github.com/idigdoug/CheckSums/actions/workflows/build-and-test.yml)
[![GitHub Release](https://img.shields.io/github/v/release/idigdoug/CheckSums)](https://github.com/idigdoug/CheckSums/releases)

# CheckSums

Create or validate file checksums on Windows.
Works a lot like `md5sum` and `sha256sum` but with a few extra features:
A fast, lightweight, native Windows command-line tool for computing and validating file checksums.

- Can optionally recurse into subdirectories.
- Can optionally write results to a file instead of stdout.
- Can optionally encode output file as UTF-8 with BOM.
- Supports many different checksum algorithms (see below).
Works a lot like `md5sum` and `sha256sum` but with extra features including directory recursion,
multiple checksum algorithms, and optional UTF-8 output.

## Table of Contents

- [Why CheckSums?](#why-checksums)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Recursion](#recursion)
- [Base Directory](#base-directory)
- [Output File](#output-file)
- [Checksum Algorithms](#checksum-algorithms)
- [Examples](#examples)
- [Usage](#usage)
- [Contributing](#contributing)
- [License](#license)

## Why CheckSums?

**CheckSums** is a Windows tool that:

- **Runs natively on Windows** - no extra runtimes: no WSL, no Cygwin.
- **Supports 12 algorithms** in a single tool, from fast non-cryptographic hashes
([Murmur3](https://en.wikipedia.org/wiki/MurmurHash),
[Adler-32](https://en.wikipedia.org/wiki/Adler-32))
to cryptographic standards
([SHA-256](https://en.wikipedia.org/wiki/SHA-2),
[SHA-512](https://en.wikipedia.org/wiki/SHA-2)).
- **Recurses into subdirectories** with familiar wildcard patterns.
- **Handles Unicode filenames** correctly with optional UTF-8 BOM output.
- **Fast** - the default Murmur3x64_128 algorithm is ~11x faster than
MD5 on typical workloads.

### Sample Output

```
> CheckSums.exe -a crc32 -r pch.*
d61765c7 exe\pch.cpp
e208b879 exe\pch.h
d61765c7 lib\pch.cpp
e208b879 lib\pch.h
d61765c7 test\pch.cpp
1c913623 test\pch.h

> CheckSums.exe -a crc32 -r pch.* -o checksums.crc32

> CheckSums.exe -a crc32 -c checksums.crc32
d61765c7 exe\pch.cpp* OK
e208b879 exe\pch.h* OK
d61765c7 lib\pch.cpp* OK
e208b879 lib\pch.h* OK
d61765c7 test\pch.cpp* OK
1c913623 test\pch.h* OK
```

## Installation

### Requirements

- **Windows 10** or later (x86, x64, ARM64).
- No additional runtime dependencies - the binary is statically linked.

### Download

Download the latest prebuilt binary from the
[Releases](https://github.com/idigdoug/CheckSums/releases) page.

### Build from Source

Requirements: Visual Studio 2022 with the C++ Desktop workload (C++20).

1. Clone the repository: `git clone https://github.com/idigdoug/CheckSums.git`
2. Open `CheckSums.sln` in Visual Studio.
3. Build the solution (Release, x64).

## Quick Start

```
# Compute SHA256 checksums for all files in the current directory:
CheckSums -a SHA256 *

# Record MD5 checksums for all .txt files in the "Files" directory and subdirectories:
CheckSums -a MD5 -r Files\*.txt > ..\checksums.md5

# Validate recorded checksums against the corresponding files:
CheckSums -a MD5 -c ..\checksums.md5
```

## Recursion

When computing checksums, this tool accepts FileSpecs that specify the files to be
processed. The FileSpec is split into a (potentially empty) directory part and a
filename pattern part. The filename pattern may contain wildcards '*' and '?'.
filename pattern part. The filename pattern may contain wildcards `*` and `?`.

Example: `CheckSums Files\*.txt` will compute checksums for all ".txt" files the
Example: `CheckSums Files\*.txt` will compute checksums for all ".txt" files in the
"Files" directory.

Normally, the filename pattern is evaluated only in the directory specified by the
directory part. However, if the `-r` or `--recurse` option is given, the filename
pattern will be evaluated in every directory at or below the directory specified by
the directory part.
the directory part. This behavior is similar to the behavior of `dir /s /b FileSpec`.

Example: `CheckSums -r Files\*.txt` will compute checksums for all ".txt" files the
Example: `CheckSums -r Files\*.txt` will compute checksums for all ".txt" files in the
"Files" directory and its subdirectories.

## Output file
## Base Directory

By default, files to be checksummed are located relative to the current directory.
You can specify a different base directory using the `-d` or `--dir` option. The
output will list file paths relative to the base directory.

Setting the base directory is not the same as specifying the directory in the FileSpec.
Directory components in the FileSpec are included in the output, while the base directory
is not. For example:

```
> CheckSums E:\repos\CheckSums\exe\pch.cpp
b2e755768937966436f669ad8e4411ce E:\repos\CheckSums\exe\pch.cpp

> CheckSums -d E:\repos\CheckSums exe\pch.cpp
b2e755768937966436f669ad8e4411ce exe\pch.cpp
```

The base directory is used when computing checksums and when validating checksums.

## Output File

By default, this tool writes results to standard output. However, you can specify an
output file using the `-o` or `--out` option.
Expand All @@ -38,28 +142,38 @@ When using `-o` or `--out`, you can save the results as UTF-8 using the `--utf8b
option. You can append to the output file instead of overwriting it using the
`--append` option.

## Checksum algorithms
## Checksum Algorithms

This tool supports the following algorithms:

- Adler32
- Crc32
- Fnv1a32
- Fnv1a64
- MD4
- MD5
- Murmur3x64_128
- SHA1
- SHA256
- SHA384
- SHA512
- Xor64

The default algorithm is Murmur3x64_128. This is not a cryptographic checksum algorithm, but it
is very fast and has good distribution properties. It is suitable for detecting changes to files.

For security-sensitive applications, you should select a cryptographic hash algorithm such as SHA256
or SHA512 using the `-a` option.
| Algorithm | Type | Benchmark (relative time, lower = faster) |
| ------------------------------------------------------------------------------------- | -------------------- | ----------------------------------------- |
| [Adler32](https://en.wikipedia.org/wiki/Adler-32) | Non-cryptographic | 131 |
| [Crc32](https://en.wikipedia.org/wiki/Cyclic_redundancy_check) | Non-cryptographic | 779 |
| [Fnv1a32](https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function) | Non-cryptographic | 442 |
| [Fnv1a64](https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function) | Non-cryptographic | 425 |
| [MD4](https://en.wikipedia.org/wiki/MD4) | Cryptographic (weak) | 450 |
| [MD5](https://en.wikipedia.org/wiki/MD5) | Cryptographic (weak) | 759 |
| [Murmur3x64_128](https://en.wikipedia.org/wiki/MurmurHash) | Non-cryptographic | 68 _(default)_ |
| [SHA1](https://en.wikipedia.org/wiki/SHA-1) | Cryptographic (weak) | 575 |
| [SHA256](https://en.wikipedia.org/wiki/SHA-2) | Cryptographic | 232 |
| [SHA384](https://en.wikipedia.org/wiki/SHA-2) | Cryptographic | 695 |
| [SHA512](https://en.wikipedia.org/wiki/SHA-2) | Cryptographic | 685 |
| [Xor64](https://en.wikipedia.org/wiki/XOR_cipher) | Non-cryptographic | 23 |

> **Note:** Benchmark values are relative times measured on a single machine. They are
> useful for comparing algorithms to each other, not as absolute performance numbers.

The default algorithm is **Murmur3x64_128**. This is not a cryptographic hash, but it
is very fast and has good distribution properties. It is suitable for detecting changes
to files.

For security-sensitive applications, use a cryptographic hash algorithm such as SHA256
or SHA512, e.g. `-a sha256`.

> **Note:** The Xor64 algorithm is extremely fast but is very weak. It is not recommended
> for general use but may be useful for benchmarking, i.e. for measuring I/O overhead
> against time spent computing the actual checksum.

## Examples

Expand Down Expand Up @@ -176,6 +290,13 @@ Checksum algorithm options, along with a benchmark time (smaller is faster):
-a Xor64 23
```

## Contributing

Contributions are welcome! Please
[open an issue](https://github.com/idigdoug/CheckSums/issues) to report bugs or
suggest features, or submit a
[pull request](https://github.com/idigdoug/CheckSums/pulls).

## License

Copyright (c) Doug Cook.
Expand Down