synesissoftware · synesissoftware · Aug 27, 2026 · Aug 14, 2026 · Aug 14, 2026 · Aug 14, 2026
diff --git 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
@@ -2,10 +2,13 @@
 
 /.bzr/
 /.bundle/
+/.bzr/
 /.config/
 /.svn/
+/.vscode/
 /.yardoc/
 
+/_build/
 /_yardoc/
 
 /InstalledFiles/
@@ -23,17 +26,22 @@
 /tmp/
 /vendor/bundle/
 
+
 # directories (by pattern)
 
+
 # files (by name)
 
 .DS_Store
 .repl_history
 .ruby-version
 .rvmrc
 
+Gemfile.lock
+
 /spec/examples.txt
 
+
 # files (by pattern)
 
 *~

diff --git 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
@@ -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
@@ -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
diff --git 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
@@ -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
@@ -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 → cmpfs-ruby.gemspec b/cmpfs.gemspec → 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
@@ -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
 #