From 1fb9f6e413ae1a8a3285bbfa7eb25f18c4b6029b Mon Sep 17 00:00:00 2001
From: synesissoftware <matthew@synesis.com.au>
Date: Thu, 27 Aug 2026 17:09:59 +1000
Subject: [PATCH 1/3] Boilerplate, CI (#1)

* **run_all_unit_tests.sh** : ~ updated to latest (from https://github.com/synesissoftware/misc-dev-scripts)

* boilerplate: markdown files

* boilerplate: .gitattributes

* boilerplate: LICENSE

* boilerplate: .vscode/settings.json

* boilerplate: .vimrc

* boilerplate: build_gem.cmd, build_gem.sh, generate_rdoc.cmd, generate_rdoc.sh

* boilerplate: LICENSE

* bolierplate: updating Gemfile

* boilerplate: placeholder markdown files

* chore: removed .ruby-version from repository

* boilerplate: .gitignore

* version dependencies

* boilerplate: .ruby-version-exclusions

* Add canonical AUTHORS, FAQ, NEWS, and TODO markdown skeletons

* Fill CHANGES.md from release tags and git history

* Add ruby.yml CI badge and switch Gemfile to gemspec

* chore: dependencies

* gemspec updates

* chore: AUTHORS.md

* fix: gemspec metadata

* added/updated Rakefile

* chore: CONTRIBUTING.md, INSTALL.md, SECURITY.md

* chore: rake in Gemfile

* fix: Add frozen lib/ strings and standardise Ruby gem boilerplate

* standard CI for all projects

* standard .editorconfig and dependabot for all projects

* TODO.md

* examples

* CHANGES.md

* NEWS.md

* README.md

* spacing
---
 .editorconfig                         |  64 ++++++++
 .gitattributes                        |  75 +++++++++
 .github/dependabot.yml                |  10 ++
 .github/workflows/ruby.yml            | 117 ++++++++++++++
 .gitignore                            |  30 +---
 .ruby-version                         |   1 -
 .ruby-version-exclusions              |   8 -
 .sis/project_name.txt                 |   1 +
 .vimrc                                |  70 ++++++++
 .vscode/settings.json                 |  49 +++++-
 AUTHORS.md                            |  21 +++
 CHANGES.md                            |  70 +++++++-
 CONTRIBUTING.md                       |  36 +++++
 EXAMPLES.md                           |  11 +-
 FAQ.md                                |  28 ++++
 Gemfile                               |  10 +-
 Gemfile.lock                          |  20 +++
 INSTALL.md                            |  41 +++++
 LICENSE                               |  20 +--
 NEWS.md                               |  20 +++
 README.md                             |   3 +-
 Rakefile                              |  21 +++
 SECURITY.md                           |  23 +++
 TODO.md                               |  19 +++
 build_gem.cmd                         |  13 ++
 build_gem.sh                          |   5 +-
 cmpfs.gemspec                         |  33 ++--
 examples/compare_two_binary_files.md  |  57 +++++++
 examples/compare_two_text_files.md    |  57 +++++++
 generate_rdoc.cmd                     |  28 ++++
 generate_rdoc.sh                      |  31 ++++
 lib/cmpfs.rb                          |   4 +-
 lib/cmpfs/compare.rb                  |   4 +-
 lib/cmpfs/compare/api_1_9.rb          |   1 +
 lib/cmpfs/compare/api_2.rb            |   1 +
 lib/cmpfs/compare/binary/internal_.rb |   1 +
 lib/cmpfs/compare/text/internal_.rb   |   1 +
 lib/cmpfs/version.rb                  |   8 +-
 run_all_unit_tests.sh                 | 219 ++++++++++++++++----------
 39 files changed, 1062 insertions(+), 169 deletions(-)
 create mode 100644 .editorconfig
 create mode 100644 .github/dependabot.yml
 create mode 100644 .github/workflows/ruby.yml
 delete mode 100644 .ruby-version
 create mode 100644 .sis/project_name.txt
 create mode 100644 .vimrc
 create mode 100644 AUTHORS.md
 create mode 100644 CONTRIBUTING.md
 create mode 100644 FAQ.md
 create mode 100644 Gemfile.lock
 create mode 100644 INSTALL.md
 create mode 100644 NEWS.md
 create mode 100644 Rakefile
 create mode 100644 SECURITY.md
 create mode 100644 TODO.md
 create mode 100644 build_gem.cmd
 create mode 100644 examples/compare_two_binary_files.md
 create mode 100644 examples/compare_two_text_files.md
 create mode 100644 generate_rdoc.cmd
 create mode 100755 generate_rdoc.sh

diff --git a/.editorconfig b/.editorconfig
new file mode 100644
index 0000000..8d78c5d
--- /dev/null
+++ b/.editorconfig
@@ -0,0 +1,64 @@
+root = true
+
+# Language indent/EOL/charset overlap with .vscode/settings.json.
+# Rulers, renderWhitespace, detectIndentation, mergeEditor, and
+# cmake.configureOnOpen cannot be expressed here — they stay in settings.json.
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 2
+indent_style = tab
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+# [bat]
+[*.{bat,cmd}]
+end_of_line = crlf
+indent_size = 4
+indent_style = space
+
+# [c]
+[*.{c,h}]
+indent_size = 4
+indent_style = space
+
+# [cmake]
+[{CMakeLists.txt,*.cmake}]
+indent_size = 4
+indent_style = tab
+
+# [cpp]
+[*.{cpp,cxx,hpp,hxx}]
+indent_size = 4
+indent_style = space
+
+# [json]
+[*.json]
+indent_size = 2
+indent_style = space
+
+# [markdown]
+[*.md]
+indent_size = 2
+indent_style = space
+trim_trailing_whitespace = false
+
+# [ruby]
+[*.{gemspec,rb}]
+indent_size = 2
+indent_style = space
+
+[{Gemfile,Rakefile}]
+indent_size = 2
+indent_style = space
+
+# [shellscript]
+[*.{bash,sh,zsh}]
+indent_size = 2
+indent_style = space
+
+# [yaml]
+[*.{yaml,yml}]
+indent_size = 2
+indent_style = space
diff --git a/.gitattributes b/.gitattributes
index e69de29..2c70232 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -0,0 +1,75 @@
+# .gitattributes — Ruby (GitHub-hosted)
+#
+# Sources: GitHub Docs (line endings), git-scm gitattributes (diff=ruby),
+# gitattributes/gitattributes Common.gitattributes + Web (*.rb),
+# github-linguist overrides.
+
+# Default: detect text, normalize to LF in the repository
+* text=auto
+
+# --- Source ---
+*.gemspec text eol=lf diff=ruby
+*.rake text eol=lf diff=ruby
+*.rb text eol=lf diff=ruby
+*.ru text eol=lf diff=ruby
+Gemfile text eol=lf diff=ruby
+Rakefile text eol=lf diff=ruby
+Capfile text eol=lf diff=ruby
+Guardfile text eol=lf diff=ruby
+*.erb text
+*.haml text
+*.slim text
+
+# --- Lock / config ---
+Gemfile.lock text
+*.gemspec.lock text -diff
+*.yml text
+*.yaml text
+*.toml text
+*.json text
+
+# --- Scripts ---
+*.bash text eol=lf
+*.bat text eol=crlf
+*.cmd text eol=crlf
+*.ps1 text eol=crlf
+*.sh text eol=lf
+*.zsh text eol=lf
+
+# --- Docs / meta ---
+*.adoc text
+*.markdown text diff=markdown
+*.md text diff=markdown
+*.txt text
+AUTHORS text
+CHANGELOG text
+CHANGES text
+CONTRIBUTING text
+COPYING text
+LICENSE text
+NEWS text
+README text
+TODO text
+.gitattributes text
+.gitignore text
+
+# --- Binary ---
+*.gem binary
+*.so binary
+
+# --- Archives / images (common) ---
+*.gif binary
+*.gz binary
+*.ico binary
+*.jpeg binary
+*.jpg binary
+*.png binary
+*.tar binary
+*.zip binary
+
+# --- GitHub Linguist ---
+**/vendor/bundle/** linguist-vendored
+**/vendor/cache/** linguist-vendored
+**/coverage/** linguist-generated
+**/doc/** linguist-documentation
+**/pkg/** linguist-generated
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
new file mode 100644
index 0000000..3189593
--- /dev/null
+++ b/.github/dependabot.yml
@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - directory: /
+    package-ecosystem: bundler
+    schedule:
+      interval: weekly
+  - directory: /
+    package-ecosystem: github-actions
+    schedule:
+      interval: weekly
diff --git a/.github/workflows/ruby.yml b/.github/workflows/ruby.yml
new file mode 100644
index 0000000..6e63b88
--- /dev/null
+++ b/.github/workflows/ruby.yml
@@ -0,0 +1,117 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
+# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
+
+#
+# Created: 15th August 2026
+# Updated: 15th August 2026
+#
+
+name: Ruby
+
+on:
+  push:
+    branches:
+      - master
+      - dev
+      - boilerplate
+      - idiomatic
+      - rc1
+      - rc2
+      - rc3
+  pull_request:
+
+permissions:
+  contents: read
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  test:
+
+    strategy:
+      fail-fast: false
+
+      matrix:
+        os:
+          - macos-latest
+          - ubuntu-latest
+          - windows-latest
+
+        ruby-version:
+          # - head
+          - '3.4'
+          - '3.3'
+          - '3.2'
+          - '3.1'
+          - '3.0'
+          - '2.7'
+          - '2.6'
+
+        include:
+          - os: ubuntu-latest
+            ruby-version: '2.5'
+          - os: ubuntu-latest
+            ruby-version: '2.4'
+          - os: ubuntu-latest
+            ruby-version: '2.0'
+          - os: windows-latest
+            ruby-version: mingw
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+    - name: Checking out code
+      uses: actions/checkout@v4
+
+    - name: Remove Gemfile.lock
+      run: rm -f Gemfile.lock
+
+    - name: Set up Ruby v${{ matrix.ruby-version }}
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+
+    - name: Show Ruby version
+      run: ruby -v
+
+    - name: Run tests
+      run: bundle exec rake test
+
+    - name: Gem build and install smoke
+      shell: bash
+      run: |
+        gem build cmpfs.gemspec
+        gem install --local cmpfs-ruby-*.gem
+        ruby -e "require 'cmpfs/version'; abort('VERSION missing') unless defined?(CmpFS::VERSION); puts CmpFS::VERSION"
+
+  warnings:
+
+    name: Warnings
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checking out code
+      uses: actions/checkout@v4
+
+    - name: Remove Gemfile.lock
+      run: rm -f Gemfile.lock
+
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '3.3'
+        bundler-cache: true
+
+    - name: Show Ruby version
+      run: ruby -v
+
+    - name: Run unit tests with warnings
+      run: ./run_all_unit_tests.sh --lib --warnings
diff --git a/.gitignore b/.gitignore
index 0677442..0d510c3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,57 +1,44 @@
-
 # directories (by name)
 
+/.bzr/
 /.bundle/
+/.config/
 /.svn/
 /.yardoc/
 
 /_yardoc/
 
+/InstalledFiles/
 /build/
-/build-iPhoneOS/
-/build-iPhoneSimulator/
 /coverage/
 /doc/
-/rdoc/
 /lib/bundler/man/
+/old-gems/
 /pkg/
+/rdoc/
+/scratch/
 /spec/reports/
 /test/tmp/
 /test/version_tmp/
 /tmp/
 /vendor/bundle/
-/InstalledFiles/
-
 
 # directories (by pattern)
 
-
 # files (by name)
 
 .DS_Store
-.bundle
-.config
 .repl_history
+.ruby-version
 .rvmrc
-.yardoc
-
-_yardoc
-
-Gemfile.lock
-InstalledFiles
-coverage
-pkg
-rdoc
 
 /spec/examples.txt
 
-
 # files (by pattern)
 
-.dat*
-
 *~
 *.*~
+.dat*
 *.b64
 *.bridgesupport
 *.gem
@@ -61,4 +48,3 @@ rdoc
 *.swp
 *.tmp
 *.zip
-
diff --git a/.ruby-version b/.ruby-version
deleted file mode 100644
index ef538c2..0000000
--- a/.ruby-version
+++ /dev/null
@@ -1 +0,0 @@
-3.1.2
diff --git a/.ruby-version-exclusions b/.ruby-version-exclusions
index 30e2993..442b295 100644
--- a/.ruby-version-exclusions
+++ b/.ruby-version-exclusions
@@ -1,10 +1,2 @@
 1.8.7-p375
-#1.9.3-p551
-#2.0.0-p648
-#2.1.10
-#2.2.10
-#2.3.8
-#2.4.5
-#2.5.3
-#2.6.1
 
diff --git a/.sis/project_name.txt b/.sis/project_name.txt
new file mode 100644
index 0000000..b654a98
--- /dev/null
+++ b/.sis/project_name.txt
@@ -0,0 +1 @@
+cmpfs.Ruby
diff --git a/.vimrc b/.vimrc
new file mode 100644
index 0000000..b8184be
--- /dev/null
+++ b/.vimrc
@@ -0,0 +1,70 @@
+" Synesis Ruby project .vimrc — aligned with .vscode/settings.json (2-space Ruby)
+
+set nocompatible
+filetype indent plugin on
+syntax enable
+set autoindent
+set backspace=indent,eol,start
+set hlsearch
+set incsearch
+set number
+
+" files.insertFinalNewline
+set eol
+set fixeol
+
+" editor.renderWhitespace: all
+set list
+set listchars=tab:->,trail:-,extends:>,precedes:<,nbsp:+
+
+" editor.detectIndentation: false — global defaults (editor.tabSize: 2, insertSpaces: true)
+set colorcolumn=76
+set expandtab
+set shiftwidth=2
+set softtabstop=2
+set tabstop=2
+
+" colorcolumn draws a full-column tint in Vim (not a VS Code-style 1px line).
+" Keep it subtle via the ColorColumn highlight group; reapply after colorscheme changes.
+if has('termguicolors')
+  " set termguicolors
+endif
+
+function! s:ConfigureColorColumn() abort
+  highlight ColorColumn ctermbg=236 guibg=#2a2a2a cterm=NONE gui=NONE
+endfunction
+
+call s:ConfigureColorColumn()
+autocmd ColorScheme * call s:ConfigureColorColumn()
+
+" files.trimTrailingWhitespace
+autocmd BufWritePre * %s/\s\+$//e
+
+augroup sis_c_cxx
+  autocmd!
+
+  " [c] / [cpp]
+  autocmd FileType c,cpp setlocal expandtab tabstop=4 shiftwidth=4 softtabstop=4 colorcolumn=60,64,68,72,76
+
+  " [rust]
+  autocmd FileType rs setlocal expandtab tabstop=4 shiftwidth=4 softtabstop=4 colorcolumn=76
+
+  " [cmake]
+  autocmd FileType cmake setlocal noexpandtab tabstop=4 shiftwidth=4 softtabstop=4
+
+  " [shellscript]
+  autocmd FileType sh,bash,zsh setlocal expandtab tabstop=2 shiftwidth=2 softtabstop=2 colorcolumn=60,76
+
+  " [bat]
+  autocmd FileType bat,dosbatch setlocal expandtab tabstop=4 shiftwidth=4 softtabstop=4 colorcolumn=60,76
+
+  " [json] / [markdown] / [yaml] / [ruby]
+  autocmd FileType json,markdown,yaml,ruby setlocal expandtab tabstop=2 shiftwidth=2 softtabstop=2
+
+  " [python]
+  autocmd FileType python setlocal expandtab tabstop=4 shiftwidth=4 softtabstop=4 colorcolumn=60,76
+
+  " [toml]
+  autocmd FileType toml setlocal noexpandtab tabstop=2 shiftwidth=2 softtabstop=2
+augroup END
+
diff --git a/.vscode/settings.json b/.vscode/settings.json
index d9e8963..19efccd 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -1,10 +1,43 @@
 {
-  "[ruby]": {
-      "editor.tabSize": 2,
-  },
-  "cmake.configureOnOpen": false,
-  "editor.detectIndentation": false,
-  "editor.insertSpaces": true,
-  "editor.tabSize": 2,
-  "files.trimTrailingWhitespace": true,
+	"[json]": {
+		"editor.insertSpaces": true,
+		"editor.tabSize": 2,
+	},
+	"[markdown]": {
+		"editor.insertSpaces": true,
+		"editor.tabSize": 2,
+	},
+	"[python]": {
+		"editor.insertSpaces": true,
+		"editor.rulers": [ 60, 76 ],
+		"editor.tabSize": 4,
+	},
+	"[ruby]": {
+		"editor.defaultFormatter": "Shopify.ruby-lsp",
+		"editor.formatOnSave": true,
+		"editor.formatOnType": true,
+		"editor.insertSpaces": true,
+		"editor.rulers": [ 60, 76 ],
+		"editor.semanticHighlighting.enabled": true,
+		"editor.tabSize": 2,
+	},
+	"[shellscript]": {
+		"editor.insertSpaces": true,
+		"editor.rulers": [ 60, 76 ],
+		"editor.tabSize": 2,
+	},
+	"[toml]": {
+		"editor.insertSpaces": false,
+		"editor.tabSize": 2,
+	},
+	"cmake.configureOnOpen": false,
+	"editor.detectIndentation": false,
+	"editor.insertSpaces": false,
+	"editor.renderWhitespace": "all",
+	"editor.rulers": [ 76 ],
+	"editor.tabSize": 2,
+	"files.insertFinalNewline": true,
+	"files.trimTrailingWhitespace": true,
+	"git.mergeEditor": false,
+	"rubyLsp.formatter": "auto",
 }
diff --git a/AUTHORS.md b/AUTHORS.md
new file mode 100644
index 0000000..72922f0
--- /dev/null
+++ b/AUTHORS.md
@@ -0,0 +1,21 @@
+# cmpfs.Ruby - Authors <!-- omit in toc -->
+
+
+## Major Contributors
+
+| Name        | GitHub                            |
+| ----------- | --------------------------------- |
+| Matt Wilson | [mwsis](https://github.com/mwsis) |
+
+
+## Defect reports, fixes and suggestions (for which we are very grateful)
+
+| Name        | GitHub                            |
+| ----------- | --------------------------------- |
+| \<none>     |                                   |
+
+
+Contributions are welcomed.
+
+
+<!-- ########################### end of file ########################### -->
diff --git a/CHANGES.md b/CHANGES.md
index 34fb2ca..457beeb 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,4 +1,70 @@
-# **cmpfs.Ruby** Changes
+# cmpfs.Ruby - Changes <!-- omit in toc -->
 
-T.B.C.
 
+## 0.2.4 - 15th August 2026
+
+* added `# frozen_string_literal: true` to all **lib/** sources;
+* completed **EXAMPLES.md** catalogue for existing examples;
+
+
+## 0.2.3 - 4th April 2024
+
+* fixed restrictive Ruby 2.x dependency in gemspec;
+
+
+## 0.2.2.1 - 4th April 2024
+
+* fixed license to canonical form;
+
+
+## 0.2.2 - 4th April 2024
+
+* fixed restrictive Ruby 2.x dependency in gemspec;
+
+
+## 0.2.1.4 - 3rd April 2024
+
+* tidying and documentation;
+
+
+## 0.2.1.3 - 3rd April 2024
+
+* tidying and documentation;
+
+
+## 0.2.1.2 - 2nd April 2024
+
+* tidying, documentation, and project boilerplate;
+
+
+## 0.2.1.1 - 2nd April 2024
+
+* merged **boilerplate** into **master**;
+
+
+## 0.2.1 - 11th April 2019
+
+* tidyings;
+
+
+## 0.2.0 - 13th March 2019
+
+* added `Compare.compare_text_files()`, `Compare.compare_text_streams()`, and `Compare.compare_text()`;
+
+
+## 0.1.0 - 13th March 2019
+
+* sorted modules correctly for including and extending;
+
+
+## 0.0.1 - 12th March 2019
+
+* added missing `VERSION_REVISION`;
+
+
+## 0.0.0 - 12th March 2019
+
+* initial version;
+
+
+<!-- ########################### end of file ########################### -->
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..d8bb0be
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,36 @@
+# cmpfs.Ruby - Contributing <!-- omit in toc -->
+
+
+## Table of Contents <!-- omit in toc -->
+
+- [Defects and features](#defects-and-features)
+- [Pull requests](#pull-requests)
+- [Tests](#tests)
+- [License](#license)
+
+
+## Defects and features
+
+Open an issue on https://github.com/synesissoftware/cmpfs.Ruby/issues.
+
+
+## Pull requests
+
+Pull requests are welcome on https://github.com/synesissoftware/cmpfs.Ruby. Keep diffs local to the change; match existing indentation (2 spaces in Ruby) and the Synesis markdown set (**README.md**, **CHANGES.md**, **NEWS.md**, **TODO.md**, **INSTALL.md**, **CONTRIBUTING.md**, **SECURITY.md**).
+
+
+## Tests
+
+```
+bundle exec rake test
+```
+
+or `./run_all_unit_tests.sh`.
+
+
+## License
+
+Contributions are accepted under the 3-clause BSD license. See [LICENSE](./LICENSE).
+
+
+<!-- ########################### end of file ########################### -->
diff --git a/EXAMPLES.md b/EXAMPLES.md
index 23b5970..e4f3fdb 100644
--- a/EXAMPLES.md
+++ b/EXAMPLES.md
@@ -1,8 +1,9 @@
-# **cmpfs.Ruby** Examples
+# cmpfs.Ruby - Examples <!-- omit in toc -->
 
-|Name|Source & Description|Summary|
-|---|---|---|
+| Name                         | Source & Description                                                                                                                               | Summary                                                                              |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| **compare_two_binary_files** | [examples/compare_two_binary_files.rb](/examples/compare_two_binary_files.rb)<br/>[examples/compare_two_binary_files.md](/examples/compare_two_binary_files.md) | Compares two files for binary equality via `compare_binary`                          |
+| **compare_two_text_files**   | [examples/compare_two_text_files.rb](/examples/compare_two_text_files.rb)<br/>[examples/compare_two_text_files.md](/examples/compare_two_text_files.md)     | Compares two files for text equality via `compare_text` (skip blank lines; trim)     |
 
 
-T.B.C.
-
+<!-- ########################### end of file ########################### -->
diff --git a/FAQ.md b/FAQ.md
new file mode 100644
index 0000000..dd6783d
--- /dev/null
+++ b/FAQ.md
@@ -0,0 +1,28 @@
+# cmpfs.Ruby - FAQ <!-- omit in toc -->
+
+The FAQ list is under (constant) development. If you post a question on the
+[Issues](https://github.com/synesissoftware/cmpfs.Ruby/issues) forum
+it will be used to create one.
+
+
+## Table of Contents <!-- omit in toc -->
+
+- [Q1: "How do I install this library?"](#q1-how-do-i-install-this-library)
+
+
+# FAQs: <!-- omit in toc -->
+
+
+## Q1: "How do I install this library?"
+
+Install via **gem**:
+
+```
+gem install cmpfs-ruby
+```
+
+See [README.md](./README.md) for usage.
+
+
+
+<!-- ########################### end of file ########################### -->
diff --git a/Gemfile b/Gemfile
index b22bf8f..29f6d2e 100644
--- a/Gemfile
+++ b/Gemfile
@@ -2,11 +2,15 @@
 
 source "https://rubygems.org"
 
-if RUBY_VERSION >= '2'
+gemspec
 
-  gem "xqsr3", '~> 0.39'
+# rake 13 requires Ruby >= 2.3
+if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("2.3")
+
+  gem "rake", '~> 13.0'
 else
 
-  gem 'xqsr3', '~> 0.21.3'
+  gem "rake", '~> 12.3'
 end
 
+gem "test-unit", '~> 3.0'
diff --git a/Gemfile.lock b/Gemfile.lock
new file mode 100644
index 0000000..8d6765f
--- /dev/null
+++ b/Gemfile.lock
@@ -0,0 +1,20 @@
+PATH
+  remote: .
+  specs:
+    cmpfs-ruby (0.2.3)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    xqsr3 (0.39.5)
+
+PLATFORMS
+  arm64-darwin-25
+  ruby
+
+DEPENDENCIES
+  cmpfs-ruby!
+  xqsr3 (~> 0.39, >= 0.39.1)
+
+BUNDLED WITH
+   2.6.9
diff --git a/INSTALL.md b/INSTALL.md
new file mode 100644
index 0000000..5ac5030
--- /dev/null
+++ b/INSTALL.md
@@ -0,0 +1,41 @@
+# cmpfs.Ruby - Installation and Use <!-- omit in toc -->
+
+
+## Table of Contents <!-- omit in toc -->
+
+- [Install the gem](#install-the-gem)
+- [From a source checkout](#from-a-source-checkout)
+- [Using the library](#using-the-library)
+
+
+## Install the gem
+
+```
+gem install cmpfs-ruby
+```
+
+or add to a **Gemfile**:
+
+```Ruby
+gem 'cmpfs-ruby'
+```
+
+then `bundle install`.
+
+
+## From a source checkout
+
+```
+bundle install
+bundle exec rake test
+```
+
+
+## Using the library
+
+```Ruby
+require 'cmpfs'
+```
+
+
+<!-- ########################### end of file ########################### -->
diff --git a/LICENSE b/LICENSE
index 61b84ab..1652284 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,22 +1,22 @@
-cmpfs.Ruby
+cmpfs.Ruby - BSD 3-Clause License
 
-Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
+Copyright (c) 2019-2026, Matthew Wilson and Synesis Information Systems
 Copyright (c) 2019, Matthew Wilson and Synesis Software
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:
 
-* Redistributions of source code must retain the above copyright notice,
-  this list of conditions and the following disclaimer.
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
 
-* Redistributions in binary form must reproduce the above copyright notice,
-  this list of conditions and the following disclaimer in the documentation
-  and/or other materials provided with the distribution.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
 
-* Neither the names of cmpfs or cmpfs.Ruby nor the names of its contributors
-  or its copyright holders may be used to endorse or promote products
-  derived from this software without specific prior written permission.
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
 
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
diff --git a/NEWS.md b/NEWS.md
new file mode 100644
index 0000000..af22b41
--- /dev/null
+++ b/NEWS.md
@@ -0,0 +1,20 @@
+# cmpfs.Ruby - News <!-- omit in toc -->
+
+| Date             | News Item                                                                                |
+| ---------------- | ---------------------------------------------------------------------------------------- |
+| 15th August 2026 | [**cmpfs.Ruby** 0.2.4](https://github.com/synesissoftware/cmpfs.Ruby/releases/tag/0.2.4) |
+| 4th April 2024   | [**cmpfs.Ruby** 0.2.3](https://github.com/synesissoftware/cmpfs.Ruby/releases/tag/0.2.3) |
+| 4th April 2024   | **cmpfs.Ruby** 0.2.2.1 released                                                          |
+| 4th April 2024   | **cmpfs.Ruby** 0.2.2 released                                                            |
+| 3rd April 2024   | **cmpfs.Ruby** 0.2.1.4 released                                                          |
+| 3rd April 2024   | **cmpfs.Ruby** 0.2.1.3 released                                                          |
+| 2nd April 2024   | **cmpfs.Ruby** 0.2.1.2 released                                                          |
+| 2nd April 2024   | **cmpfs.Ruby** 0.2.1.1 released                                                          |
+| 11th April 2019  | **cmpfs.Ruby** 0.2.1 released                                                            |
+| 13th March 2019  | **cmpfs.Ruby** 0.2.0 released                                                            |
+| 13th March 2019  | **cmpfs.Ruby** 0.1.0 released                                                            |
+| 12th March 2019  | **cmpfs.Ruby** 0.0.1 released                                                            |
+| 12th March 2019  | **cmpfs.Ruby** 0.0.0 released                                                            |
+
+
+<!-- ########################### end of file ########################### -->
diff --git a/README.md b/README.md
index 06ad37a..4fe1341 100644
--- a/README.md
+++ b/README.md
@@ -3,6 +3,7 @@
 **Com**pare **F**ile-**S**ystem entities, for **Ruby**
 
 [![Gem Version](https://badge.fury.io/rb/cmpfs-ruby.svg)](https://badge.fury.io/rb/cmpfs-ruby)
+[![Ruby](https://github.com/synesissoftware/cmpfs.Ruby/actions/workflows/ruby.yml/badge.svg)](https://github.com/synesissoftware/cmpfs.Ruby/actions/workflows/ruby.yml)
 
 
 ## Introduction
@@ -157,7 +158,7 @@ Defect reports, feature requests, and pull requests are welcome on https://githu
 
 ### Related projects
 
-T.B.C.
+* C/C++ **cmpfs** — same product idea (binary/text file and stream comparison); recovery into freelibs is planned beside this gem (not yet published as a sibling tree here);
 
 
 ### License
diff --git a/Rakefile b/Rakefile
new file mode 100644
index 0000000..424b0b7
--- /dev/null
+++ b/Rakefile
@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Rakefile for cmpfs.Ruby
+
+require 'rake/testtask'
+
+
+Rake::TestTask.new do |tt|
+
+  tt.libs << 'lib'
+  tt.libs << 'test'
+  tt.name = 'test'
+  tt.test_files = FileList['test/**/tc_*.rb']
+  tt.verbose = true
+end
+
+
+task :default => :test
+
+
+# ############################## end of file ############################# #
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..6529292
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,23 @@
+# cmpfs.Ruby - Security <!-- omit in toc -->
+
+
+## Table of Contents <!-- omit in toc -->
+
+- [Reporting a vulnerability](#reporting-a-vulnerability)
+- [Supported versions](#supported-versions)
+
+
+## Reporting a vulnerability
+
+Please report security issues privately via GitHub Security Advisories on https://github.com/synesissoftware/cmpfs.Ruby/security, or by opening an issue if an advisory cannot be filed. Do not attach exploit proofs of concept against third-party systems.
+
+
+## Supported versions
+
+| Version | Supported |
+| ------- | --------- |
+| 0.2.x   | ✅        |
+| < 0.2   | ❌        |
+
+
+<!-- ########################### end of file ########################### -->
diff --git a/TODO.md b/TODO.md
new file mode 100644
index 0000000..94d7dbe
--- /dev/null
+++ b/TODO.md
@@ -0,0 +1,19 @@
+# cmpfs.Ruby - TODO <!-- omit in toc -->
+
+
+## Functional improvements
+
+* \<none>
+
+
+## Performance improvements
+
+* \<none>
+
+
+## Packaging improvements
+
+* [ ] Rename gemspec so the filename stem matches `spec.name` (`cmpfs.gemspec` → **cmpfs-ruby.gemspec**);
+
+
+<!-- ########################### end of file ########################### -->
diff --git a/build_gem.cmd b/build_gem.cmd
new file mode 100644
index 0000000..c894c21
--- /dev/null
+++ b/build_gem.cmd
@@ -0,0 +1,13 @@
+@ECHO OFF
+
+REM ########################################################################
+REM File:     build_gem.cmd
+REM
+REM Purpose:  Builds the gem
+REM
+REM Created:  11th July 2016
+REM Updated:  14th August 2026
+REM
+REM ########################################################################
+
+FOR %%f IN (*.gemspec) DO gem build "%%f" %*
diff --git a/build_gem.sh b/build_gem.sh
index 479b6db..864823e 100755
--- a/build_gem.sh
+++ b/build_gem.sh
@@ -6,9 +6,8 @@
 # Purpose:  Builds the gem
 #
 # Created:  9th June 2016
-# Updated:  1st April 2024
+# Updated:  14th August 2026
 #
 #############################################################################
 
-gem build cmpfs.gemspec $*
-
+gem build *.gemspec $*
diff --git a/cmpfs.gemspec b/cmpfs.gemspec
index 49a8739..5f3b3bc 100644
--- a/cmpfs.gemspec
+++ b/cmpfs.gemspec
@@ -4,45 +4,48 @@
 # Purpose:  Gemspec for cmpfs.Ruby library
 #
 # Created:  1st March 2019
-# Updated:  4th April 2024
+# Updated:  15th August 2026
 #
 # ######################################################################### #
 
 
 $:.unshift File.join(File.dirname(__FILE__), 'lib')
 
-require 'cmpfs'
+require 'cmpfs/version'
 
-require 'date'
 
 Gem::Specification.new do |spec|
 
   spec.name         = 'cmpfs-ruby'
   spec.version      = CmpFS::VERSION
-  spec.date         = Date.today.to_s
   spec.summary      = 'CmpFS.Ruby'
   spec.description  = <<END_DESC
 Compare File-System entities, for Ruby is a library that provides comparison
 functions for file-system entities - files and streams - including binary and
 filtering textual comparisons.
 END_DESC
-  spec.authors      = [ 'Matt Wilson' ]
-  spec.email        = 'matthew@synesis.com.au'
-  spec.homepage     = 'http://github.com/synesissoftware/cmpfs.Ruby'
+
+  spec.authors      = [
+    'Matt Wilson',
+  ]
+  spec.email        = [
+    'matthew@synesis.com.au',
+  ]
+  spec.homepage     = 'https://github.com/synesissoftware/cmpfs.Ruby'
   spec.license      = 'BSD-3-Clause'
   spec.files        = Dir[ 'Rakefile', '{bin,examples,lib,man,spec,test}/**/*', 'README*', 'LICENSE*' ] & `git ls-files -z`.split("\0")
 
-  if RUBY_VERSION >= '2'
-
-    spec.required_ruby_version = '>= 2'
-  else
+  spec.required_ruby_version = [ '>= 1.9.3' ]
 
-    spec.required_ruby_version = [ '~> 1.9', '>= 1.9.3' ]
-  end
+  spec.metadata = {
+    'bug_tracker_uri' => 'https://github.com/synesissoftware/cmpfs.Ruby/issues',
+    'changelog_uri' => 'https://github.com/synesissoftware/cmpfs.Ruby/blob/master/CHANGES.md',
+    'homepage_uri' => 'https://github.com/synesissoftware/cmpfs.Ruby',
+    'source_code_uri' => 'https://github.com/synesissoftware/cmpfs.Ruby',
+  }
 
-  spec.add_development_dependency 'xqsr3', [ '~> 0.39', '>= 0.39.1' ]
+  spec.add_development_dependency "xqsr3", [ '>= 0.39.5', '< 1.0' ]
 end
 
 
 # ############################## end of file ############################# #
-
diff --git a/examples/compare_two_binary_files.md b/examples/compare_two_binary_files.md
new file mode 100644
index 0000000..4e19c8c
--- /dev/null
+++ b/examples/compare_two_binary_files.md
@@ -0,0 +1,57 @@
+# cmpfs.Ruby - Example - **compare_two_binary_files**
+
+## Summary
+
+Compares two files for binary equality via `compare_binary`.
+
+
+## Source
+
+```ruby
+#! /usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), '../lib')
+
+
+require 'cmpfs'
+
+
+include CmpFS
+
+
+# command-line handling
+
+lhs_path, rhs_path =
+case ARGV.size
+when 0, 1
+
+  if '--help' == ARGV[0]
+
+    $stdout.puts "#$0: <lhs-path> <rhs-path>"
+
+    exit 0
+  end
+
+  abort "#$0: not enough arguments; use --help for usage"
+when 2
+
+  ARGV[0..2]
+else
+
+  abort "#$0: too many arguments; use --help for usage"
+end
+
+
+# main()
+
+
+$stdout.puts "binary comparison of '#{lhs_path}' with '#{rhs_path}':"
+
+$stdout.puts "files are #{compare_binary(lhs_path, rhs_path) ? '' : 'not '}equal"
+
+
+# ############################## end of file ############################# #
+```
+
+
+<!-- ########################### end of file ########################### -->
diff --git a/examples/compare_two_text_files.md b/examples/compare_two_text_files.md
new file mode 100644
index 0000000..c72a1d5
--- /dev/null
+++ b/examples/compare_two_text_files.md
@@ -0,0 +1,57 @@
+# cmpfs.Ruby - Example - **compare_two_text_files**
+
+## Summary
+
+Compares two files for text equality via `compare_text`, skipping blank lines and trimming lines.
+
+
+## Source
+
+```ruby
+#! /usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), '../lib')
+
+
+require 'cmpfs'
+
+
+include CmpFS
+
+
+# command-line handling
+
+lhs_path, rhs_path =
+case ARGV.size
+when 0, 1
+
+  if '--help' == ARGV[0]
+
+    $stdout.puts "#$0: <lhs-path> <rhs-path>"
+
+    exit 0
+  end
+
+  abort "#$0: not enough arguments; use --help for usage"
+when 2
+
+  ARGV[0..2]
+else
+
+  abort "#$0: too many arguments; use --help for usage"
+end
+
+
+# main()
+
+
+$stdout.puts "text comparison of '#{lhs_path}' with '#{rhs_path}':"
+
+$stdout.puts "files are #{compare_text(lhs_path, rhs_path, skip_blank_lines: true, trim_lines: true) ? '' : 'not '}equal"
+
+
+# ############################## end of file ############################# #
+```
+
+
+<!-- ########################### end of file ########################### -->
diff --git a/generate_rdoc.cmd b/generate_rdoc.cmd
new file mode 100644
index 0000000..4f6f7ad
--- /dev/null
+++ b/generate_rdoc.cmd
@@ -0,0 +1,28 @@
+@ECHO OFF
+
+REM ########################################################################
+REM File:     generate_rdoc.cmd
+REM
+REM Purpose:  Generates documentation
+REM
+REM Created:  14th August 2026
+REM Updated:  14th August 2026
+REM
+REM ########################################################################
+
+IF EXIST doc RMDIR /S /Q doc
+rdoc ^
+  -x build_gem.cmd ^
+  -x build_gem.sh ^
+  -x generate_rdoc.cmd ^
+  -x generate_rdoc.sh ^
+  -x run_all_unit_tests.sh ^
+  -x *.gemspec ^
+  -x doc/ ^
+  -x gems/ ^
+  -x old-gems/ ^
+  -x test/performance/ ^
+  -x test/scratch/ ^
+  -x tc_.*\.rb ^
+  -x ts_all.rb ^
+  %*
diff --git a/generate_rdoc.sh b/generate_rdoc.sh
new file mode 100755
index 0000000..e7dc865
--- /dev/null
+++ b/generate_rdoc.sh
@@ -0,0 +1,31 @@
+#! /bin/bash
+
+#############################################################################
+# File:     generate_rdoc.sh
+#
+# Purpose:  Generates documentation
+#
+# Created:  11th June 2016
+# Updated:  14th August 2026
+#
+#############################################################################
+
+rm -rfd doc
+rdoc \
+  -x build_gem.cmd \
+  -x build_gem.sh \
+  -x generate_rdoc.cmd \
+  -x generate_rdoc.sh \
+  -x run_all_unit_tests.sh \
+  -x *.gemspec \
+  \
+  -x doc/ \
+  -x gems/ \
+  -x old-gems/ \
+  -x test/performance/ \
+  -x test/scratch/ \
+  \
+  -x tc_.*\.rb \
+  -x ts_all.rb \
+  \
+  $*
diff --git a/lib/cmpfs.rb b/lib/cmpfs.rb
index ceef4d5..83b0648 100644
--- a/lib/cmpfs.rb
+++ b/lib/cmpfs.rb
@@ -1,11 +1,11 @@
-
+# frozen_string_literal: true
 # ######################################################################## #
 # File:     cmpfs.rb
 #
 # Purpose:  Primary require for cmpfs.Ruby library
 #
 # Created:  1st March 2019
-# Updated:  2nd April 2024
+# Updated:  15th August 2026
 #
 # Home:     http://github.com/synesissoftware/cmpfs.Ruby
 #
diff --git a/lib/cmpfs/compare.rb b/lib/cmpfs/compare.rb
index cb0d2b2..b41b3f7 100644
--- a/lib/cmpfs/compare.rb
+++ b/lib/cmpfs/compare.rb
@@ -1,11 +1,11 @@
-
+# frozen_string_literal: true
 # ######################################################################## #
 # File:     cmpfs/version.rb
 #
 # Purpose:  Version for cmpfs.Ruby library
 #
 # Created:  1st March 2019
-# Updated:  2nd April 2024
+# Updated:  15th August 2026
 #
 # Home:     http://github.com/synesissoftware/cmpfs.Ruby
 #
diff --git a/lib/cmpfs/compare/api_1_9.rb b/lib/cmpfs/compare/api_1_9.rb
index 1b668d6..c1fe500 100644
--- a/lib/cmpfs/compare/api_1_9.rb
+++ b/lib/cmpfs/compare/api_1_9.rb
@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 
 if RUBY_VERSION >= '2'
 
diff --git a/lib/cmpfs/compare/api_2.rb b/lib/cmpfs/compare/api_2.rb
index 8b70c1d..7e01d80 100644
--- a/lib/cmpfs/compare/api_2.rb
+++ b/lib/cmpfs/compare/api_2.rb
@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 
 unless RUBY_VERSION >= '2'
 
diff --git a/lib/cmpfs/compare/binary/internal_.rb b/lib/cmpfs/compare/binary/internal_.rb
index bd347d5..7f3865e 100644
--- a/lib/cmpfs/compare/binary/internal_.rb
+++ b/lib/cmpfs/compare/binary/internal_.rb
@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 
 require 'fileutils'
 require 'stringio'
diff --git a/lib/cmpfs/compare/text/internal_.rb b/lib/cmpfs/compare/text/internal_.rb
index 20b1098..3e5ba1c 100644
--- a/lib/cmpfs/compare/text/internal_.rb
+++ b/lib/cmpfs/compare/text/internal_.rb
@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 
 require 'fileutils'
 require 'stringio'
diff --git a/lib/cmpfs/version.rb b/lib/cmpfs/version.rb
index 7ba3bd9..ee6f778 100644
--- a/lib/cmpfs/version.rb
+++ b/lib/cmpfs/version.rb
@@ -1,17 +1,17 @@
-
+# frozen_string_literal: true
 # ######################################################################## #
 # File:     cmpfs/version.rb
 #
 # Purpose:  Version for cmpfs.Ruby library
 #
 # Created:  1st March 2019
-# Updated:  4th April 2024
+# Updated:  15th August 2026
 #
 # Home:     http://github.com/synesissoftware/cmpfs.Ruby
 #
 # Author:   Matthew Wilson
 #
-# Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
+# Copyright (c) 2019-2026, Matthew Wilson and Synesis Information Systems
 # Copyright (c) 2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
@@ -51,7 +51,7 @@
 module CmpFS
 
   # Current version of the cmpfs.Ruby library
-  VERSION           = '0.2.3'
+  VERSION           = '0.2.4'
 
   private
   VERSION_PARTS_    = VERSION.split(/[.]/).collect { |n| n.to_i } # :nodoc:
diff --git a/run_all_unit_tests.sh b/run_all_unit_tests.sh
index 76ca314..6aea55b 100755
--- a/run_all_unit_tests.sh
+++ b/run_all_unit_tests.sh
@@ -4,12 +4,13 @@
 # File:     run_all_unit_tests.sh
 #
 # Purpose:  Executes the unit-tests of a Ruby project regardless of
-#           calling directory
+#           calling directory, allowing use of debug mode, warnings, and
+#           executing each rbenv version
 #
 # Created:  9th June 2011
-# Updated:  2nd April 2024
+# Updated:  12th August 2026
 #
-# Copyright (c) Matthew Wilson, 2011-2024
+# Copyright (c) Matthew Wilson, 2011-2026
 # All rights reserved
 #
 # Redistribution and use in source and binary forms, with or without
@@ -47,128 +48,137 @@
 Source="${BASH_SOURCE[0]}"
 while [ -h "$Source" ]; do
 
-  Dir="$(cd -P "$(dirname "$Source")" && pwd)"
+  ScriptDir="$(cd -P "$(dirname "$Source")" && pwd)"
   Source="$(readlink "$Source")"
-  [[ $Source != /* ]] && Source="$Dir/$Source"
+  [[ $Source != /* ]] && Source="$ScriptDir/$Source"
 done
-Dir="$(cd -P "$( dirname "$Source" )" && pwd)"
+ScriptDir="$(cd -P "$( dirname "$Source" )" && pwd)"
+Basename="$(basename "$Source")"
 
 
 # colours
 
 if command -v tput > /dev/null; then
 
-  RbEnvClr_Blue=${FG_BLUE:-$(tput setaf 4)}
-  RbEnvClr_Red=${FG_BLUE:-$(tput setaf 1)}
-  RbEnvClr_Bold=${FD_BOLD:-$(tput bold)}
-  RbEnvClr_None=${FD_NONE:-$(tput sgr0)}
+  SisClr_Blue=${FG_BLUE:-$(tput setaf 4)}
+  SisClr_Red=${FG_RED:-$(tput setaf 1)}
+  SisClr_Bold=${FD_BOLD:-$(tput bold)}
+  SisClr_None=${FD_NONE:-$(tput sgr0)}
 else
 
-  RbEnvClr_Blue=
-  RbEnvClr_Red=
-  RbEnvClr_Bold=
-  RbEnvClr_None=
+  SisClr_Blue=
+  SisClr_Red=
+  SisClr_Bold=
+  SisClr_None=
 fi
 
 
-# special command-line handling ('--rbenv-versions')
-# rbenv handling
+# special command-line handling ('--pwd', '--rbenv-versions')
 
+ProjectDir="$ScriptDir"
+ForwardArgs=()
+FoundHelp=
 RunRbEnvAllVersions=
-Arguments=
 
 for arg in "$@"
 do
 
   case "$arg" in
 
-    --rbenv-versions)
+  --help)
 
-      RunRbEnvAllVersions=1
-      ;;
-    *)
+    FoundHelp=1
+    ForwardArgs+=("$arg")
+    ;;
+  --pwd)
 
-      Arguments="$Arguments $arg"
-      ;;
+    ProjectDir=$(pwd)
+    ForwardArgs+=("$arg")
+    ;;
+  --rbenv-versions)
+
+    RunRbEnvAllVersions=1
+    ;;
+  *)
+
+    ForwardArgs+=("$arg")
+    ;;
   esac
 done
 
-if [ ! -z "$RunRbEnvAllVersions" ]; then
+if [ ! -z "$FoundHelp" ]; then
 
-  if ! command -v rbenv > /dev/null; then
-
-    >&2 echo "$0: ${RbEnvClr_Red}${RbEnvClr_Bold}rbenv${RbEnvClr_None} not detected"
+  RunRbEnvAllVersions=
+fi
 
-    exit 1
-  fi
+if [ ! -z "$RunRbEnvAllVersions" ]; then
 
-  if [ ! -e "$Dir/.ruby-version" ];then
+  if ! command -v rbenv > /dev/null; then
 
-    >&2 echo "$0: ${RbEnvClr_Red}${RbEnvClr_Bold}.ruby-version${RbEnvClr_None} file not detected"
+  >&2 echo "$0: ${SisClr_Red}${SisClr_Bold}rbenv${SisClr_None} not detected"
 
-    exit 1
+  exit 1
   fi
 
   exclusions=()
-  if [ -e "$Dir/.ruby-version-exclusions" ]; then
+  if [ -e "$ProjectDir/.ruby-version-exclusions" ]; then
 
-    exclusion_lines=`cat "$Dir/.ruby-version-exclusions"`
-    for line in $exclusion_lines; do
+  exclusion_lines=`cat "$ProjectDir/.ruby-version-exclusions"`
+  for line in $exclusion_lines; do
 
-      exclusions+=($line)
-    done
+    exclusions+=("$line")
+  done
   fi
 
-  echo "executing command line '${RbEnvClr_Blue}${RbEnvClr_Bold}$0 $Arguments${RbEnvClr_None}' with all Ruby versions ..."
+  echo "executing command line '${SisClr_Blue}${SisClr_Bold}$0 ${ForwardArgs[*]}${SisClr_None}' with all Ruby versions ..."
 
-  current=$(rbenv local)
+  current=
+  if [ -f "$ProjectDir/.ruby-version" ]; then
 
-  #echo "current version: $current"
+    current=$(tr -d '[:space:]' < "$ProjectDir/.ruby-version")
+  fi
 
   versions=()
   while IFS= read -r line; do
 
-    versions+=("$line")
+  versions+=("$line")
   done < <(rbenv versions --bare)
 
-  echo "versions: ${RbEnvClr_Blue}${RbEnvClr_Bold}${versions[*]}${RbEnvClr_None}; skipped versions: ${RbEnvClr_Blue}${RbEnvClr_Bold}${exclusions[*]}${RbEnvClr_None}; current version: ${RbEnvClr_Blue}${RbEnvClr_Bold}${current}${RbEnvClr_None}"
+  echo "versions: ${SisClr_Blue}${SisClr_Bold}${versions[*]}${SisClr_None}; skipped versions: ${SisClr_Blue}${SisClr_Bold}${exclusions[*]}${SisClr_None}; current version: ${SisClr_Blue}${SisClr_Bold}${current:-(none)}${SisClr_None}"
 
   result=0
 
-  for version in ${versions[@]}
+  for version in "${versions[@]}"
   do
 
-    echo
+  echo
 
-    skip=
+  skip=
 
-    for exclusion in "${exclusions[@]}"; do
+  for exclusion in "${exclusions[@]}"; do
 
-      if [[ "$exclusion" == "$version" ]]; then
+    if [[ "$exclusion" == "$version" ]]; then
 
-        skip=1
-      fi
-    done
+    skip=1
+    fi
+  done
 
-    if [ "$skip" != "" ]; then
+  if [ "$skip" != "" ]; then
 
-      echo "skipping Ruby version ${RbEnvClr_Blue}${RbEnvClr_Bold}$version${RbEnvClr_None}:"
-    else
+    echo "skipping Ruby version ${SisClr_Blue}${SisClr_Bold}$version${SisClr_None}:"
+  else
 
-      echo "processing Ruby version ${RbEnvClr_Blue}${RbEnvClr_Bold}$version${RbEnvClr_None}:"
+    echo "processing Ruby version ${SisClr_Blue}${SisClr_Bold}$version${SisClr_None}:"
 
-      echo -e "\texecuting command line '$0 $Arguments' with Ruby version $version ..."
-      rbenv local $version
+    echo -e "\texecuting command line 'RBENV_VERSION=$version $0 ${ForwardArgs[*]}' with Ruby version $version ..."
 
-      if ! $0 $Arguments; then
+    if ! RBENV_VERSION="$version" "$0" "${ForwardArgs[@]}"; then
 
-        result=1
-      fi
+    result=1
     fi
+  fi
   done
 
-  rbenv local $current
-
   exit $result
 fi
 
@@ -177,6 +187,8 @@ fi
 
 Separate=
 DebugFlag=
+PrependLib=
+WarningsFlag=-W0
 
 for v in "$@"
 do
@@ -187,52 +199,93 @@ do
 
       DebugFlag=--debug
       ;;
-
     --help)
 
-      echo "USAGE: $Source { | --help | [ --debug ] [ --separate ] }"
-      echo
-      echo "flags:"
-      echo
-      echo "  --help"
-      echo "    shows this help and terminates"
-      echo
-      echo "  --debug"
-      echo "    executes Ruby interpreter in debug mode"
-      echo
-      echo "  --rbenv-versions"
-      echo "    executes this script (with all other specified arguments) for each rbenv version (except those listed in the file .ruby-version-exclusions, if present)"
-      echo
-      echo "  --separate"
-      echo "    executes each unit-test in a separate program"
-      echo
-
-      exit
+      cat << EOF
+USAGE: $Basename { | --help | [ --debug ] [ --lib ] [ --pwd ] [ --rbenv-versions ] [ --separate ] [ --warnings ]}
+
+flags:
+
+  --help
+  shows this help and terminates
+
+  --debug
+  executes Ruby interpreter in debug mode
+
+  --lib
+  prepends the lib directory under the script's directory into RUBYLIB before executing
+
+  --pwd
+  executes from present working directory, rather than relative to the script directory
+
+  --rbenv-versions
+  executes this script (with all other specified arguments) for each rbenv version (except those listed in the file .ruby-version-exclusions, if present)
+
+  --separate
+  executes each unit-test in a separate program
+
+  --warnings
+  executes Ruby interpreter in warnings mode
+EOF
+
+      exit 0
+      ;;
+    --lib)
+
+      PrependLib=1
       ;;
+    --pwd)
 
+      # already-processed as special case above
+      ;;
+    --rbenv-versions)
+
+      # already-processed as special case above
+      ;;
     --separate)
 
       Separate=true
       ;;
+    --warnings|--warn)
 
+      WarningsFlag=-W2 #-W:performance
+      ;;
     *)
 
-      echo "unrecognised argument; use --help for usage"
+      >&2 echo "unrecognised argument '$v'; use --help for usage"
 
       exit 1
       ;;
   esac
 done
 
+
 # executing tests
 
+if [ ! -z "$PrependLib" ]; then
+
+  export RUBYLIB=$ProjectDir/lib:$RUBYLIB
+fi
+
+
 if [ -z "$Separate" ]; then
 
-  ruby $DebugFlag "$Dir/test/unit/ts_all.rb"
+  ruby $DebugFlag $WarningsFlag "$ProjectDir/test/unit/ts_all.rb"
 else
 
-  find "$Dir" -name 'tc_*.rb' -exec ruby $DebugFlag {} \;
+  result=0
+
+  while IFS= read -r -d '' testfile; do
+
+    if ! ruby $DebugFlag $WarningsFlag "$testfile"; then
+
+      result=1
+    fi
+  done < <(find "$ProjectDir" -name 'tc_*.rb' -print0)
+
+  exit $result
 fi
 
+
 # ############################## end of file ############################# #
 

From da6e91e48df55cc4bf57657208c33774117daf15 Mon Sep 17 00:00:00 2001
From: synesissoftware <matthew@synesis.com.au>
Date: Thu, 27 Aug 2026 17:24:28 +1000
Subject: [PATCH 2/3] 0.2.5 (#2)

* **run_all_unit_tests.sh** : ~ updated to latest (from https://github.com/synesissoftware/misc-dev-scripts)

* boilerplate: markdown files

* boilerplate: .gitattributes

* boilerplate: LICENSE

* boilerplate: .vscode/settings.json

* boilerplate: .vimrc

* boilerplate: build_gem.cmd, build_gem.sh, generate_rdoc.cmd, generate_rdoc.sh

* boilerplate: LICENSE

* bolierplate: updating Gemfile

* boilerplate: placeholder markdown files

* chore: removed .ruby-version from repository

* boilerplate: .gitignore

* version dependencies

* boilerplate: .ruby-version-exclusions

* Add canonical AUTHORS, FAQ, NEWS, and TODO markdown skeletons

* Fill CHANGES.md from release tags and git history

* Add ruby.yml CI badge and switch Gemfile to gemspec

* chore: dependencies

* gemspec updates

* chore: AUTHORS.md

* fix: gemspec metadata

* added/updated Rakefile

* chore: CONTRIBUTING.md, INSTALL.md, SECURITY.md

* chore: rake in Gemfile

* fix: Add frozen lib/ strings and standardise Ruby gem boilerplate

* standard CI for all projects

* standard .editorconfig and dependabot for all projects

* TODO.md

* examples

* CHANGES.md

* NEWS.md

* README.md

* spacing

* 0.2.5

* TODO.md
---
 .github/workflows/ruby.yml          | 21 +++++--
 .gitignore                          |  8 +++
 CHANGES.md                          | 12 ++++
 EXAMPLES.md                         |  8 +--
 Gemfile                             |  7 +++
 Gemfile.lock                        | 20 ------
 NEWS.md                             |  1 +
 README.md                           | 71 +++++++++++++++++++---
 TODO.md                             |  9 ++-
 cmpfs.gemspec => cmpfs-ruby.gemspec | 33 +++++++---
 lib/cmpfs.rb                        |  4 +-
 lib/cmpfs/compare.rb                |  4 +-
 lib/cmpfs/version.rb                |  6 +-
 run_all_unit_tests.sh               | 94 ++++++++++++++++++-----------
 14 files changed, 210 insertions(+), 88 deletions(-)
 delete mode 100644 Gemfile.lock
 rename cmpfs.gemspec => cmpfs-ruby.gemspec (70%)

diff --git a/.github/workflows/ruby.yml b/.github/workflows/ruby.yml
index 6e63b88..a5e52a4 100644
--- a/.github/workflows/ruby.yml
+++ b/.github/workflows/ruby.yml
@@ -7,7 +7,7 @@
 
 #
 # Created: 15th August 2026
-# Updated: 15th August 2026
+# Updated: 19th August 2026
 #
 
 name: Ruby
@@ -70,13 +70,20 @@ jobs:
       uses: actions/checkout@v4
 
     - name: Remove Gemfile.lock
+      shell: bash
       run: rm -f Gemfile.lock
 
     - name: Set up Ruby v${{ matrix.ruby-version }}
       uses: ruby/setup-ruby@v1
       with:
         ruby-version: ${{ matrix.ruby-version }}
-        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+        # Bundler 4 honours Gemfile `lockfile false`, so no Gemfile.lock
+        # is written. bundler-cache cats that file after `bundle lock`
+        # and fails on Windows 3.2+ (setup-ruby installs Bundler ~> 4).
+        bundler-cache: false
+
+    - name: Install gems
+      run: bundle install
 
     - name: Show Ruby version
       run: ruby -v
@@ -87,7 +94,7 @@ jobs:
     - name: Gem build and install smoke
       shell: bash
       run: |
-        gem build cmpfs.gemspec
+        gem build cmpfs-ruby.gemspec
         gem install --local cmpfs-ruby-*.gem
         ruby -e "require 'cmpfs/version'; abort('VERSION missing') unless defined?(CmpFS::VERSION); puts CmpFS::VERSION"
 
@@ -102,13 +109,17 @@ jobs:
       uses: actions/checkout@v4
 
     - name: Remove Gemfile.lock
+      shell: bash
       run: rm -f Gemfile.lock
 
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: '3.3'
-        bundler-cache: true
+        ruby-version: '3.4'
+        bundler-cache: false
+
+    - name: Install gems
+      run: bundle install
 
     - name: Show Ruby version
       run: ruby -v
diff --git a/.gitignore b/.gitignore
index 0d510c3..14b3203 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,10 +2,13 @@
 
 /.bzr/
 /.bundle/
+/.bzr/
 /.config/
 /.svn/
+/.vscode/
 /.yardoc/
 
+/_build/
 /_yardoc/
 
 /InstalledFiles/
@@ -23,8 +26,10 @@
 /tmp/
 /vendor/bundle/
 
+
 # directories (by pattern)
 
+
 # files (by name)
 
 .DS_Store
@@ -32,8 +37,11 @@
 .ruby-version
 .rvmrc
 
+Gemfile.lock
+
 /spec/examples.txt
 
+
 # files (by pattern)
 
 *~
diff --git a/CHANGES.md b/CHANGES.md
index 457beeb..66909b9 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,6 +1,18 @@
 # cmpfs.Ruby - Changes <!-- omit in toc -->
 
 
+## 0.2.5 - 19th August 2026
+
+* renamed **cmpfs.gemspec** to **cmpfs-ruby.gemspec** so the filename stem matches `spec.name`;
+* **cmpfs-ruby.gemspec**: `spec.summary` matches the README tagline; packaged **AUTHORS**, **CHANGES**, **CONTRIBUTING**, **EXAMPLES**, **FAQ**, **INSTALL**, **NEWS**, **SECURITY**, and **TODO**; **Gemfile.lock** and **.ruby-version** excluded from `spec.files`;
+* stop tracking **Gemfile.lock**; **Gemfile** sets `lockfile false` when Bundler supports it; CI uses `bundler-cache: false` because Bundler 4 then writes no lockfile and **ruby/setup-ruby** cache cats **Gemfile.lock**;
+* CI **Warnings** job now runs on Ruby **3.4**; `gem build cmpfs-ruby.gemspec`;
+* updated **run_all_unit_tests.sh** (from https://github.com/synesissoftware/misc-dev-scripts) to skip **tput** when **$TERM** is unset or stdout is not a TTY;
+* reordered **README.md** (tagline before badges; TOC after badges), added Language / License / Last Commit badges and **Dependencies** (Efferent / Afferent);
+* **EXAMPLES.md** example links are repo-relative (`./examples/…`);
+* library source **Home:** URLs now use `https`;
+
+
 ## 0.2.4 - 15th August 2026
 
 * added `# frozen_string_literal: true` to all **lib/** sources;
diff --git a/EXAMPLES.md b/EXAMPLES.md
index e4f3fdb..0696942 100644
--- a/EXAMPLES.md
+++ b/EXAMPLES.md
@@ -1,9 +1,9 @@
 # cmpfs.Ruby - Examples <!-- omit in toc -->
 
-| Name                         | Source & Description                                                                                                                               | Summary                                                                              |
-| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
-| **compare_two_binary_files** | [examples/compare_two_binary_files.rb](/examples/compare_two_binary_files.rb)<br/>[examples/compare_two_binary_files.md](/examples/compare_two_binary_files.md) | Compares two files for binary equality via `compare_binary`                          |
-| **compare_two_text_files**   | [examples/compare_two_text_files.rb](/examples/compare_two_text_files.rb)<br/>[examples/compare_two_text_files.md](/examples/compare_two_text_files.md)     | Compares two files for text equality via `compare_text` (skip blank lines; trim)     |
+|Name|Source & Description|Summary|
+|---|---|---|
+|**compare_two_binary_files**|[examples/compare_two_binary_files.rb](./examples/compare_two_binary_files.rb)<br/>[examples/compare_two_binary_files.md](./examples/compare_two_binary_files.md)|Compares two files for binary equality via `compare_binary`|
+|**compare_two_text_files**|[examples/compare_two_text_files.rb](./examples/compare_two_text_files.rb)<br/>[examples/compare_two_text_files.md](./examples/compare_two_text_files.md)|Compares two files for text equality via `compare_text` (skip blank lines; trim)|
 
 
 <!-- ########################### end of file ########################### -->
diff --git a/Gemfile b/Gemfile
index 29f6d2e..79965e8 100644
--- a/Gemfile
+++ b/Gemfile
@@ -2,6 +2,13 @@
 
 source "https://rubygems.org"
 
+# Suppress lockfile on Bundler 4+ (gem: do not pin the graph). No-op on
+# Bundler that lacks the DSL (Ruby 2.x CI). Do not combine with
+# ruby/setup-ruby `bundler-cache: true` — that action cats Gemfile.lock
+# after `bundle lock` and fails when no file is written (Windows 3.2+,
+# where setup-ruby installs Bundler ~> 4).
+lockfile false if respond_to?(:lockfile)
+
 gemspec
 
 # rake 13 requires Ruby >= 2.3
diff --git a/Gemfile.lock b/Gemfile.lock
deleted file mode 100644
index 8d6765f..0000000
--- a/Gemfile.lock
+++ /dev/null
@@ -1,20 +0,0 @@
-PATH
-  remote: .
-  specs:
-    cmpfs-ruby (0.2.3)
-
-GEM
-  remote: https://rubygems.org/
-  specs:
-    xqsr3 (0.39.5)
-
-PLATFORMS
-  arm64-darwin-25
-  ruby
-
-DEPENDENCIES
-  cmpfs-ruby!
-  xqsr3 (~> 0.39, >= 0.39.1)
-
-BUNDLED WITH
-   2.6.9
diff --git a/NEWS.md b/NEWS.md
index af22b41..a1998bc 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -2,6 +2,7 @@
 
 | Date             | News Item                                                                                |
 | ---------------- | ---------------------------------------------------------------------------------------- |
+| 19th August 2026 | [**cmpfs.Ruby** 0.2.5](https://github.com/synesissoftware/cmpfs.Ruby/releases/tag/0.2.5) |
 | 15th August 2026 | [**cmpfs.Ruby** 0.2.4](https://github.com/synesissoftware/cmpfs.Ruby/releases/tag/0.2.4) |
 | 4th April 2024   | [**cmpfs.Ruby** 0.2.3](https://github.com/synesissoftware/cmpfs.Ruby/releases/tag/0.2.3) |
 | 4th April 2024   | **cmpfs.Ruby** 0.2.2.1 released                                                          |
diff --git a/README.md b/README.md
index 4fe1341..21abef8 100644
--- a/README.md
+++ b/README.md
@@ -2,15 +2,13 @@
 
 **Com**pare **F**ile-**S**ystem entities, for **Ruby**
 
+![Language](https://img.shields.io/badge/Ruby-CC342D?style=flat&logo=ruby&logoColor=white)
+[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
 [![Gem Version](https://badge.fury.io/rb/cmpfs-ruby.svg)](https://badge.fury.io/rb/cmpfs-ruby)
+[![Last Commit](https://img.shields.io/github/last-commit/synesissoftware/cmpfs.Ruby)](https://github.com/synesissoftware/cmpfs.Ruby/commits/master)
 [![Ruby](https://github.com/synesissoftware/cmpfs.Ruby/actions/workflows/ruby.yml/badge.svg)](https://github.com/synesissoftware/cmpfs.Ruby/actions/workflows/ruby.yml)
 
 
-## Introduction
-
-Provides platform-independent facilities for comparing file contents, for both binary and text files
-
-
 ## Table of Contents <!-- omit in toc -->
 
 - [Introduction](#introduction)
@@ -21,13 +19,38 @@ Provides platform-independent facilities for comparing file contents, for both b
   - [Where to get help](#where-to-get-help)
   - [Contribution guidelines](#contribution-guidelines)
   - [Dependencies](#dependencies)
+    - [Efferent (fan-out)](#efferent-fan-out)
+      - [Runtime Dependencies (aka "Normal Dependencies")](#runtime-dependencies-aka-normal-dependencies)
+      - [Development Dependencies](#development-dependencies)
+    - [Afferent (fan-in)](#afferent-fan-in)
+      - [Runtime dependents](#runtime-dependents)
+      - [Development dependents](#development-dependents)
   - [Related projects](#related-projects)
   - [License](#license)
 
 
+## Introduction
+
+**cmpfs.Ruby** provides platform-independent facilities for comparing file contents, for both binary and text files.
+
+It has **no dependencies** on any other non-standard library.
+
+
 ## Installation
 
-Install using `gem install cmpfs-ruby` or add it to your `Gemfile`.
+Install via **gem** as in:
+
+```
+gem install cmpfs-ruby
+```
+
+or add it to your `Gemfile`.
+
+Use via **require**, as in:
+
+```Ruby
+require 'cmpfs'
+```
 
 
 ## Components
@@ -46,6 +69,8 @@ all of which are obtained when `extend`ing or `include`ing the `CmpFS` module.
 
 ## Examples
 
+Examples are provided in the ```examples``` directory, along with a markdown description for each. A detailed list TOC of them is provided in [EXAMPLES.md](./EXAMPLES.md).
+
 **examples/compare_two_binary_files.rb**:
 ```Ruby
 #! /usr/bin/env ruby
@@ -143,6 +168,7 @@ $stdout.puts "files are #{compare_text(lhs_path, rhs_path, skip_blank_lines: tru
 
 ## Project Information
 
+
 ### Where to get help
 
 [GitHub Page](https://github.com/synesissoftware/cmpfs.Ruby "GitHub Page")
@@ -156,6 +182,38 @@ Defect reports, feature requests, and pull requests are welcome on https://githu
 ### Dependencies
 
 
+#### Efferent (fan-out)
+
+Libraries upon which **cmpfs.Ruby** depends:
+
+
+##### Runtime Dependencies (aka "Normal Dependencies")
+
+* \<none>;
+
+
+##### Development Dependencies
+
+* [**rake**](https://rubygems.org/gems/rake);
+* [**test-unit**](https://rubygems.org/gems/test-unit);
+* [**xqsr3**](https://github.com/synesissoftware/xqsr3);
+
+
+#### Afferent (fan-in)
+
+Projects that depend on **cmpfs.Ruby**:
+
+
+##### Runtime dependents
+
+* \<none>;
+
+
+##### Development dependents
+
+* \<none>;
+
+
 ### Related projects
 
 * C/C++ **cmpfs** — same product idea (binary/text file and stream comparison); recovery into freelibs is planned beside this gem (not yet published as a sibling tree here);
@@ -167,4 +225,3 @@ Defect reports, feature requests, and pull requests are welcome on https://githu
 
 
 <!-- ########################### end of file ########################### -->
-
diff --git a/TODO.md b/TODO.md
index 94d7dbe..c90fa18 100644
--- a/TODO.md
+++ b/TODO.md
@@ -3,7 +3,8 @@
 
 ## Functional improvements
 
-* \<none>
+* [ ] quiet assigned-but-unused variable warnings in **lib/cmpfs/compare/text/internal_.rb** (`lhs_ix`, `rhs_ix`, `lhs_nr`, `rhs_nr`; Ruby 3.4 `-W` / CI **Warnings** job);
+* [ ] quiet the ambiguous `/` regexp warning in **test/unit/tc_version.rb** (Ruby 3.4 `-W` / CI **Warnings** job);
 
 
 ## Performance improvements
@@ -13,7 +14,11 @@
 
 ## Packaging improvements
 
-* [ ] Rename gemspec so the filename stem matches `spec.name` (`cmpfs.gemspec` → **cmpfs-ruby.gemspec**);
+* [x] ~~~updated **run_all_unit_tests.sh** (from **misc-dev-scripts**) to skip `tput` when `$TERM` is unset or stdout is not a TTY~~~;
+* [x] ~~~**Gemfile** `lockfile false`; stop tracking **Gemfile.lock**; CI `bundler-cache: false`~~~;
+* [x] ~~~gemspec polish: README tagline as `spec.summary`, package docs, exclude **Gemfile.lock** / **.ruby-version**; renamed **cmpfs.gemspec** → **cmpfs-ruby.gemspec**~~~;
+* [x] ~~~README canonical structure (tagline before badges; **Dependencies**; CI badge → **ruby.yml**)~~~;
+* [x] ~~~after the packaging/boilerplate/CI baseline: bump **VERSION** and align **CHANGES**/**NEWS**~~~;
 
 
 <!-- ########################### end of file ########################### -->
diff --git a/cmpfs.gemspec b/cmpfs-ruby.gemspec
similarity index 70%
rename from cmpfs.gemspec
rename to cmpfs-ruby.gemspec
index 5f3b3bc..6dd0a07 100644
--- a/cmpfs.gemspec
+++ b/cmpfs-ruby.gemspec
@@ -1,12 +1,12 @@
-# ######################################################################### #
-# File:     cmpfs.gemspec
+# ######################################################################## #
+# File:     cmpfs-ruby.gemspec
 #
 # Purpose:  Gemspec for cmpfs.Ruby library
 #
 # Created:  1st March 2019
-# Updated:  15th August 2026
+# Updated:  19th August 2026
 #
-# ######################################################################### #
+# ######################################################################## #
 
 
 $:.unshift File.join(File.dirname(__FILE__), 'lib')
@@ -17,8 +17,8 @@ require 'cmpfs/version'
 Gem::Specification.new do |spec|
 
   spec.name         = 'cmpfs-ruby'
+  spec.summary      = 'Compare File-System entities, for Ruby'
   spec.version      = CmpFS::VERSION
-  spec.summary      = 'CmpFS.Ruby'
   spec.description  = <<END_DESC
 Compare File-System entities, for Ruby is a library that provides comparison
 functions for file-system entities - files and streams - including binary and
@@ -33,7 +33,6 @@ END_DESC
   ]
   spec.homepage     = 'https://github.com/synesissoftware/cmpfs.Ruby'
   spec.license      = 'BSD-3-Clause'
-  spec.files        = Dir[ 'Rakefile', '{bin,examples,lib,man,spec,test}/**/*', 'README*', 'LICENSE*' ] & `git ls-files -z`.split("\0")
 
   spec.required_ruby_version = [ '>= 1.9.3' ]
 
@@ -44,7 +43,27 @@ END_DESC
     'source_code_uri' => 'https://github.com/synesissoftware/cmpfs.Ruby',
   }
 
-  spec.add_development_dependency "xqsr3", [ '>= 0.39.5', '< 1.0' ]
+  spec.files = Dir[
+    'Rakefile',
+    '{bin,examples,lib,man,spec,test}/**/*',
+    'AUTHORS*',
+    'CHANGES*',
+    'CONTRIBUTING*',
+    'EXAMPLES*',
+    'FAQ*',
+    'INSTALL*',
+    'LICENSE*',
+    'NEWS*',
+    'README*',
+    'SECURITY*',
+    'TODO*',
+  ] & `git ls-files -z`.split("\0")
+  spec.files -= [
+    '.ruby-version',
+    'Gemfile.lock',
+  ]
+
+  spec.add_development_dependency 'xqsr3', [ '>= 0.39.5', '< 1.0' ]
 end
 
 
diff --git a/lib/cmpfs.rb b/lib/cmpfs.rb
index 83b0648..68c6f36 100644
--- a/lib/cmpfs.rb
+++ b/lib/cmpfs.rb
@@ -5,9 +5,9 @@
 # Purpose:  Primary require for cmpfs.Ruby library
 #
 # Created:  1st March 2019
-# Updated:  15th August 2026
+# Updated:  19th August 2026
 #
-# Home:     http://github.com/synesissoftware/cmpfs.Ruby
+# Home:     https://github.com/synesissoftware/cmpfs.Ruby
 #
 # Author:   Matthew Wilson
 #
diff --git a/lib/cmpfs/compare.rb b/lib/cmpfs/compare.rb
index b41b3f7..13ae5d2 100644
--- a/lib/cmpfs/compare.rb
+++ b/lib/cmpfs/compare.rb
@@ -5,9 +5,9 @@
 # Purpose:  Version for cmpfs.Ruby library
 #
 # Created:  1st March 2019
-# Updated:  15th August 2026
+# Updated:  19th August 2026
 #
-# Home:     http://github.com/synesissoftware/cmpfs.Ruby
+# Home:     https://github.com/synesissoftware/cmpfs.Ruby
 #
 # Author:   Matthew Wilson
 #
diff --git a/lib/cmpfs/version.rb b/lib/cmpfs/version.rb
index ee6f778..e62913c 100644
--- a/lib/cmpfs/version.rb
+++ b/lib/cmpfs/version.rb
@@ -5,9 +5,9 @@
 # Purpose:  Version for cmpfs.Ruby library
 #
 # Created:  1st March 2019
-# Updated:  15th August 2026
+# Updated:  19th August 2026
 #
-# Home:     http://github.com/synesissoftware/cmpfs.Ruby
+# Home:     https://github.com/synesissoftware/cmpfs.Ruby
 #
 # Author:   Matthew Wilson
 #
@@ -51,7 +51,7 @@
 module CmpFS
 
   # Current version of the cmpfs.Ruby library
-  VERSION           = '0.2.4'
+  VERSION           = '0.2.5'
 
   private
   VERSION_PARTS_    = VERSION.split(/[.]/).collect { |n| n.to_i } # :nodoc:
diff --git a/run_all_unit_tests.sh b/run_all_unit_tests.sh
index 6aea55b..0a05634 100755
--- a/run_all_unit_tests.sh
+++ b/run_all_unit_tests.sh
@@ -8,7 +8,7 @@
 #           executing each rbenv version
 #
 # Created:  9th June 2011
-# Updated:  12th August 2026
+# Updated:  19th August 2026
 #
 # Copyright (c) Matthew Wilson, 2011-2026
 # All rights reserved
@@ -58,18 +58,20 @@ Basename="$(basename "$Source")"
 
 # colours
 
-if command -v tput > /dev/null; then
+SisClr_Blue=${FG_BLUE:-}
+SisClr_Red=${FG_RED:-}
+SisClr_Bold=${FD_BOLD:-}
+SisClr_None=${FD_NONE:-}
 
-  SisClr_Blue=${FG_BLUE:-$(tput setaf 4)}
-  SisClr_Red=${FG_RED:-$(tput setaf 1)}
-  SisClr_Bold=${FD_BOLD:-$(tput bold)}
-  SisClr_None=${FD_NONE:-$(tput sgr0)}
-else
+if [ -n "${TERM:-}" ] && [ -t 1 ] && command -v tput >/dev/null 2>&1; then
+
+  if tput sgr0 >/dev/null 2>&1; then
 
-  SisClr_Blue=
-  SisClr_Red=
-  SisClr_Bold=
-  SisClr_None=
+    SisClr_Blue=${FG_BLUE:-$(tput setaf 4)}
+    SisClr_Red=${FG_RED:-$(tput setaf 1)}
+    SisClr_Bold=${FD_BOLD:-$(tput bold)}
+    SisClr_None=${FD_NONE:-$(tput sgr0)}
+  fi
 fi
 
 
@@ -115,19 +117,19 @@ if [ ! -z "$RunRbEnvAllVersions" ]; then
 
   if ! command -v rbenv > /dev/null; then
 
-  >&2 echo "$0: ${SisClr_Red}${SisClr_Bold}rbenv${SisClr_None} not detected"
+    >&2 echo "$0: ${SisClr_Red}${SisClr_Bold}rbenv${SisClr_None} not detected"
 
-  exit 1
+    exit 1
   fi
 
   exclusions=()
   if [ -e "$ProjectDir/.ruby-version-exclusions" ]; then
 
-  exclusion_lines=`cat "$ProjectDir/.ruby-version-exclusions"`
-  for line in $exclusion_lines; do
+    exclusion_lines=`cat "$ProjectDir/.ruby-version-exclusions"`
+    for line in $exclusion_lines; do
 
-    exclusions+=("$line")
-  done
+      exclusions+=("$line")
+    done
   fi
 
   echo "executing command line '${SisClr_Blue}${SisClr_Bold}$0 ${ForwardArgs[*]}${SisClr_None}' with all Ruby versions ..."
@@ -138,11 +140,20 @@ if [ ! -z "$RunRbEnvAllVersions" ]; then
     current=$(tr -d '[:space:]' < "$ProjectDir/.ruby-version")
   fi
 
+  if ! version_output=$(rbenv versions --bare); then
+
+    >&2 echo "$0: ${SisClr_Red}${SisClr_Bold}failed to enumerate Ruby versions via rbenv${SisClr_None}"
+    exit 1
+  fi
+
   versions=()
-  while IFS= read -r line; do
+  if [ -n "$version_output" ]; then
 
-  versions+=("$line")
-  done < <(rbenv versions --bare)
+    while IFS= read -r line; do
+
+      versions+=("$line")
+    done <<< "$version_output"
+  fi
 
   echo "versions: ${SisClr_Blue}${SisClr_Bold}${versions[*]}${SisClr_None}; skipped versions: ${SisClr_Blue}${SisClr_Bold}${exclusions[*]}${SisClr_None}; current version: ${SisClr_Blue}${SisClr_Bold}${current:-(none)}${SisClr_None}"
 
@@ -151,32 +162,32 @@ if [ ! -z "$RunRbEnvAllVersions" ]; then
   for version in "${versions[@]}"
   do
 
-  echo
+    echo
 
-  skip=
+    skip=
 
-  for exclusion in "${exclusions[@]}"; do
+    for exclusion in "${exclusions[@]}"; do
 
-    if [[ "$exclusion" == "$version" ]]; then
+      if [[ "$exclusion" == "$version" ]]; then
 
-    skip=1
-    fi
-  done
+        skip=1
+      fi
+    done
 
-  if [ "$skip" != "" ]; then
+    if [ "$skip" != "" ]; then
 
-    echo "skipping Ruby version ${SisClr_Blue}${SisClr_Bold}$version${SisClr_None}:"
-  else
+      echo "skipping Ruby version ${SisClr_Blue}${SisClr_Bold}$version${SisClr_None}:"
+    else
 
-    echo "processing Ruby version ${SisClr_Blue}${SisClr_Bold}$version${SisClr_None}:"
+      echo "processing Ruby version ${SisClr_Blue}${SisClr_Bold}$version${SisClr_None}:"
 
-    echo -e "\texecuting command line 'RBENV_VERSION=$version $0 ${ForwardArgs[*]}' with Ruby version $version ..."
+      echo -e "\texecuting command line 'RBENV_VERSION=$version $0 ${ForwardArgs[*]}' with Ruby version $version ..."
 
-    if ! RBENV_VERSION="$version" "$0" "${ForwardArgs[@]}"; then
+      if ! RBENV_VERSION="$version" "$0" "${ForwardArgs[@]}"; then
 
-    result=1
+        result=1
+      fi
     fi
-  fi
   done
 
   exit $result
@@ -275,13 +286,24 @@ else
 
   result=0
 
+  test_files=$(mktemp "${TMPDIR:-/tmp}/run_all_unit_tests.XXXXXX") || {
+    >&2 echo "$0: ${SisClr_Red}${SisClr_Bold}failed to create temporary file for test discovery${SisClr_None}"
+    exit 1
+  }
+  trap 'rm -f "$test_files"' EXIT
+
+  if ! find "$ProjectDir" -name 'tc_*.rb' -print0 > "$test_files"; then
+    >&2 echo "$0: ${SisClr_Red}${SisClr_Bold}failed to discover test files${SisClr_None}"
+    exit 1
+  fi
+
   while IFS= read -r -d '' testfile; do
 
     if ! ruby $DebugFlag $WarningsFlag "$testfile"; then
 
       result=1
     fi
-  done < <(find "$ProjectDir" -name 'tc_*.rb' -print0)
+  done < "$test_files"
 
   exit $result
 fi

From 495e35b2fba73a67633a76d3b0863a4f2ef682d4 Mon Sep 17 00:00:00 2001
From: Matt Wilson <matthew@synesis.com.au>
Date: Thu, 27 Aug 2026 17:26:50 +1000
Subject: [PATCH 3/3] release

---
 .github/workflows/ruby.yml | 2 +-
 CHANGES.md                 | 2 +-
 NEWS.md                    | 2 +-
 cmpfs-ruby.gemspec         | 2 +-
 lib/cmpfs/version.rb       | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/ruby.yml b/.github/workflows/ruby.yml
index a5e52a4..327617d 100644
--- a/.github/workflows/ruby.yml
+++ b/.github/workflows/ruby.yml
@@ -7,7 +7,7 @@
 
 #
 # Created: 15th August 2026
-# Updated: 19th August 2026
+# Updated: 27th August 2026
 #
 
 name: Ruby
diff --git a/CHANGES.md b/CHANGES.md
index 66909b9..c842ae7 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,7 +1,7 @@
 # cmpfs.Ruby - Changes <!-- omit in toc -->
 
 
-## 0.2.5 - 19th August 2026
+## 0.2.5 - 27th August 2026
 
 * renamed **cmpfs.gemspec** to **cmpfs-ruby.gemspec** so the filename stem matches `spec.name`;
 * **cmpfs-ruby.gemspec**: `spec.summary` matches the README tagline; packaged **AUTHORS**, **CHANGES**, **CONTRIBUTING**, **EXAMPLES**, **FAQ**, **INSTALL**, **NEWS**, **SECURITY**, and **TODO**; **Gemfile.lock** and **.ruby-version** excluded from `spec.files`;
diff --git a/NEWS.md b/NEWS.md
index a1998bc..ffb3aee 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -2,7 +2,7 @@
 
 | Date             | News Item                                                                                |
 | ---------------- | ---------------------------------------------------------------------------------------- |
-| 19th August 2026 | [**cmpfs.Ruby** 0.2.5](https://github.com/synesissoftware/cmpfs.Ruby/releases/tag/0.2.5) |
+| 27th August 2026 | [**cmpfs.Ruby** 0.2.5](https://github.com/synesissoftware/cmpfs.Ruby/releases/tag/0.2.5) |
 | 15th August 2026 | [**cmpfs.Ruby** 0.2.4](https://github.com/synesissoftware/cmpfs.Ruby/releases/tag/0.2.4) |
 | 4th April 2024   | [**cmpfs.Ruby** 0.2.3](https://github.com/synesissoftware/cmpfs.Ruby/releases/tag/0.2.3) |
 | 4th April 2024   | **cmpfs.Ruby** 0.2.2.1 released                                                          |
diff --git a/cmpfs-ruby.gemspec b/cmpfs-ruby.gemspec
index 6dd0a07..6c3b73c 100644
--- a/cmpfs-ruby.gemspec
+++ b/cmpfs-ruby.gemspec
@@ -4,7 +4,7 @@
 # Purpose:  Gemspec for cmpfs.Ruby library
 #
 # Created:  1st March 2019
-# Updated:  19th August 2026
+# Updated:  27th August 2026
 #
 # ######################################################################## #
 
diff --git a/lib/cmpfs/version.rb b/lib/cmpfs/version.rb
index e62913c..e41b3ba 100644
--- a/lib/cmpfs/version.rb
+++ b/lib/cmpfs/version.rb
@@ -5,7 +5,7 @@
 # Purpose:  Version for cmpfs.Ruby library
 #
 # Created:  1st March 2019
-# Updated:  19th August 2026
+# Updated:  27th August 2026
 #
 # Home:     https://github.com/synesissoftware/cmpfs.Ruby
 #