From 9a3539d4bc0eb6d2166fa938aadb1ebc22400f6c Mon Sep 17 00:00:00 2001
From: Anthony West <anthony.s.west@gmail.com>
Date: Sat, 10 Oct 2026 17:13:55 -0700
Subject: [PATCH 01/12] Update ASWLog description and add/update header
 descriptions

---
 AGENTS.md                       |  2 +-
 ASWLog/ASWLog_Base.h            |  6 +++++-
 ASWLog/ASWLog_CategoryLog.h     |  5 ++++-
 ASWLog/ASWLog_Config.h          |  6 ++++--
 ASWLog/ASWLog_ConsoleLog.h      |  5 ++++-
 ASWLog/ASWLog_CrashHandler.h    |  5 ++++-
 ASWLog/ASWLog_DebuggerLog.h     |  5 ++++-
 ASWLog/ASWLog_Fields.h          |  5 +++--
 ASWLog/ASWLog_FileLog.h         |  5 ++++-
 ASWLog/ASWLog_Formatter.h       |  6 ++++--
 ASWLog/ASWLog_Interface.h       |  5 ++++-
 ASWLog/ASWLog_Limiter.h         |  3 +++
 ASWLog/ASWLog_MemoryLog.h       |  5 ++++-
 ASWLog/ASWLog_MultiLog.h        |  5 ++++-
 ASWLog/ASWLog_NullLog.h         |  5 ++++-
 ASWLog/ASWLog_SyslogLog.h       |  5 ++++-
 ASWLog/ASWLog_TextLogBase.h     |  6 +++++-
 ASWLog/ASWLog_Types.h           |  5 +++--
 ASWLog/ASWLog_Unicode.h         |  5 +++--
 ASWLog/ASWLog_Utils.h           |  5 +++--
 ASWLog/ASWLog_Version.h         |  5 ++++-
 ASWLog/ASWLog_WindowsEventLog.h |  3 +++
 CMakeLists.txt                  |  2 ++
 README.md                       | 12 ++++++++++--
 24 files changed, 93 insertions(+), 28 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 6d21c27..2e0badf 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -6,7 +6,7 @@ These instructions apply to the entire repository unless a more specific `AGENTS
 
 ## Repository Overview
 
-ASWLog is a thread-safe light-weight C++ logging tool for Windows and Linux projects.
+ASWLog is a thread-safe, dependency-free C++20 logging library for Windows and Linux.
 
 - `ASWLog/` contains the framework implementation.
 - `tests/` contains the unit tests: test modules (`Test_ASWLog_<Unit>`, the tests of `ASWLog_<Unit>`) and shared test helpers (`UT_Helper_<Topic>`, e.g. `UT_Helper_DateTime`) in `tests/tests/`, their CMake project in `tests/cmake/`, their RAD Studio console project in `tests/rad370/`, and their RAD Studio VCL GUI runner project in `tests/vcl/gui/rad370/` (built from the submodule's `vcl/gui/src`). `tests/compile_checks/` holds "must not compile" checks, which `tests/cmake/CMakeLists.txt` runs with `try_compile` when configuring (a failed check stops the configure). `tests/package/` is a project that builds against an installed ASWLog with `find_package` (CI installs the library and runs it).
diff --git a/ASWLog/ASWLog_Base.h b/ASWLog/ASWLog_Base.h
index 685181a..1a6cf3f 100644
--- a/ASWLog/ASWLog_Base.h
+++ b/ASWLog/ASWLog_Base.h
@@ -2,7 +2,11 @@
 ASWLog_Base.h
 Author: Anthony S. West - ASW Software
 
-A light-weight logging tool.
+A logging library.
+
+TASWLogBase, the base of the built-in loggers: the minimum level, the
+enabled flag, the backtrace, the config and the error reporting that every
+logger shares.
 
 Requires C++ 20 or higher.
 
diff --git a/ASWLog/ASWLog_CategoryLog.h b/ASWLog/ASWLog_CategoryLog.h
index f674423..58c20f8 100644
--- a/ASWLog/ASWLog_CategoryLog.h
+++ b/ASWLog/ASWLog_CategoryLog.h
@@ -2,7 +2,10 @@
 ASWLog_CategoryLog.h
 Author: Anthony S. West - ASW Software
 
-A light-weight logging tool.
+A logging library.
+
+TASWCategoryLog, a named category of entries (e.g. "Net") with a minimum
+level of its own, which wraps another logger.
 
 Requires C++ 20 or higher.
 
diff --git a/ASWLog/ASWLog_Config.h b/ASWLog/ASWLog_Config.h
index 8920a8b..f3b08bd 100644
--- a/ASWLog/ASWLog_Config.h
+++ b/ASWLog/ASWLog_Config.h
@@ -2,9 +2,11 @@
 ASWLog_Config.h
 Author: Anthony S. West - ASW Software
 
-A light-weight logging tool.
+A logging library.
 
-Source for the ASWLog config options.
+TASWLogConfig, the settings of a logger, and the structs that group them
+(line layout, file, asynchronous writing, backtrace, startup and shutdown
+lines, and the settings of the system loggers).
 
 Requires C++ 20 or higher.
 
diff --git a/ASWLog/ASWLog_ConsoleLog.h b/ASWLog/ASWLog_ConsoleLog.h
index 3ea3338..11e5fd1 100644
--- a/ASWLog/ASWLog_ConsoleLog.h
+++ b/ASWLog/ASWLog_ConsoleLog.h
@@ -2,7 +2,10 @@
 ASWLog_ConsoleLog.h
 Author: Anthony S. West - ASW Software
 
-A light-weight logging tool.
+A logging library.
+
+TASWConsoleLog, a text logger that writes to the console (stdout, and
+stderr for warnings and errors), optionally in color.
 
 Requires C++ 20 or higher.
 
diff --git a/ASWLog/ASWLog_CrashHandler.h b/ASWLog/ASWLog_CrashHandler.h
index cc27630..b176262 100644
--- a/ASWLog/ASWLog_CrashHandler.h
+++ b/ASWLog/ASWLog_CrashHandler.h
@@ -2,7 +2,10 @@
 ASWLog_CrashHandler.h
 Author: Anthony S. West - ASW Software
 
-A light-weight logging tool.
+A logging library.
+
+Crash handlers that flush every text logger and write a "Crash: <reason>"
+line when the application crashes (InstallCrashHandlers(), HandleCrash()).
 
 Requires C++ 20 or higher.
 
diff --git a/ASWLog/ASWLog_DebuggerLog.h b/ASWLog/ASWLog_DebuggerLog.h
index 5c5c6e6..64ab5aa 100644
--- a/ASWLog/ASWLog_DebuggerLog.h
+++ b/ASWLog/ASWLog_DebuggerLog.h
@@ -2,7 +2,10 @@
 ASWLog_DebuggerLog.h
 Author: Anthony S. West - ASW Software
 
-A light-weight logging tool.
+A logging library.
+
+TASWDebuggerLog, a text logger that writes to the debugger's output on
+Windows (OutputDebugStringW); it writes nothing on other platforms.
 
 Requires C++ 20 or higher.
 
diff --git a/ASWLog/ASWLog_Fields.h b/ASWLog/ASWLog_Fields.h
index ed8eb86..3bf8c20 100644
--- a/ASWLog/ASWLog_Fields.h
+++ b/ASWLog/ASWLog_Fields.h
@@ -2,9 +2,10 @@
 ASWLog_Fields.h
 Author: Anthony S. West - ASW Software
 
-A light-weight logging tool.
+A logging library.
 
-Source for the ASWLog structured fields and scoped context.
+Structured fields: TASWLogField, a named value attached to one entry, and
+TASWLogScope, context that every entry logged on the thread carries.
 
 Requires C++ 20 or higher.
 
diff --git a/ASWLog/ASWLog_FileLog.h b/ASWLog/ASWLog_FileLog.h
index 80e08ba..4746515 100644
--- a/ASWLog/ASWLog_FileLog.h
+++ b/ASWLog/ASWLog_FileLog.h
@@ -2,7 +2,10 @@
 ASWLog_FileLog.h
 Author: Anthony S. West - ASW Software
 
-A light-weight logging tool.
+A logging library.
+
+TASWFileLog, a text logger that writes to a file, with rotation by size and
+by day, backup cleanup, and flush and sync settings for crash durability.
 
 Requires C++ 20 or higher.
 
diff --git a/ASWLog/ASWLog_Formatter.h b/ASWLog/ASWLog_Formatter.h
index ca9b42c..d5c9922 100644
--- a/ASWLog/ASWLog_Formatter.h
+++ b/ASWLog/ASWLog_Formatter.h
@@ -2,9 +2,11 @@
 ASWLog_Formatter.h
 Author: Anthony S. West - ASW Software
 
-A light-weight logging tool.
+A logging library.
 
-Source for the ASWLog line formatters.
+IASWLogFormatter, which turns an entry into the line a text logger writes,
+and the built-in formatters: TASWTextFormatter (the default layout),
+TASWPatternFormatter and TASWJSONFormatter (JSON Lines).
 
 Requires C++ 20 or higher.
 
diff --git a/ASWLog/ASWLog_Interface.h b/ASWLog/ASWLog_Interface.h
index e3cc936..ee8a5d0 100644
--- a/ASWLog/ASWLog_Interface.h
+++ b/ASWLog/ASWLog_Interface.h
@@ -2,7 +2,10 @@
 ASWLog_Interface.h
 Author: Anthony S. West - ASW Software
 
-A light-weight logging tool.
+A logging library.
+
+IASWLog, the interface of every logger, with its logging methods: plain,
+formatted (*Fmt, checked at compile time), raw and forced.
 
 Requires C++ 20 or higher.
 
diff --git a/ASWLog/ASWLog_Limiter.h b/ASWLog/ASWLog_Limiter.h
index 8bcf342..6639388 100644
--- a/ASWLog/ASWLog_Limiter.h
+++ b/ASWLog/ASWLog_Limiter.h
@@ -4,6 +4,9 @@ Author: Anthony S. West - ASW Software
 
 A logging library.
 
+Rate-limited logging for entries that can repeat often: the ASWLOG_ONCE,
+ASWLOG_EVERY_N and ASWLOG_EVERY_INTERVAL macros, and TASWLogLimiter.
+
 Requires C++ 20 or higher.
 
 Copyright 2026 ASW Software
diff --git a/ASWLog/ASWLog_MemoryLog.h b/ASWLog/ASWLog_MemoryLog.h
index b0bc05c..7918925 100644
--- a/ASWLog/ASWLog_MemoryLog.h
+++ b/ASWLog/ASWLog_MemoryLog.h
@@ -2,7 +2,10 @@
 ASWLog_MemoryLog.h
 Author: Anthony S. West - ASW Software
 
-A light-weight logging tool.
+A logging library.
+
+TASWMemoryLog, a text logger that keeps its newest lines in memory, e.g.
+for an in-app log viewer, a crash report or tests.
 
 Requires C++ 20 or higher.
 
diff --git a/ASWLog/ASWLog_MultiLog.h b/ASWLog/ASWLog_MultiLog.h
index eaa6ebd..a169b0f 100644
--- a/ASWLog/ASWLog_MultiLog.h
+++ b/ASWLog/ASWLog_MultiLog.h
@@ -2,7 +2,10 @@
 ASWLog_MultiLog.h
 Author: Anthony S. West - ASW Software
 
-A light-weight logging tool.
+A logging library.
+
+TASWMultiLog, which passes each entry on to several loggers, e.g. a file
+logger and a console logger.
 
 Requires C++ 20 or higher.
 
diff --git a/ASWLog/ASWLog_NullLog.h b/ASWLog/ASWLog_NullLog.h
index 52a654e..03fdb42 100644
--- a/ASWLog/ASWLog_NullLog.h
+++ b/ASWLog/ASWLog_NullLog.h
@@ -2,7 +2,10 @@
 ASWLog_NullLog.h
 Author: Anthony S. West - ASW Software
 
-A light-weight logging tool.
+A logging library.
+
+TASWNullLog, a logger that writes nothing, e.g. to turn logging off without
+changing the code that logs, or to pass to code under test.
 
 Requires C++ 20 or higher.
 
diff --git a/ASWLog/ASWLog_SyslogLog.h b/ASWLog/ASWLog_SyslogLog.h
index 013dec8..a2e126f 100644
--- a/ASWLog/ASWLog_SyslogLog.h
+++ b/ASWLog/ASWLog_SyslogLog.h
@@ -2,7 +2,10 @@
 ASWLog_SyslogLog.h
 Author: Anthony S. West - ASW Software
 
-A light-weight logging tool.
+A logging library.
+
+TASWSyslogLog, a text logger that sends its lines to the Linux system log
+(and the systemd journal); it writes nothing on Windows.
 
 Requires C++ 20 or higher.
 
diff --git a/ASWLog/ASWLog_TextLogBase.h b/ASWLog/ASWLog_TextLogBase.h
index 69c49b9..bbcc4cb 100644
--- a/ASWLog/ASWLog_TextLogBase.h
+++ b/ASWLog/ASWLog_TextLogBase.h
@@ -2,7 +2,11 @@
 ASWLog_TextLogBase.h
 Author: Anthony S. West - ASW Software
 
-A light-weight logging tool.
+A logging library.
+
+TASWTextLogBase, the base of the loggers that write each entry as a line of
+text: locking, formatting, asynchronous writing and the startup lines. A
+custom text logger derives from it and implements only its output.
 
 Requires C++ 20 or higher.
 
diff --git a/ASWLog/ASWLog_Types.h b/ASWLog/ASWLog_Types.h
index 95ea589..de6855f 100644
--- a/ASWLog/ASWLog_Types.h
+++ b/ASWLog/ASWLog_Types.h
@@ -2,9 +2,10 @@
 ASWLog_Types.h
 Author: Anthony S. West - ASW Software
 
-A light-weight logging tool.
+A logging library.
 
-Source for the ASWLog types.
+The basic types: Level and the other enums, TASWLogRecord (an entry as a
+logger receives it) and TASWLogError (a logger's internal failure).
 
 Requires C++ 20 or higher.
 
diff --git a/ASWLog/ASWLog_Unicode.h b/ASWLog/ASWLog_Unicode.h
index e64cb93..0f68a10 100644
--- a/ASWLog/ASWLog_Unicode.h
+++ b/ASWLog/ASWLog_Unicode.h
@@ -4,8 +4,9 @@ Author: Anthony S. West - ASW Software
 
 A logging library.
 
-Source for logging wide (UTF-16 and UTF-32) text: conversions to and from UTF-8, and the text wrappers the logging
-methods and the *Fmt arguments take.
+Wide-string support: TASWWideText (wchar_t and char16_t messages), the
+Wide() and UTF8() wrappers for *Fmt arguments, and conversions between
+UTF-8 and UTF-16 or UTF-32.
 
 Requires C++ 20 or higher.
 
diff --git a/ASWLog/ASWLog_Utils.h b/ASWLog/ASWLog_Utils.h
index 99d1bf5..0613531 100644
--- a/ASWLog/ASWLog_Utils.h
+++ b/ASWLog/ASWLog_Utils.h
@@ -2,9 +2,10 @@
 ASWLog_Utils.h
 Author: Anthony S. West - ASW Software
 
-A light-weight logging tool.
+A logging library.
 
-Source for the ASWLog utility functions, etc.
+Helpers the loggers use, which an application can use too: log file names,
+process and system information, paths, time formatting and JSON escaping.
 
 Requires C++ 20 or higher.
 
diff --git a/ASWLog/ASWLog_Version.h b/ASWLog/ASWLog_Version.h
index cb65b4a..cb787d0 100644
--- a/ASWLog/ASWLog_Version.h
+++ b/ASWLog/ASWLog_Version.h
@@ -2,7 +2,10 @@
 ASWLog_Version.h
 Author: Anthony S. West - ASW Software
 
-Single source for the ASWLog semantic version (https://semver.org).
+A logging library.
+
+The ASWLog version (https://semver.org), as macros and constants: the only
+place where the version is set.
 
 Requires C++ 20 or higher.
 
diff --git a/ASWLog/ASWLog_WindowsEventLog.h b/ASWLog/ASWLog_WindowsEventLog.h
index 787075d..048fcfe 100644
--- a/ASWLog/ASWLog_WindowsEventLog.h
+++ b/ASWLog/ASWLog_WindowsEventLog.h
@@ -4,6 +4,9 @@ Author: Anthony S. West - ASW Software
 
 A logging library.
 
+TASWWindowsEventLog, a text logger that reports its lines to the Windows
+Event Log; it writes nothing on other platforms.
+
 Requires C++ 20 or higher.
 
 Copyright 2026 ASW Software
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 0117f0b..e881b47 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -13,6 +13,8 @@ endforeach()
 
 project(ASWLog
     VERSION ${ASWLOG_VERSION_MAJOR}.${ASWLOG_VERSION_MINOR}.${ASWLOG_VERSION_PATCH}
+    DESCRIPTION "A thread-safe, dependency-free C++20 logging library for Windows and Linux"
+    HOMEPAGE_URL "https://github.com/ASWSoftware/asw-log"
     LANGUAGES CXX
 )
 
diff --git a/README.md b/README.md
index 3f4ce05..80f9265 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,14 @@
 # ASWLog - https://github.com/ASWSoftware/asw-log
 
-ASWLog is a thread-safe light-weight C++ logging tool for Windows and Linux projects.
+ASWLog is a thread-safe, dependency-free C++20 logging library for Windows and Linux.
+
+## Design
+
+ASWLog is a folder of standard C++ sources, or one CMake target, with no third-party code. Its defaults put crash
+durability first: a logging call is synchronous and every entry is flushed before the call returns, so the last
+entries before a crash are in the file. A call below the logger's level costs a few nanoseconds, so Debug and Trace
+calls can stay in release builds and be turned on at run time. The rest (asynchronous writing, backtrace, JSON and
+pattern formatters, crash handlers, and the other extras below) is opt-in.
 
 ## Features
 
@@ -67,7 +75,7 @@ ASWLog is a thread-safe light-weight C++ logging tool for Windows and Linux proj
 
 # Donations:
 
-If you find this tool helpful, donations are always appreciated:
+If you find this library helpful, donations are always appreciated:
 
 PayPal:
 donate@aswsoftware.com

From b693e6ced2a3f27fc75023ac4a34d92b7ee74c33 Mon Sep 17 00:00:00 2001
From: Anthony West <anthony.s.west@gmail.com>
Date: Sat, 10 Oct 2026 18:15:33 -0700
Subject: [PATCH 02/12] Update documentation in prep for 1.0

---
 AGENTS.md             |   4 +-
 Deploy.bat            |   7 ++
 README.md             | 126 ++++++++++++++++++++++++-
 docs/Configuration.md | 211 ++++++++++++++++++++++++++++++++++++++++++
 docs/CustomLoggers.md | 155 +++++++++++++++++++++++++++++++
 docs/Guarantees.md    |  93 +++++++++++++++++++
 example/src/main.cpp  |  36 +++++--
 7 files changed, 620 insertions(+), 12 deletions(-)
 create mode 100644 docs/Configuration.md
 create mode 100644 docs/CustomLoggers.md
 create mode 100644 docs/Guarantees.md

diff --git a/AGENTS.md b/AGENTS.md
index 2e0badf..670ad39 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -15,7 +15,8 @@ ASWLog is a thread-safe, dependency-free C++20 logging library for Windows and L
 - `.github/workflows/ci.yml` builds and runs the unit tests on Windows (MSVC, MinGW) and Linux (GCC, Clang), plus Linux Clang builds with ThreadSanitizer and with AddressSanitizer + UBSan (`ASWLOG_SANITIZE`); the non-sanitizer jobs also check the installed CMake package (`tests/package/`).
 - `example/` contains example app that uses the logger.
 - `example/rad370/` contains the RAD Studio 13.1 project and Windows build scripts.
-- `README.md` contains repo details.
+- `README.md` contains repo details: features, quick start, project setup, API overview, versions and tests.
+- `docs/` contains the reference documentation: `Configuration.md` (every `TASWLogConfig` setting, its default and which loggers use it, and the environment variables), `Guarantees.md` (thread safety, order, callback threads, lifetimes, crash durability) and `CustomLoggers.md` (custom formatters and loggers).
 - `CHANGELOG.md` records notable changes per release (see Changelog below).
 - `CONTRIBUTING.md` contains the guidelines for contributors (issues, branches, commit history, pull requests, and bug reports); it defers to this file for coding rules, so keep the two consistent.
 - `.uncrustify.cfg` and `.githooks/` define the repository formatting workflow.
@@ -54,6 +55,7 @@ Prefer standard C++ and portable library facilities. Avoid compiler-, IDE-, or o
 - Follow the surrounding naming, indentation, brace, include, and comment style. Avoid unrelated formatting changes.
 - Keep declarations and definitions consistent, and update all relevant project or build files when adding source files.
 - Add or update focused tests for behavior changes, including error and platform-specific cases where applicable.
+- Keep the documentation in step: a new or changed `TASWLogConfig` setting or environment key goes in `docs/Configuration.md`, a new logger in the README's API overview, and a change to threading, lifetimes or durability in `docs/Guarantees.md`. Add a new docs file to `Deploy.bat`.
 
 ## Building and Testing
 
diff --git a/Deploy.bat b/Deploy.bat
index 8657210..d85cd89 100644
--- a/Deploy.bat
+++ b/Deploy.bat
@@ -67,6 +67,13 @@ if errorlevel 1 exit /b 1
 call :CopyFile "cmake\ASWLogConfig.cmake.in" "%TARGET_DIR%\cmake\ASWLogConfig.cmake.in"
 if errorlevel 1 exit /b 1
 
+call :CopyFile "docs\Configuration.md" "%TARGET_DIR%\docs\Configuration.md"
+if errorlevel 1 exit /b 1
+call :CopyFile "docs\CustomLoggers.md" "%TARGET_DIR%\docs\CustomLoggers.md"
+if errorlevel 1 exit /b 1
+call :CopyFile "docs\Guarantees.md" "%TARGET_DIR%\docs\Guarantees.md"
+if errorlevel 1 exit /b 1
+
 call :CopyFile "ASWLog\ASWLog_Base.cpp" "%TARGET_DIR%\ASWLog\ASWLog_Base.cpp"
 if errorlevel 1 exit /b 1
 call :CopyFile "ASWLog\ASWLog_Base.h" "%TARGET_DIR%\ASWLog\ASWLog_Base.h"
diff --git a/README.md b/README.md
index 80f9265..766fd92 100644
--- a/README.md
+++ b/README.md
@@ -55,6 +55,10 @@ pattern formatters, crash handlers, and the other extras below) is opt-in.
 - Rate-limited logging for entries that can repeat often: `ASWLOG_ONCE`, `ASWLOG_EVERY_N` and `ASWLOG_EVERY_INTERVAL`
   (`ASWLog_Limiter.h`), e.g. `ASWLOG_EVERY_INTERVAL(log, std::chrono::seconds(5), ASWLog::Level::Warn, "Retrying {}",
   host);`, which counts the skipped entries in a `suppressed` field.
+- Settings from environment variables (`TASWLogConfig::ApplyEnvironment()`), e.g. `ASWLOG_LEVEL=Trace` to see
+  everything a deployed release build logs, without rebuilding it.
+- Wide-string messages: every logging method also takes `wchar_t` or `char16_t` text (e.g. `L"..."`, a
+  `std::wstring`, or C++Builder's `UnicodeString::c_str()`), converted to UTF-8 only if the entry is written.
 - A hook to drop or change entries before they are written (`TASWLogConfig::OnBeforeWrite`), e.g. to redact secrets
   or drop noisy entries by content, category or field.
 - Structured fields per entry, e.g. `logger.LogInfo("Order placed", {{"orderId", 17}})`, and scoped context that every
@@ -85,13 +89,64 @@ Bitcoin:
 
 # How to Use
 
-Add the source in `ASWLog` to your C++ project.
+## Quick start
 
-## CMake
+```cpp
+#include "ASWLog_CrashHandler.h"
+#include "ASWLog_FileLog.h"
+
+int main()
+{
+    ASWLog::TASWLogConfig config;
+    config.File.FilePath = "myapp.txt"; // In the "logs" folder
+    config.ApplyEnvironment(); // Optional: e.g. ASWLOG_LEVEL=Debug overrides the level
+
+    auto& log = ASWLog::TASWFileLog::GetInstance();
+    if (!log.Initialize(config))
+        return 1;
+
+    ASWLog::InstallCrashHandlers(); // Flushes the log and adds a "Crash:" line if the application crashes
+
+    log.LogInfo("Started");
+    log.LogWarnFmt("Disk {} is {}% full", "C:", 93); // Checked against its arguments at compile time
+    log.LogInfo("Order placed", { { "orderId", 17 }, { "total", 9.99 } });
+    log.LogDebug("Not written: below the minimum level (Info by default)");
+
+    return 0;
+}
+```
+
+writes `logs/myapp.txt`, after the startup lines (time, OS, drive, memory, application; see `TASWLogConfig::Startup`):
+
+```text
+[2026-10-11T00:24:25.089Z][INFO][P:6180][T:6648]: Started
+[2026-10-11T00:24:25.089Z][WARN][P:6180][T:6648]: Disk C: is 93% full
+[2026-10-11T00:24:25.089Z][INFO][P:6180][T:6648][orderId=17 total=9.99]: Order placed
+[2026-10-11T00:24:25.089Z][INFO][P:6180][T:6648]: Logger shutdown: 2026-10-11T00:24:25.089Z
+```
+
+The `example/src/main.cpp` app shows more: console, multi-log, categories, scopes, rate limiting and wide text.
+
+## Adding ASWLog to a project
+
+### Copied sources (any build system)
+
+Add every `.cpp` file in `ASWLog/` to the project, and the `ASWLog` folder to its include path, and compile as C++20.
+On Windows, link `psapi` and `advapi32` (RAD Studio links them by default); on Linux, the threads library
+(`-pthread`). `Deploy.bat <folder>` copies the library sources, the examples and the docs to a folder, e.g. for a
+release package.
+
+### RAD Studio
+
+Add the `ASWLog/*.cpp` files to the project (Project > Add to Project) and the `ASWLog` folder to the include path
+(Project > Options > Building > C++ Shared Options > Include path). RAD Studio 13.1 or later with the modern Clang
+toolchain (Win64x). `example/rad370/ASWLogExample.cbproj` is a working project to copy settings from.
+
+### CMake
 
 The repository's root `CMakeLists.txt` defines the static library target `ASWLog::ASWLog`. Linking to it adds the
-`ASWLog` include folder, C++20, and the system libraries the logger needs (the threads library, and `psapi` on
-Windows). Add it from a copy of the repository, such as a git submodule:
+`ASWLog` include folder, C++20, and the system libraries the logger needs (the threads library, and `psapi` and
+`advapi32` on Windows). Add it from a copy of the repository, such as a git submodule:
 
 ```
 add_subdirectory(third_party/asw-log)
@@ -146,6 +201,60 @@ cmake --build example/cmake/build --config Release
 
 The executable is written to `example/build/bin/Release/ASWLogExample.exe`, alongside RAD Studio output.
 
+## API overview
+
+**Loggers.** Each implements `ASWLog::IASWLog` (`ASWLog_Interface.h`), so code that logs can take an `IASWLog&` and
+not care where the entries go. Most have a `GetInstance()` singleton, and any of them can also be created as an
+ordinary object.
+
+| Class | Header | Writes to |
+|---|---|---|
+| `TASWFileLog` | `ASWLog_FileLog.h` | A file, with rotation, daily rolling and backup cleanup |
+| `TASWConsoleLog` | `ASWLog_ConsoleLog.h` | stdout, and stderr for Warn and above, in color on a terminal |
+| `TASWDebuggerLog` | `ASWLog_DebuggerLog.h` | The debugger's output (Windows) |
+| `TASWMemoryLog` | `ASWLog_MemoryLog.h` | Memory: the newest lines, e.g. for an in-app log viewer |
+| `TASWSyslogLog` | `ASWLog_SyslogLog.h` | The system log and the systemd journal (Linux) |
+| `TASWWindowsEventLog` | `ASWLog_WindowsEventLog.h` | The Windows Event Log (Windows) |
+| `TASWNullLog` | `ASWLog_NullLog.h` | Nothing |
+| `TASWMultiLog` | `ASWLog_MultiLog.h` | Several loggers at once, e.g. a file and the console |
+| `TASWCategoryLog` | `ASWLog_CategoryLog.h` | Another logger, marking the entries with a category (e.g. `[Net]`) that can have a level of its own |
+
+The loggers that write to only one platform build on both and write nothing on the other, so the same code can add
+them everywhere.
+
+**Logging.** On any logger:
+
+- `LogTrace()`, `LogDebug()`, `LogInfo()`, `LogWarn()`, `LogError()`, `LogCritical()`, and `Log(level, ...)`.
+- `LogInfoFmt("Opened {} in {} ms", name, ms)` and the other `*Fmt` methods: `std::format`, with the format string
+  checked against its arguments at compile time (wrap a format string built at run time in `ASWLog::RuntimeFormat()`).
+  An entry below the minimum level isn't formatted.
+- `LogRaw()` writes the message as it is, without the line layout; `LogForce()` and `LogForceRaw()` write it whatever
+  the minimum level.
+- Fields: `LogInfo("Order placed", {{"orderId", 17}})`, `LogInfoFmt({{"orderId", id}}, "Order {} placed", id)`, and
+  `ASWLog::TASWLogScope scope{{"requestId", id}};` for fields that every entry on the thread carries while it exists
+  (`ASWLog_Fields.h`).
+- Wide text: `LogInfo(L"...")`, `LogInfoFmt(L"... {}", ...)`, and `ASWLog::Wide(text)` / `ASWLog::UTF8(text)` for
+  arguments (`ASWLog_Unicode.h`).
+- The caller's function and source line are captured automatically (shown with `Line.ShowFunctionName` and
+  `Line.ShowSourceLine`).
+
+**Control.** `Initialize(config)`, `Reconfigure(config)`, `GetConfig()`, `SetMinimumLevel()`, `ShouldLog(level)` (to
+skip building an expensive message), `SetEnabled()`, `Flush()`, `Open()`, `Close()` and `DumpBacktrace()`; a file
+logger also has `RotateLogFiles()` and `DeleteOldLogs()`.
+
+**More.** `ASWLog::InstallCrashHandlers()` (`ASWLog_CrashHandler.h`), the `ASWLOG_ONCE`, `ASWLOG_EVERY_N` and
+`ASWLOG_EVERY_INTERVAL` macros (`ASWLog_Limiter.h`), `TASWLogConfig::ApplyEnvironment()`, the formatters
+(`ASWLog_Formatter.h`), and the version (`ASWLog_Version.h`). The header comments document every class and method.
+
+## Documentation
+
+- [docs/Configuration.md](docs/Configuration.md): every setting, its default, and which loggers use it, plus the
+  environment variables.
+- [docs/Guarantees.md](docs/Guarantees.md): thread safety, the order of entries, which thread runs each callback,
+  object lifetimes, and choosing settings for crash durability.
+- [docs/CustomLoggers.md](docs/CustomLoggers.md): writing a formatter or a logger of your own.
+- [CHANGELOG.md](CHANGELOG.md): the changes in each release.
+
 ## Versions
 
 ASWLog follows [Semantic Versioning](https://semver.org). Releases are tagged on `main` (e.g. `v1.1.0`). Between
@@ -161,6 +270,15 @@ and as constants in the `ASWLog` namespace:
 #endif
 ```
 
+### Upgrading from 0.x
+
+1.0.0 is the first release with a stable interface; the 0.x releases changed it as the design settled. The releases
+that can need changes in code that uses ASWLog are 0.43.0, 0.45.0, 0.65.0, 0.75.0 (only for a class that implements
+`IASWLog` directly) and 1.0.0. In [CHANGELOG.md](CHANGELOG.md), read the **Changed** and **Removed** sections, and
+the entries marked "Breaking", of every release after the one you use: each says what existing code must change.
+Projects that list the ASWLog sources must also add the files that new releases added (the CHANGELOG names them, e.g.
+`ASWLog_Unicode.cpp`).
+
 # Unit Tests
 
 Using the logger only requires the `ASWLog` source. The unit tests in `tests` additionally use the
diff --git a/docs/Configuration.md b/docs/Configuration.md
new file mode 100644
index 0000000..de42c30
--- /dev/null
+++ b/docs/Configuration.md
@@ -0,0 +1,211 @@
+# Configuration reference
+
+Every logger takes a `ASWLog::TASWLogConfig` (`ASWLog_Config.h`) in `Initialize()`. Its settings are grouped by
+concern, and a logger ignores the groups it doesn't use, so one config can be passed to several loggers (a multi-log
+passes its config on to the loggers it holds).
+
+```cpp
+ASWLog::TASWLogConfig config;
+config.InitialMinimumLevel = ASWLog::Level::Debug;
+config.File.FolderPath = "logs";
+config.File.FilePath = "myapp.txt";
+config.File.EnableRotation = true;
+config.ApplyEnvironment(); // Optional: lets ASWLOG_* environment variables override the settings (see below)
+
+auto& log = ASWLog::TASWFileLog::GetInstance();
+log.Initialize(config);
+```
+
+To change the settings of a running logger, copy its current config, change the copy, and pass it to `Reconfigure()`,
+which is safe while other threads log:
+
+```cpp
+auto config = *log.GetConfig();
+config.Line.ShowThreadId = false;
+log.Reconfigure(config);
+```
+
+`Reconfigure()` doesn't change the minimum level (use `SetMinimumLevel()`) and doesn't write the startup lines again.
+
+The header comments in `ASWLog_Config.h` have the full details of each setting; this page is the overview.
+
+## Which logger uses what
+
+| Group | Used by |
+|---|---|
+| `InitialMinimumLevel` | Every logger, including the multi-log (its own pre-filter) |
+| `Line`, `Startup`, `Shutdown`, `Async` | The text loggers: file, console, debugger, memory, syslog, Windows Event Log, and loggers derived from `TASWTextLogBase` |
+| `File` | `TASWFileLog` |
+| `Backtrace` | Every logger except the multi-log (each of its loggers keeps its own), the category logger and the null logger |
+| `Memory` | `TASWMemoryLog` |
+| `Syslog` | `TASWSyslogLog` |
+| `EventLog` | `TASWWindowsEventLog` |
+| `OnBeforeWrite` | Every logger; a multi-log calls its own once per entry, before passing the entry on |
+| `OnLogEntry`, `OnLogEntryMinimumLevel` | The text loggers |
+| `OnError`, `ErrorReportInterval` | Every logger; a multi-log passes them on, and each of its loggers reports its own failures |
+
+A category logger (`TASWCategoryLog`) and the null logger (`TASWNullLog`) take no config: the category's output
+belongs to the logger it wraps.
+
+## Top level
+
+| Setting | Default | What it does |
+|---|---|---|
+| `InitialMinimumLevel` | `Level::Info` | The minimum level `Initialize()` sets. Change it later with `SetMinimumLevel()`; this field doesn't follow it. |
+| `OnBeforeWrite` | empty | Called for each entry that passes the level checks, before it is written: return `false` to drop it, or change it with `entry.SetMessage()`, `SetField()` or `RemoveField()` (e.g. to redact secrets). Runs on the logging thread, before the logger's lock, possibly on several threads at once. |
+| `OnLogEntry` | empty | Called after an entry at or above `OnLogEntryMinimumLevel` was written, with the record and the line as written (e.g. for alerting). Runs outside the logger's lock; with `Async.Enabled`, on the logger's own thread. Exceptions are swallowed. |
+| `OnLogEntryMinimumLevel` | `Level::Error` | The level an entry needs for `OnLogEntry`. `Level::Off` = never. |
+| `OnError` | empty | Receives the logger's internal failures (a file that can't be opened, written, flushed or rotated, an invalid setting, ...) as a `TASWLogError`. Empty: each is written to stderr as one line. Runs outside the logger's lock. |
+| `ErrorReportInterval` | 1 minute | Each kind of failure is reported at most once per interval; the next report says how many were left out. 0 = report every failure. |
+
+## `Line`: the line layout (`TASWLineConfig`)
+
+| Setting | Default | What it does |
+|---|---|---|
+| `Formatter` | empty | Formats each line. Empty: the built-in layout (`TASWTextFormatter`) from the `Show*` settings. Assign a `TASWPatternFormatter` (e.g. `"{time} {level:5} {message}"`), a `TASWJSONFormatter` (JSON Lines) or your own `IASWLogFormatter`. One formatter can be shared by several loggers. |
+| `Ending` | `LineEnding::LF` | Added after each formatted line (`LF` or `CRLF`); not after `LogRaw()` entries written as they are. |
+| `Multiline` | `MultilineMode::Preserve` | The line breaks inside an entry: written as they are (`Preserve`), each followed by `    \| ` (`Indent`), or as `\r` and `\n` (`Escape`). |
+| `TimestampZone` | `TimeZone::UTC` | `UTC` (e.g. `2026-09-28T21:02:44.342Z`) or `Local` (e.g. `2026-09-28T16:02:44.342-05:00`). Also sets when daily rolling starts a new file and the time in backup names. |
+| `TimestampPrecision` | `TimePrecision::Milliseconds` | `Milliseconds`, `Microseconds` or `Nanoseconds`. |
+| `ShowTimestamp` | `true` | The entry's time. |
+| `ShowLevel` | `true` | The entry's level, e.g. `[INFO]`. |
+| `ShowCategory` | `true` | The entry's category, e.g. `[Net]`, if it has one. |
+| `ShowProcessId` | `true` | The OS process id. |
+| `ShowThreadId` | `true` | The OS id of the thread that logged the entry. |
+| `ShowWorkingSet` | `false` | The process's memory use. |
+| `ShowPeakWorkingSet` | `false` | The process's peak memory use. |
+| `ShowFunctionName` | `false` | The function that logged the entry. |
+| `ShowSourceLine` | `false` | The source file and line that logged the entry. |
+| `ShowFields` | `true` | The entry's fields (its own and its scopes'), if it has any. |
+
+The `Show*` settings are read by the built-in layout and by `TASWJSONFormatter`; a pattern decides its own fields.
+
+## `Startup`: the lines `Initialize()` writes (`TASWStartupConfig`)
+
+| Setting | Default | What it does |
+|---|---|---|
+| `Banner` | empty | A line written first, if set. |
+| `WriteApplicationInfo` | `true` | The executable's path and build target, e.g. `App: app_exe='C:\MyApp\MyApp.exe', app_target=Win64`. |
+| `WriteCommandLine` | `false` | The command line, added to the application line. |
+| `WriteDriveInfo` | `true` | The disk's total, free and used space. |
+| `WriteMemoryUsage` | `true` | The process's memory use (working set and peak). |
+| `WriteOSInfo` | `true` | The operating system, its version and the architecture. |
+| `WriteSystemMemoryInfo` | `true` | The system's total and available memory. |
+| `WriteTimeInfo` | `true` | The time in UTC, and in local time with its offset. |
+
+## `Shutdown`: the lines at shutdown and on a crash (`TASWShutdownConfig`)
+
+| Setting | Default | What it does |
+|---|---|---|
+| `WriteLine` | `true` | "Logger shutdown: <time>" when the logger is finalized (its destructor, or process exit for a `GetInstance()` singleton), followed by the banner if set. |
+| `Banner` | empty | A line after the shutdown line. |
+| `WriteCrashLine` | `true` | A Critical "Crash: <reason>" line when the application crashes (with the crash handlers installed, see `ASWLog_CrashHandler.h`). The logger is flushed on a crash either way. |
+
+## `File`: the log file (`TASWFileConfig`)
+
+| Setting | Default | What it does |
+|---|---|---|
+| `FolderPath` | `"logs"` | The folder of the log file, relative to the working directory unless absolute. |
+| `FilePath` | `"aswlog.txt"` | The log file's name, inside `FolderPath`, or a path of its own if absolute. `ResolvePath()` gives the result. |
+| `AutoOpenClosePerWrite` | `false` | Opens and closes the file for every entry. Required when several processes write to one log file. |
+| `Flush` | `FlushMode::EveryWrite` | When the file's buffer is flushed: after every entry (`EveryWrite`), after every entry that ends a line (`OnNewLine`, so a `LogRaw()` piece without a line break waits), only on `Flush()` or when the buffer is full (`Manual`), or every `FlushInterval` by the logger's own thread (`Periodic`). See [Guarantees.md](Guarantees.md#crash-durability). |
+| `FlushInterval` | 1000 ms | `FlushMode::Periodic`'s interval. 0 or less = every entry. |
+| `FlushImmediatelyAtLevel` | `Level::Error` | An entry at or above this level is flushed as soon as it is written, whatever `Flush` says. `Level::Off` = only `Flush` decides. |
+| `SyncToDiskAtLevel` | `Level::Off` | An entry at or above this level is also synced to disk (`FlushFileBuffers`/`fsync`), so it survives a power loss. A sync often takes milliseconds: keep it for rare entries. |
+| `OpenRetryCount` | 5 | How often opening the file is tried before an entry is dropped (e.g. while another program holds the file). |
+| `OpenRetryDelay` | 50 ms | The wait between those tries. |
+| `CircuitBreakerResetDelay` | 500 ms | After the file couldn't be reopened, entries are dropped without trying again until this long after the last failure. 0 = try on every entry. |
+| `EnableRotation` | `false` | Renames the file to a backup when it reaches `MaxFileSizeBytes`. |
+| `MaxFileSizeBytes` | 10 MB | The size that triggers a rotation. |
+| `RotationRetryDelay` | 500 ms | After a failed rotation, entries go on to the current file, and rotating isn't tried again until this long after the failure. |
+| `EnableDailyRolling` | `false` | Rotates the file at midnight (in `Line.TimestampZone`), and at `Initialize()` if the file was last written on an earlier day. |
+| `OnBackupCreated` | empty | Called for each backup a rotation makes, with its path and reason, e.g. to compress, upload or move it. Runs outside the logger's lock, on the thread whose call rotated the log. |
+| `RetentionMaxAge` | 0 (off) | After each rotation, deletes this log's backups older than this. |
+| `MaxBackupFiles` | 0 (unlimited) | After each rotation, keeps only the newest this many backups. |
+| `MaxBackupTotalBytes` | 0 (unlimited) | After each rotation, keeps only the newest backups that together take at most this many bytes. Set it above `MaxFileSizeBytes`. |
+
+Backups are named `<stem>.<reason>.<time>.bak`, e.g. `myapp.size.2026-10-10_143005_123.bak`, and a name is never
+reused. `TASWFileLog::DeleteOldLogs()` deletes other old files by a wildcard pattern.
+
+## `Async`: asynchronous writing (`TASWAsyncConfig`)
+
+| Setting | Default | What it does |
+|---|---|---|
+| `Enabled` | `false` | The logging call formats the entry and queues it; the logger's own thread writes the queued entries in order. |
+| `QueueCapacity` | 8192 | How many entries can wait in the queue. |
+| `OverflowPolicy` | `AsyncOverflowPolicy::Block` | When the queue is full: the call waits for room (`Block`), or the entry is dropped and the drops are counted and reported (`DropNewest`). |
+| `WaitAtLevel` | `Level::Error` | The call of an entry at or above this level returns only once the entry (and every entry queued before it) is written and flushed, and such an entry is never dropped. `Level::Off` = no call waits. |
+
+## `Backtrace`: recent entries below the minimum level (`TASWBacktraceConfig`)
+
+| Setting | Default | What it does |
+|---|---|---|
+| `Capacity` | 0 (off) | How many entries below the minimum level are kept in memory; the oldest goes when it is full. |
+| `LowestLevel` | `Level::Trace` | Entries below it aren't kept. |
+| `DumpAtLevel` | `Level::Error` | Writing an entry at or above this level writes the kept entries first. `Level::Off` = only `DumpBacktrace()` and a crash write them. |
+
+## `Memory`: what a memory logger keeps (`TASWMemoryConfig`)
+
+| Setting | Default | What it does |
+|---|---|---|
+| `MaxLines` | 1000 | The most lines kept; the oldest go first. 0 = no limit. |
+| `MaxBytes` | 0 (no limit) | The most bytes of text kept. A line longer than this on its own is cut, ending with `" [cut]"`. |
+
+## `Syslog`: the syslog logger (`TASWSyslogConfig`, Linux)
+
+| Setting | Default | What it does |
+|---|---|---|
+| `Ident` | empty | The name syslog shows, e.g. `myapp` in `myapp[1234]: ...`. Empty: the executable's file name. Process-wide: the syslog logger initialized last sets it. |
+| `Facility` | `SyslogFacility::User` | The facility each message is sent with. |
+
+## `EventLog`: the Windows Event Log logger (`TASWEventLogConfig`, Windows)
+
+| Setting | Default | What it does |
+|---|---|---|
+| `Source` | empty | The event source Event Viewer shows, in the Application log. Empty: the executable's file name without its extension. Register it once with `TASWWindowsEventLog::RegisterSource()` (needs administrator rights) for plain messages. |
+| `EventIds` | 1000 to 1005 | The event ID of each level's entries, indexed by level (Trace first). |
+
+## Settings from environment variables
+
+`config.ApplyEnvironment()` reads these variables, named with a prefix (`ASWLOG_` by default), and their values
+replace what the code set. Nothing reads the environment unless the application calls it. Call it after setting
+`OnError` and before `Initialize()`. A variable that isn't set or is empty changes nothing, and neither does an invalid
+value, which is reported to `OnError` (or stderr) as `ErrorKind::InvalidSetting`. Keys and values ignore case. Each
+logger can have its own prefix, e.g. `config.ApplyEnvironment("MYAPP_CONSOLE_")`. `config.ApplySetting(key, value)`
+sets one of the same settings, e.g. from a command line.
+
+| Variable | Values | Setting |
+|---|---|---|
+| `ASWLOG_LEVEL` | `Trace`, `Debug`, `Info`, `Warn`, `Error`, `Critical` or `Off` | `InitialMinimumLevel` |
+| `ASWLOG_CATEGORIES` | Category levels, e.g. `*=Info,Net=Debug,Net.Http=Trace` | `TASWCategoryLog::ApplyLevels()` (process-wide: use it under one prefix only) |
+| `ASWLOG_FOLDER` | A folder (UTF-8) | `File.FolderPath` |
+| `ASWLOG_FILE` | A file name or path (UTF-8) | `File.FilePath` |
+| `ASWLOG_FLUSH` | `EveryWrite`, `OnNewLine`, `Manual` or `Periodic` | `File.Flush` |
+| `ASWLOG_SYNC_AT_LEVEL` | A level | `File.SyncToDiskAtLevel` |
+| `ASWLOG_ASYNC` | `1`, `true`, `yes`, `on`; `0`, `false`, `no`, `off` | `Async.Enabled` |
+| `ASWLOG_BACKTRACE` | How many entries to keep; 0 = none | `Backtrace.Capacity` |
+| `ASWLOG_TIME_ZONE` | `UTC` or `Local` | `Line.TimestampZone` |
+| `ASWLOG_TIME_PRECISION` | `ms`, `us` or `ns` (or `Milliseconds`, ...) | `Line.TimestampPrecision` |
+| `ASWLOG_MULTILINE` | `Preserve`, `Indent` or `Escape` | `Line.Multiline` |
+| `ASWLOG_SHOW_FUNCTION` | As `ASWLOG_ASYNC` | `Line.ShowFunctionName` |
+| `ASWLOG_SHOW_SOURCE` | As `ASWLOG_ASYNC` | `Line.ShowSourceLine` |
+| `ASWLOG_FORMAT` | `Text` (the built-in layout) or `JSON` | `Line.Formatter` |
+| `ASWLOG_PATTERN` | A `TASWPatternFormatter` pattern, e.g. `{time} {message}` (applied after `FORMAT`) | `Line.Formatter` |
+
+For example, to see everything a deployed application logs, without rebuilding it:
+
+```text
+set ASWLOG_LEVEL=Trace
+myapp.exe
+```
+
+## Settings on the logger itself
+
+Some settings belong to the logger object rather than its config, and can be changed from any thread at any time:
+
+| Method | What it does |
+|---|---|
+| `SetMinimumLevel(level)` | The level an entry needs to be written (lock-free). |
+| `SetEnabled(enabled)` | Turns all writing off and on, forced entries included, keeping the output open (lock-free). |
+| `TASWConsoleLog::SetColorMode(mode)` | `ColorMode::Auto` (color only on a console or terminal that shows it, unless `NO_COLOR` is set), `Always` or `Never`. |
+| `TASWCategoryLog::SetMinimumLevel(level)` | A category's own level, which replaces the wrapped logger's for that category's entries. |
diff --git a/docs/CustomLoggers.md b/docs/CustomLoggers.md
new file mode 100644
index 0000000..3f4f02e
--- /dev/null
+++ b/docs/CustomLoggers.md
@@ -0,0 +1,155 @@
+# Custom formatters and loggers
+
+ASWLog can be extended without changing its sources, so a copy in a submodule or a vendored folder stays untouched:
+
+- To change how a line looks, write a **formatter**, and any text logger (file, console, ...) uses it.
+- To send lines somewhere new (a socket, a GUI control, another library), write a **text logger**: derive from
+  `TASWTextLogBase` and implement only the output. Levels, formatting, the startup and shutdown lines, asynchronous
+  writing, the backtrace, the hooks and crash handling come with it.
+- For output that isn't lines of text (e.g. passing entries on to another logging framework), derive from
+  `TASWLogBase` and implement `WriteRecord()`, as `TASWMultiLog` does.
+
+Before writing a formatter, check whether a pattern does the job, e.g.
+`std::make_shared<ASWLog::TASWPatternFormatter>("{time} {level:5} {[category] }{message}")` (see
+`ASWLog_Formatter.h` for the fields), or `TASWJSONFormatter` for JSON Lines.
+
+## A formatter
+
+A formatter derives from `IASWLogFormatter` (`ASWLog_Formatter.h`) and turns a `TASWLogRecord` into a line, without
+its line ending (the logger adds `Line.Ending`, and applies `Line.Multiline`):
+
+```cpp
+#include <format>
+#include <string>
+
+#include "ASWLog_Formatter.h"
+
+// Writes "WARN [Net] Retrying", or "INFO Started" for an entry without a category
+class TShortFormatter : public ASWLog::IASWLogFormatter
+{
+public:
+    std::string Format(const ASWLog::TASWLogRecord& record, const ASWLog::TASWLogConfig& /*config*/) const override
+    {
+        if (record.Category.empty())
+            return std::format("{} {}", ASWLog::Level_ToString(record.LogLevel), record.Message);
+
+        return std::format("{} [{}] {}", ASWLog::Level_ToString(record.LogLevel), record.Category, record.Message);
+    }
+};
+```
+
+Assign it to the config of the loggers that should use it:
+
+```cpp
+ASWLog::TASWLogConfig config;
+config.Line.Formatter = std::make_shared<TShortFormatter>();
+```
+
+- The record has the entry's time (`Timestamp`, UTC), `LogLevel`, `Message`, `Category`, source `Location`,
+  `ProcessId`, `ThreadId`, and its fields through `record.ForEachField([](const ASWLog::TASWLogField& field) {...})`.
+  `config` is the calling logger's config, e.g. for `Line.TimestampZone`.
+- Several loggers, and several threads, may call one formatter at once: keep `Format()` free of unguarded state.
+- `Format()` may throw (e.g. `std::bad_alloc`); the entry is then dropped and the logger goes on.
+- A `LogRaw()` entry is written as it is, without calling the formatter, unless `FormatsRawEntries()` returns `true`.
+
+## A text logger
+
+A text logger derives from `TASWTextLogBase` (`ASWLog_TextLogBase.h`). This one writes each line to a `std::ostream`,
+e.g. a stream that sends to a socket:
+
+```cpp
+#include <ostream>
+#include <string_view>
+
+#include "ASWLog_TextLogBase.h"
+
+// Writes each line to a std::ostream that outlives the logger
+class TStreamLog : public ASWLog::TASWTextLogBase
+{
+private:
+    std::ostream& m_Stream;
+
+protected: // TASWTextLogBase hooks, called with the logger's lock held
+    bool CloseUnlocked() override
+    {
+        m_IsOpen.store(false);
+        m_IsInitialized.store(false);
+
+        return true;
+    }
+
+    bool FlushUnlocked() override
+    {
+        m_Stream.flush();
+
+        return m_IsOpen.load() && m_Stream.good();
+    }
+
+    bool InitializeUnlocked() override
+    {
+        return OpenUnlocked();
+    }
+
+    bool OpenUnlocked() override
+    {
+        m_IsOpen.store(true);
+        m_IsInitialized.store(true);
+
+        return true;
+    }
+
+    // 'line' already ends with the line ending, unless it is a LogRaw() entry written as is
+    void WriteLineUnlocked(ASWLog::Level /*level*/, std::string_view line, bool /*endsLine*/) override
+    {
+        m_Stream << line;
+    }
+
+    std::string_view GetLoggerClassName() const noexcept override
+    {
+        return "TStreamLog";
+    }
+
+public:
+    explicit TStreamLog(std::ostream& stream) :
+        m_Stream(stream)
+    {
+    }
+
+    // Writes the shutdown line and closes the output while this class's hooks still exist
+    ~TStreamLog() override
+    {
+        Finalize();
+    }
+};
+```
+
+It is used like any other logger:
+
+```cpp
+TStreamLog log(stream);
+log.Initialize(config);
+log.LogWarnFmt("Retrying {}", host);
+```
+
+The rules for the hooks:
+
+- **Required:** `InitializeUnlocked()` (prepare and open the output), `OpenUnlocked()` (set `m_IsOpen` and
+  `m_IsInitialized`), `CloseUnlocked()` (clear them), `FlushUnlocked()` and `WriteLineUnlocked()`, plus
+  `GetLoggerClassName()` (used by `GetFullVersionStr()`).
+- **Call `Finalize()` in the destructor.** The base class can't call the hooks from its own destructor, since the
+  derived part is gone by then.
+- The hooks run with the logger's lock held, one entry at a time, so they need no locking of their own. They must not
+  log to the same logger. To call back into the application (which may log), queue the work with `DeferUnlocked()`;
+  to report a failure, call `ReportErrorUnlocked()`, which passes it to `OnError` after the lock is released.
+- An exception from a hook is caught: the entry is dropped and the failure reported, so logging still never throws.
+- **Optional hooks:** `PrepareWriteUnlocked()` (before each line, e.g. to rotate; return `false` to drop the line),
+  `ReconfigureUnlocked()` (apply a new config), `GetWorkerIntervalUnlocked()` and `OnWorkerWakeUnlocked()` (periodic
+  work on the logger's own thread, e.g. a timed flush), and, for crash handling, `FlushForCrashUnlocked()` and
+  `WriteCrashLineDirect()`. The crash hooks may run in a POSIX signal handler, so they must only do
+  async-signal-safe work (no allocation, no locks). Without them, a crash still flushes the logger through
+  `FlushUnlocked()` where it can.
+- A logger whose output exists only on some platforms can override `ShouldLog()` to return `false` elsewhere, so no
+  line is formatted there (see `TASWDebuggerLog`).
+
+The built-in loggers are examples to start from: `TASWDebuggerLog` and `TASWMemoryLog` are short, and
+`TASWFileLog` shows rotation, the worker thread and the crash hooks.
diff --git a/docs/Guarantees.md b/docs/Guarantees.md
new file mode 100644
index 0000000..c666694
--- /dev/null
+++ b/docs/Guarantees.md
@@ -0,0 +1,93 @@
+# Guarantees: thread safety, lifetime and crash durability
+
+What ASWLog promises about threads, object lifetimes and crashes, and how to choose the settings that trade speed for
+durability. The header comments have the details of each class and setting.
+
+## Logging never throws
+
+Every logging method is `noexcept`, and so is every other method of `IASWLog` except `GetFullVersionStr()`. A logger
+reports a failure by returning `false` (`Initialize()`, `Reconfigure()`, `Open()`, `Close()`, `Flush()`) or by
+dropping the entry, and reports its internal failures (e.g. a log file that can't be opened, written or rotated) to
+`TASWLogConfig::OnError`, or to stderr if that is empty. A `*Fmt` format string that fails at run time (only possible
+with `RuntimeFormat()`) writes the error in the entry's line instead of the message.
+
+## Thread safety
+
+- Every logger is thread-safe: any thread may log, flush, open, close or reconfigure it at any time.
+- `SetMinimumLevel()`, `SetEnabled()` and the level check of a logging call are lock-free.
+- `Reconfigure()` is safe while other threads log: the entries written after it returns use the new settings.
+  `GetConfig()` returns an immutable snapshot that stays valid after a later `Reconfigure()`.
+- A text logger writes one entry at a time under its own lock, so lines from different threads never mix.
+- A category logger is lock-free (making or destroying one takes a short process-wide lock). A multi-log guards its
+  list of loggers, and each of its loggers its own output.
+- Scoped fields (`TASWLogScope`) belong to the thread that made them; `TASWLogScope::Capture()` copies them for
+  another thread.
+- Several processes can share one log file with `File.AutoOpenClosePerWrite`, which opens and closes the file for
+  every entry (slower, but no process keeps it open).
+
+## Timestamps and order
+
+- An entry's time, process id and thread id are taken on the calling thread, during the call (after the level check,
+  so a filtered call doesn't read the clock). The time is when the event happened, not when the logger got to it.
+- One thread's entries are written in the order it logged them, also with asynchronous writing, which uses one queue.
+- Entries that two threads log at the same moment can be written in either order, so the times in a log can step back
+  slightly between lines of different threads.
+
+## Which thread runs a callback
+
+| Callback | Thread | Notes |
+|---|---|---|
+| `OnBeforeWrite` | The logging thread, before the logger takes its lock or queues the entry | Threads that log at once call it at once: keep it thread-safe and quick. It may log to another logger; an entry logged from inside it, on its thread, skips the hooks. If it throws, the entry is dropped and the exception reported. |
+| `OnLogEntry` | The logging thread after the entry is written, outside the lock; with `Async.Enabled`, the logger's own thread | Exceptions are swallowed. The record and line are only valid during the call. |
+| `OnError` | A thread that was using the logger (logging, `Flush()`, `Close()`, ...), outside the lock, or the logger's own thread (e.g. a failed periodic flush) | It may log, even to the failing logger: failures caused by the handler itself aren't reported again. Exceptions are swallowed. |
+| `File.OnBackupCreated` | The thread whose call rotated the log (a logging call, `Initialize()`, `Reconfigure()` or `RotateLogFiles()`; with `Async.Enabled`, the logger's own thread), outside the lock | That call waits for it: hand slow work (compressing, uploading) to another thread. Exceptions are swallowed. |
+
+## Lifetime
+
+- **Singletons.** `GetInstance()` (file, console, debugger, syslog, Windows Event Log and null loggers) returns an
+  instance that is never destroyed, so it can be used until the process ends, e.g. from another static object's
+  destructor or a thread still running at exit. At exit it is finalized (shutdown line, flush, close) in static
+  destruction order: a static object constructed after the first `GetInstance()` call can still log from its
+  destructor. In a Windows DLL or package that is unloaded before the process ends, `Close()` a logger that uses
+  `FlushMode::Periodic` (or `Async`) before unloading, since stopping its thread during the unload can deadlock.
+- **Instances.** A logger you create writes its shutdown line, writes the entries still queued, flushes and closes in
+  its destructor.
+- **Multi-log.** `TASWMultiLog` holds its loggers by reference and doesn't own them: each must outlive the multi-log,
+  or be removed from it (`RemoveLogger()`) first.
+- **Category.** The logger a `TASWCategoryLog` wraps must outlive the category, and must not be a multi-log that
+  holds the category.
+- **Scopes.** A `TASWLogScope` must end on the thread that made it, in the reverse order of making, as local variables
+  do. It copies its keys and texts, so they may be temporaries.
+- **Fields of a call.** The keys and texts of an entry's fields are only read during the call, so they may be
+  temporaries too; a logger that keeps the entry (asynchronous writing, the backtrace) copies them.
+
+## Crash durability
+
+ASWLog's first purpose is that the last entries before a crash are in the log. The defaults are the most durable;
+each faster option says what it gives up.
+
+| Setting | What reaches the file | Cost per entry |
+|---|---|---|
+| Default: synchronous, `File.Flush = EveryWrite` | Every entry is handed to the operating system before the call returns, so it survives an application crash. | One write and flush per entry. |
+| `File.Flush = Periodic`, `Manual` or `OnNewLine` | Entries wait in the logger's buffer until a flush. Entries at or above `File.FlushImmediatelyAtLevel` (Error by default) are still flushed at once. On a crash, the crash handlers (below) flush the buffer. | Less I/O; fewer, larger writes. |
+| `File.SyncToDiskAtLevel` (e.g. `Level::Error`) | Those entries are also synced to the disk, so they survive a power loss or a system crash. | A sync often takes milliseconds: use it for rare entries. |
+| `Async.Enabled` | The call only formats and queues the entry; the logger's thread writes it. Entries at or above `Async.WaitAtLevel` (Error by default) wait until they are written and flushed. On a crash, the handlers give the logger's thread up to `TASWCrashHandlerOptions::WaitTimeout` (1 s) to write the queue. | The call doesn't wait for the output. |
+| `Backtrace.Capacity` | The last N entries below the minimum level are kept in memory and written just before the next Error, on `DumpBacktrace()`, or on a crash. | About the cost of copying the message, for entries that would otherwise be filtered. |
+
+**Crash handlers.** `ASWLog::InstallCrashHandlers()` (in `ASWLog_CrashHandler.h`) catches `std::terminate()`,
+`abort()` and fatal faults (an access violation on Windows, SIGSEGV and the like on Linux). Every initialized text
+logger is then flushed, including its buffered and queued entries, and gets a Critical "Crash: <reason>" line, before
+the crash is passed on to the handler installed before (so error reports and core dumps still happen). This is best
+effort, since a crashed process may be in any state; the header lists what is and isn't handled. An application with
+its own crash reporter can call `ASWLog::HandleCrash()` from it instead.
+
+### Choosing settings
+
+| Goal | Settings |
+|---|---|
+| Find the cause of any crash (the default) | The defaults; call `InstallCrashHandlers()` early in `main()`. |
+| Less I/O for a busy log, errors still at once | `File.Flush = FlushMode::Periodic` (every `File.FlushInterval`, 1 s by default) and `InstallCrashHandlers()`. `File.FlushImmediatelyAtLevel` stays at Error. |
+| Errors that survive a power loss | `File.SyncToDiskAtLevel = Level::Error`. |
+| Logging calls that don't wait for a slow disk | `Async.Enabled = true`; `Async.WaitAtLevel` stays at Error, and `InstallCrashHandlers()`. |
+| The details leading up to an error, without logging them all | `InitialMinimumLevel = Level::Info` and `Backtrace.Capacity = 200` (or another count). |
+| Full verbosity in a deployed build, without rebuilding | `config.ApplyEnvironment()` before `Initialize()`, then run with `ASWLOG_LEVEL=Trace` (see [Configuration.md](Configuration.md#settings-from-environment-variables)). |
diff --git a/example/src/main.cpp b/example/src/main.cpp
index f752fd8..0070f5b 100644
--- a/example/src/main.cpp
+++ b/example/src/main.cpp
@@ -28,8 +28,10 @@ limitations under the License.
 #include "ASWLog_CategoryLog.h"
 #include "ASWLog_ConsoleLog.h"
 #include "ASWLog_CrashHandler.h"
+#include "ASWLog_DebuggerLog.h"
 #include "ASWLog_Fields.h"
 #include "ASWLog_FileLog.h"
+#include "ASWLog_Limiter.h"
 #include "ASWLog_MultiLog.h"
 #include "ASWLog_Utils.h"
 //---------------------------------------------------------------------------
@@ -103,6 +105,10 @@ int main(int argc, char* argv[])
     globalConfig.Line.ShowWorkingSet = true;
     globalConfig.Line.ShowPeakWorkingSet = true;
 
+    // Environment variables may replace these settings, e.g. ASWLOG_LEVEL=Info or ASWLOG_FORMAT=JSON, so a deployed
+    // build can log differently without being rebuilt. Unset variables change nothing.
+    globalConfig.ApplyEnvironment();
+
     // Get singleton instance - the logger supports singleton and non-singleton instances
     auto& globalLogger = ASWLog::TASWFileLog::GetInstance();
     if (!globalLogger.Initialize(globalConfig))
@@ -141,6 +147,14 @@ int main(int argc, char* argv[])
     // New C++ 'format' is supported
     globalLogger.LogCriticalFmt("CRITICAL EVENT BOUNDARY RECOVERY CODE: {:X}", 0xDEADBEEF);
 
+    // Rate limiting: of these 25 warnings in a loop, only the 1st, 11th and 21st are written
+    for (int attempt = 1; attempt <= 25; ++attempt)
+        ASWLOG_EVERY_N(globalLogger, 10, ASWLog::Level::Warn, "Retrying the connection, attempt {}", attempt);
+
+    // Wide text (e.g. C++Builder's UnicodeString::c_str()) is written as UTF-8, here "Wide text: cafe" with an e acute
+    globalLogger.LogInfo(L"Wide text: caf\x00E9");
+    globalLogger.LogInfoFmt("Opened {}", ASWLog::Wide(L"C:\\Data\\report.txt"));
+
     // Example of independent standalone/local logger instance
     std::cout << "Testing independent local stack instance execution...\n";
     ASWLog::TASWLogConfig localConfig;
@@ -191,19 +205,27 @@ int main(int argc, char* argv[])
         std::cout << "Console logger failed to initialize!\n";
     }
 
-    // Example of fanning a single call out to multiple sinks at once
-    std::cout << "Testing multi-sink logger (file + console fan-out)...\n";
+    // The debugger's output: on Windows, the RAD Studio Event Log, Visual Studio's Output window or DebugView; it writes
+    // nothing on other platforms
+    ASWLog::TASWDebuggerLog debuggerLogger;
+    if (!debuggerLogger.Initialize(consoleConfig))
+        std::cout << "Debugger logger failed to initialize!\n";
+
+    // Example of fanning a single call out to multiple sinks at once. The multi-log doesn't own its loggers, so they
+    // are declared before it and outlive it.
+    std::cout << "Testing multi-sink logger (file + console + debugger fan-out)...\n";
     ASWLog::TASWMultiLog multiLogger;
-    multiLogger.AddLogger(globalLogger);  // Reuses the already-initialized file singleton
-    multiLogger.AddLogger(consoleLogger); // Reuses the already-initialized console logger
+    multiLogger.AddLogger(globalLogger);   // Reuses the already-initialized file singleton
+    multiLogger.AddLogger(consoleLogger);  // Reuses the already-initialized console logger
+    multiLogger.AddLogger(debuggerLogger); // Reuses the already-initialized debugger logger
 
     // One call reaches every registered sink; each sink still applies its own level and formatting
-    multiLogger.LogInfo("This single call is written to both the log file and the console.");
+    multiLogger.LogInfo("This single call is written to the log file, the console and the debugger output.");
 
     // The composite's own level is an optional pre-filter, independent of each sink's own level
     multiLogger.SetMinimumLevel(ASWLog::Level::Error);
-    multiLogger.LogWarn("This Warn is suppressed by the composite gate before reaching either sink.");
-    multiLogger.LogError("This Error clears the composite gate and reaches both sinks.");
+    multiLogger.LogWarn("This Warn is suppressed by the composite gate before reaching any sink.");
+    multiLogger.LogError("This Error clears the composite gate and reaches every sink.");
 
     // Example of categories: each entry shows its category after the level, e.g. "[Db]", and a category with a level
     // of its own uses it instead of the wrapped logger's (Trace here)

From f094d20e501bdc7607edb42d1a8cf38fad57f902 Mon Sep 17 00:00:00 2001
From: Anthony West <anthony.s.west@gmail.com>
Date: Sat, 10 Oct 2026 19:00:32 -0700
Subject: [PATCH 03/12] Write the ASWLog version in the startup lines

---
 ASWLog/ASWLog_Config.h                      |  3 +++
 ASWLog/ASWLog_TextLogBase.cpp               | 10 ++++++++
 ASWLog/ASWLog_TextLogBase.h                 |  1 +
 CHANGELOG.md                                |  5 ++++
 README.md                                   |  6 +++--
 docs/Configuration.md                       |  1 +
 tests/tests/Test_ASWLog_CategoryLog.cpp     |  1 +
 tests/tests/Test_ASWLog_Config.cpp          |  2 ++
 tests/tests/Test_ASWLog_ConsoleLog.cpp      |  1 +
 tests/tests/Test_ASWLog_CrashHandler.cpp    |  1 +
 tests/tests/Test_ASWLog_DebuggerLog.cpp     |  1 +
 tests/tests/Test_ASWLog_Fields.cpp          |  1 +
 tests/tests/Test_ASWLog_FileLog.cpp         |  2 ++
 tests/tests/Test_ASWLog_Formatter.cpp       |  1 +
 tests/tests/Test_ASWLog_Limiter.cpp         |  1 +
 tests/tests/Test_ASWLog_MemoryLog.cpp       |  1 +
 tests/tests/Test_ASWLog_MultiLog.cpp        |  1 +
 tests/tests/Test_ASWLog_SyslogLog.cpp       |  1 +
 tests/tests/Test_ASWLog_TextLogBase.cpp     | 28 +++++++++++++++++++++
 tests/tests/Test_ASWLog_TextLogBase.h       |  1 +
 tests/tests/Test_ASWLog_Unicode.cpp         |  1 +
 tests/tests/Test_ASWLog_WindowsEventLog.cpp |  1 +
 22 files changed, 69 insertions(+), 2 deletions(-)

diff --git a/ASWLog/ASWLog_Config.h b/ASWLog/ASWLog_Config.h
index f3b08bd..ffdb7d5 100644
--- a/ASWLog/ASWLog_Config.h
+++ b/ASWLog/ASWLog_Config.h
@@ -305,6 +305,9 @@ struct TASWStartupConfig
     bool WriteApplicationInfo  = true;
     bool WriteCommandLine      = false; // Added to the application info line
     bool WriteDriveInfo        = true;
+    // "ASWLog: version=<ASWLOG_VERSION_STRING>, logger=<class>", the first line after the banner, so a log says which
+    // ASWLog wrote it
+    bool WriteLoggerVersion    = true;
     bool WriteMemoryUsage      = true;
     bool WriteOSInfo           = true;
     bool WriteSystemMemoryInfo = true;
diff --git a/ASWLog/ASWLog_TextLogBase.cpp b/ASWLog/ASWLog_TextLogBase.cpp
index 1e23e66..dbdeef4 100644
--- a/ASWLog/ASWLog_TextLogBase.cpp
+++ b/ASWLog/ASWLog_TextLogBase.cpp
@@ -31,6 +31,7 @@ limitations under the License.
 //---------------------------------------------------------------------------
 #include "ASWLog_CrashHandler.h"
 #include "ASWLog_Utils.h"
+#include "ASWLog_Version.h"
 //---------------------------------------------------------------------------
 
 namespace ASWLog
@@ -977,6 +978,9 @@ void TASWTextLogBase::WriteInfoLine(std::string_view message, std::source_locati
 //---------------------------------------------------------------------------
 void TASWTextLogBase::WriteInitializationInfo()
 {
+    if (GetConfigUnlocked().Startup.WriteLoggerVersion)
+        WriteLoggerVersionInfo();
+
     if (GetConfigUnlocked().Startup.WriteTimeInfo)
         WriteTimeInfo();
 
@@ -1019,6 +1023,12 @@ std::string TASWTextLogBase::WriteLogEntry(const TASWLogRecord& record)
     return line;
 }
 
+//---------------------------------------------------------------------------
+void TASWTextLogBase::WriteLoggerVersionInfo()
+{
+    WriteInfoLine(std::format("ASWLog: version={}, logger={}", Version, GetLoggerClassName()));
+}
+
 //---------------------------------------------------------------------------
 void TASWTextLogBase::WriteMemoryUsageInfo()
 {
diff --git a/ASWLog/ASWLog_TextLogBase.h b/ASWLog/ASWLog_TextLogBase.h
index bbcc4cb..5cf6a89 100644
--- a/ASWLog/ASWLog_TextLogBase.h
+++ b/ASWLog/ASWLog_TextLogBase.h
@@ -209,6 +209,7 @@ class TASWTextLogBase : public TASWLogBase
     void WriteInfoLine(std::string_view message, std::source_location loc = std::source_location::current());
     void WriteInitializationInfo();
     std::string WriteLogEntry(const TASWLogRecord& record);
+    void WriteLoggerVersionInfo();
     void WriteMemoryUsageInfo();
     void WriteOSInfo();
     void WriteQueuedEntries(std::deque<TQueuedEntry>& entries, std::size_t droppedCount) noexcept;
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d171850..bc44842 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -254,6 +254,11 @@ see [0.26.1](#0261---2026-09-17) for the initial versioned baseline.
   the library is now named `ASWLogd` (e.g. `ASWLogd.lib`), so Debug and
   Release can share an install prefix; nothing changes for code that links to
   the `ASWLog::ASWLog` target.
+- The ASWLog version in the startup lines: right after the banner, a text
+  logger writes e.g. `ASWLog: version=1.0.0, logger=TASWFileLog`, so a log
+  from the field says which ASWLog (and which logger) wrote it. On by
+  default; `Startup.WriteLoggerVersion = false` leaves it out, which code that
+  turns off every startup line one by one must now add.
 
 ### Changed
 
diff --git a/README.md b/README.md
index 766fd92..f307b23 100644
--- a/README.md
+++ b/README.md
@@ -24,7 +24,8 @@ pattern formatters, crash handlers, and the other extras below) is opt-in.
   against their arguments at compile time; wrap one built at run time in `ASWLog::RuntimeFormat()`.
 - Runtime `Open()`, `Close()`, `Flush()` and log rotation controls, and `Reconfigure()` to change settings safely
   while other threads log.
-- Optional application and system memory, OS, drive, time, and command-line diagnostics.
+- Optional startup diagnostics: the ASWLog version, application and system memory, OS, drive, time, and the command
+  line.
 - Retry handling for temporary file access conflicts and Windows reader-sharing support.
 - Crash durability: every entry is flushed by default, and with buffered flushing Error and Critical entries still
   are (`File.FlushImmediatelyAtLevel`). Entries at a chosen level can also be synced to disk to survive a power loss
@@ -116,7 +117,8 @@ int main()
 }
 ```
 
-writes `logs/myapp.txt`, after the startup lines (time, OS, drive, memory, application; see `TASWLogConfig::Startup`):
+writes `logs/myapp.txt`, after the startup lines (ASWLog version, time, OS, drive, memory, application; see
+`TASWLogConfig::Startup`):
 
 ```text
 [2026-10-11T00:24:25.089Z][INFO][P:6180][T:6648]: Started
diff --git a/docs/Configuration.md b/docs/Configuration.md
index de42c30..baf40c8 100644
--- a/docs/Configuration.md
+++ b/docs/Configuration.md
@@ -85,6 +85,7 @@ The `Show*` settings are read by the built-in layout and by `TASWJSONFormatter`;
 | Setting | Default | What it does |
 |---|---|---|
 | `Banner` | empty | A line written first, if set. |
+| `WriteLoggerVersion` | `true` | The ASWLog version and the logger's class, right after the banner, e.g. `ASWLog: version=1.0.0, logger=TASWFileLog`, so a log says which ASWLog wrote it. |
 | `WriteApplicationInfo` | `true` | The executable's path and build target, e.g. `App: app_exe='C:\MyApp\MyApp.exe', app_target=Win64`. |
 | `WriteCommandLine` | `false` | The command line, added to the application line. |
 | `WriteDriveInfo` | `true` | The disk's total, free and used space. |
diff --git a/tests/tests/Test_ASWLog_CategoryLog.cpp b/tests/tests/Test_ASWLog_CategoryLog.cpp
index d8a7be3..5f53668 100644
--- a/tests/tests/Test_ASWLog_CategoryLog.cpp
+++ b/tests/tests/Test_ASWLog_CategoryLog.cpp
@@ -185,6 +185,7 @@ ASWLog::TASWLogConfig MakeFileConfig(const std::filesystem::path& file)
     config.Line.ShowProcessId = false;
     config.Line.ShowThreadId = false;
     config.Shutdown.WriteLine = false;
+    config.Startup.WriteLoggerVersion = false;
     config.Startup.WriteTimeInfo = false;
     config.Startup.WriteOSInfo = false;
     config.Startup.WriteDriveInfo = false;
diff --git a/tests/tests/Test_ASWLog_Config.cpp b/tests/tests/Test_ASWLog_Config.cpp
index 7acea5a..305dcc1 100644
--- a/tests/tests/Test_ASWLog_Config.cpp
+++ b/tests/tests/Test_ASWLog_Config.cpp
@@ -341,6 +341,7 @@ void TTest_ASWLog_Config::Test_ApplyEnvironment_SeedsTheLevelAtInitialize()
     config.Startup.WriteMemoryUsage = false;
     config.Startup.WriteOSInfo = false;
     config.Startup.WriteSystemMemoryInfo = false;
+    config.Startup.WriteLoggerVersion = false;
     config.Startup.WriteTimeInfo = false;
     config.Shutdown.WriteLine = false;
     ASWLog::TASWMemoryLog log;
@@ -555,6 +556,7 @@ void TTest_ASWLog_Config::Test_Defaults_MatchDocumentedValues()
     CheckTrue(config.Startup.WriteApplicationInfo, "Startup.WriteApplicationInfo should default to true");
     CheckFalse(config.Startup.WriteCommandLine, "Startup.WriteCommandLine should default to false");
     CheckTrue(config.Startup.WriteDriveInfo, "Startup.WriteDriveInfo should default to true");
+    CheckTrue(config.Startup.WriteLoggerVersion, "Startup.WriteLoggerVersion should default to true");
     CheckTrue(config.Startup.WriteMemoryUsage, "Startup.WriteMemoryUsage should default to true");
     CheckTrue(config.Startup.WriteOSInfo, "Startup.WriteOSInfo should default to true");
     CheckTrue(config.Startup.WriteSystemMemoryInfo, "Startup.WriteSystemMemoryInfo should default to true");
diff --git a/tests/tests/Test_ASWLog_ConsoleLog.cpp b/tests/tests/Test_ASWLog_ConsoleLog.cpp
index d158eda..bb6418d 100644
--- a/tests/tests/Test_ASWLog_ConsoleLog.cpp
+++ b/tests/tests/Test_ASWLog_ConsoleLog.cpp
@@ -191,6 +191,7 @@ ASWLog::TASWLogConfig MakeQuietConfig()
     config.Line.ShowFunctionName = false;
     config.Line.ShowSourceLine = false;
     config.Shutdown.WriteLine = false;
+    config.Startup.WriteLoggerVersion = false;
     config.Startup.WriteTimeInfo = false;
     config.Startup.WriteOSInfo = false;
     config.Startup.WriteDriveInfo = false;
diff --git a/tests/tests/Test_ASWLog_CrashHandler.cpp b/tests/tests/Test_ASWLog_CrashHandler.cpp
index 26e251b..66ee3c4 100644
--- a/tests/tests/Test_ASWLog_CrashHandler.cpp
+++ b/tests/tests/Test_ASWLog_CrashHandler.cpp
@@ -270,6 +270,7 @@ ASWLog::TASWLogConfig MakeCrashTestConfig(const std::filesystem::path& fileName)
     config.Line.ShowFunctionName = false;
     config.Line.ShowSourceLine = false;
     config.Shutdown.WriteLine = false;
+    config.Startup.WriteLoggerVersion = false;
     config.Startup.WriteTimeInfo = false;
     config.Startup.WriteOSInfo = false;
     config.Startup.WriteDriveInfo = false;
diff --git a/tests/tests/Test_ASWLog_DebuggerLog.cpp b/tests/tests/Test_ASWLog_DebuggerLog.cpp
index c91ec50..b8c6b02 100644
--- a/tests/tests/Test_ASWLog_DebuggerLog.cpp
+++ b/tests/tests/Test_ASWLog_DebuggerLog.cpp
@@ -84,6 +84,7 @@ ASWLog::TASWLogConfig MakeDebuggerConfig()
     config.Line.ShowProcessId = false;
     config.Line.ShowThreadId = false;
     config.Shutdown.WriteLine = false;
+    config.Startup.WriteLoggerVersion = false;
     config.Startup.WriteTimeInfo = false;
     config.Startup.WriteOSInfo = false;
     config.Startup.WriteDriveInfo = false;
diff --git a/tests/tests/Test_ASWLog_Fields.cpp b/tests/tests/Test_ASWLog_Fields.cpp
index 3ccce80..62bcf31 100644
--- a/tests/tests/Test_ASWLog_Fields.cpp
+++ b/tests/tests/Test_ASWLog_Fields.cpp
@@ -256,6 +256,7 @@ void TTest_ASWLog_Fields::Test_Async_OnLogEntryGetsTheFieldsAfterTheScopeEnds()
     config.File.FilePath = "async.log";
     config.File.OpenRetryCount = 1;
     config.Async.Enabled = true;
+    config.Startup.WriteLoggerVersion = false;
     config.Startup.WriteTimeInfo = false;
     config.Startup.WriteOSInfo = false;
     config.Startup.WriteDriveInfo = false;
diff --git a/tests/tests/Test_ASWLog_FileLog.cpp b/tests/tests/Test_ASWLog_FileLog.cpp
index 3a772b6..fd0ad67 100644
--- a/tests/tests/Test_ASWLog_FileLog.cpp
+++ b/tests/tests/Test_ASWLog_FileLog.cpp
@@ -293,6 +293,7 @@ ASWLog::TASWLogConfig MakeRotationTestConfig(const std::filesystem::path& logFil
     config.Line.ShowThreadId = false;
     config.Line.ShowFunctionName = false;
     config.Line.ShowSourceLine = false;
+    config.Startup.WriteLoggerVersion = false;
     config.Startup.WriteTimeInfo = false;
     config.Startup.WriteOSInfo = false;
     config.Startup.WriteDriveInfo = false;
@@ -1460,6 +1461,7 @@ void TTest_ASWLog_FileLog::Test_InitializeAndLogInfo_WritesText()
     config.Line.ShowPeakWorkingSet = false;
     config.Line.ShowFunctionName = false;
     config.Line.ShowSourceLine = false;
+    config.Startup.WriteLoggerVersion = false;
     config.Startup.WriteTimeInfo = false;
     config.Startup.WriteOSInfo = false;
     config.Startup.WriteDriveInfo = false;
diff --git a/tests/tests/Test_ASWLog_Formatter.cpp b/tests/tests/Test_ASWLog_Formatter.cpp
index 12ae67c..dd3f3a7 100644
--- a/tests/tests/Test_ASWLog_Formatter.cpp
+++ b/tests/tests/Test_ASWLog_Formatter.cpp
@@ -134,6 +134,7 @@ ASWLog::TASWLogConfig MakeConfigWithoutFields(const std::filesystem::path& file)
     config.Line.ShowSourceLine = false;
     config.File.OpenRetryCount = 1;
     config.Shutdown.WriteLine = false;
+    config.Startup.WriteLoggerVersion = false;
     config.Startup.WriteTimeInfo = false;
     config.Startup.WriteOSInfo = false;
     config.Startup.WriteDriveInfo = false;
diff --git a/tests/tests/Test_ASWLog_Limiter.cpp b/tests/tests/Test_ASWLog_Limiter.cpp
index 2498066..3ef8207 100644
--- a/tests/tests/Test_ASWLog_Limiter.cpp
+++ b/tests/tests/Test_ASWLog_Limiter.cpp
@@ -84,6 +84,7 @@ ASWLog::TASWLogConfig MakeLimiterConfig()
     config.Line.ShowProcessId = false;
     config.Line.ShowThreadId = false;
     config.Shutdown.WriteLine = false;
+    config.Startup.WriteLoggerVersion = false;
     config.Startup.WriteTimeInfo = false;
     config.Startup.WriteOSInfo = false;
     config.Startup.WriteDriveInfo = false;
diff --git a/tests/tests/Test_ASWLog_MemoryLog.cpp b/tests/tests/Test_ASWLog_MemoryLog.cpp
index 8a3f029..185bdc7 100644
--- a/tests/tests/Test_ASWLog_MemoryLog.cpp
+++ b/tests/tests/Test_ASWLog_MemoryLog.cpp
@@ -60,6 +60,7 @@ ASWLog::TASWLogConfig MakeMemoryConfig(std::size_t maxLines = 1000, std::size_t
     config.Line.ShowProcessId = false;
     config.Line.ShowThreadId = false;
     config.Shutdown.WriteLine = false;
+    config.Startup.WriteLoggerVersion = false;
     config.Startup.WriteTimeInfo = false;
     config.Startup.WriteOSInfo = false;
     config.Startup.WriteDriveInfo = false;
diff --git a/tests/tests/Test_ASWLog_MultiLog.cpp b/tests/tests/Test_ASWLog_MultiLog.cpp
index 16523a0..e339dcb 100644
--- a/tests/tests/Test_ASWLog_MultiLog.cpp
+++ b/tests/tests/Test_ASWLog_MultiLog.cpp
@@ -248,6 +248,7 @@ ASWLog::TASWLogConfig MakeFileConfig(const std::filesystem::path& dir, const std
     config.Line.ShowSourceLine = false;
     config.File.OpenRetryCount = 1;
     config.Shutdown.WriteLine = false;
+    config.Startup.WriteLoggerVersion = false;
     config.Startup.WriteTimeInfo = false;
     config.Startup.WriteOSInfo = false;
     config.Startup.WriteDriveInfo = false;
diff --git a/tests/tests/Test_ASWLog_SyslogLog.cpp b/tests/tests/Test_ASWLog_SyslogLog.cpp
index 60822ff..85f1ca9 100644
--- a/tests/tests/Test_ASWLog_SyslogLog.cpp
+++ b/tests/tests/Test_ASWLog_SyslogLog.cpp
@@ -89,6 +89,7 @@ ASWLog::TASWLogConfig MakeSyslogConfig()
     config.Line.ShowProcessId = false;
     config.Line.ShowThreadId = false;
     config.Shutdown.WriteLine = false;
+    config.Startup.WriteLoggerVersion = false;
     config.Startup.WriteTimeInfo = false;
     config.Startup.WriteOSInfo = false;
     config.Startup.WriteDriveInfo = false;
diff --git a/tests/tests/Test_ASWLog_TextLogBase.cpp b/tests/tests/Test_ASWLog_TextLogBase.cpp
index e160266..7dccc0c 100644
--- a/tests/tests/Test_ASWLog_TextLogBase.cpp
+++ b/tests/tests/Test_ASWLog_TextLogBase.cpp
@@ -49,6 +49,7 @@ limitations under the License.
 #include "ASWLog_FileLog.h"
 #include "ASWLog_Formatter.h"
 #include "ASWLog_TextLogBase.h"
+#include "ASWLog_Version.h"
 //---------------------------------------------------------------------------
 
 namespace ASWUnitTests
@@ -342,6 +343,7 @@ ASWLog::TASWLogConfig MakeQuietConfig()
     config.Line.ShowSourceLine = false;
     config.File.OpenRetryCount = 1;
     config.Shutdown.WriteLine = false;
+    config.Startup.WriteLoggerVersion = false;
     config.Startup.WriteTimeInfo = false;
     config.Startup.WriteOSInfo = false;
     config.Startup.WriteDriveInfo = false;
@@ -418,6 +420,7 @@ TTest_ASWLog_TextLogBase::TTest_ASWLog_TextLogBase()
     RegisterTest(&TTest_ASWLog_TextLogBase::Test_Flush_ThrowingHookDoesNotEscape, "Flush_ThrowingHookDoesNotEscape");
     RegisterTest(&TTest_ASWLog_TextLogBase::Test_Formatter_FormatsEveryFileLine, "Formatter_FormatsEveryFileLine");
     RegisterTest(&TTest_ASWLog_TextLogBase::Test_Initialize_ThrowingFormatterStillInitializes, "Initialize_ThrowingFormatterStillInitializes");
+    RegisterTest(&TTest_ASWLog_TextLogBase::Test_Initialize_WritesLoggerVersionAfterTheBanner, "Initialize_WritesLoggerVersionAfterTheBanner");
     RegisterTest(&TTest_ASWLog_TextLogBase::Test_Initialize_WritesStartupLinesThenCallsAfterEntry, "Initialize_WritesStartupLinesThenCallsAfterEntry");
     RegisterTest(&TTest_ASWLog_TextLogBase::Test_Log_AtLevelOffIsNeverWritten, "Log_AtLevelOffIsNeverWritten");
     RegisterTest(&TTest_ASWLog_TextLogBase::Test_Log_DroppedWhenNotReadyOrNotPrepared, "Log_DroppedWhenNotReadyOrNotPrepared");
@@ -1096,6 +1099,31 @@ void TTest_ASWLog_TextLogBase::Test_Initialize_ThrowingFormatterStillInitializes
         "The skipped startup lines and the dropped entry should be reported");
 }
 //---------------------------------------------------------------------------
+void TTest_ASWLog_TextLogBase::Test_Initialize_WritesLoggerVersionAfterTheBanner()
+{
+    // Arrange
+    TMemoryOutput output;
+    TMemoryTextLog log(output);
+    auto config = MakeQuietConfig();
+    config.Startup.Banner = "starting";
+    config.Startup.WriteLoggerVersion = true;
+    config.Startup.WriteTimeInfo = true;
+
+    // Act
+    const bool initialized = log.Initialize(config);
+
+    // Assert
+    CheckTrue(initialized, "Initialize should succeed");
+    CheckEquals(3, output.Lines.size(), "Initialize should write the banner, the version line and the time line");
+    if (output.Lines.size() == 3)
+    {
+        CheckEquals(std::string("[INFO]: starting\n"), output.Lines[0], "The banner should come first");
+        CheckEquals(std::format("[INFO]: ASWLog: version={}, logger=TMemoryTextLog\n", ASWLog::Version), output.Lines[1],
+            "The version line should follow the banner, with the version and the logger's class");
+        CheckStartsWith(output.Lines[2], "[INFO]: Time: ", "The other startup lines should follow: " + output.Lines[2]);
+    }
+}
+//---------------------------------------------------------------------------
 void TTest_ASWLog_TextLogBase::Test_Initialize_WritesStartupLinesThenCallsAfterEntry()
 {
     // Arrange
diff --git a/tests/tests/Test_ASWLog_TextLogBase.h b/tests/tests/Test_ASWLog_TextLogBase.h
index f3b5e9a..e7b5819 100644
--- a/tests/tests/Test_ASWLog_TextLogBase.h
+++ b/tests/tests/Test_ASWLog_TextLogBase.h
@@ -55,6 +55,7 @@ class TTest_ASWLog_TextLogBase : public TTestGroupBase
     void Test_Flush_ThrowingHookDoesNotEscape();
     void Test_Formatter_FormatsEveryFileLine();
     void Test_Initialize_ThrowingFormatterStillInitializes();
+    void Test_Initialize_WritesLoggerVersionAfterTheBanner();
     void Test_Initialize_WritesStartupLinesThenCallsAfterEntry();
     void Test_Log_AtLevelOffIsNeverWritten();
     void Test_Log_DroppedWhenNotReadyOrNotPrepared();
diff --git a/tests/tests/Test_ASWLog_Unicode.cpp b/tests/tests/Test_ASWLog_Unicode.cpp
index b8c3b39..e1612ad 100644
--- a/tests/tests/Test_ASWLog_Unicode.cpp
+++ b/tests/tests/Test_ASWLog_Unicode.cpp
@@ -254,6 +254,7 @@ ASWLog::TASWLogConfig MakeQuietConfig()
     config.Startup.WriteMemoryUsage = false;
     config.Startup.WriteOSInfo = false;
     config.Startup.WriteSystemMemoryInfo = false;
+    config.Startup.WriteLoggerVersion = false;
     config.Startup.WriteTimeInfo = false;
     return config;
 }
diff --git a/tests/tests/Test_ASWLog_WindowsEventLog.cpp b/tests/tests/Test_ASWLog_WindowsEventLog.cpp
index 400b6e6..4b9d3b8 100644
--- a/tests/tests/Test_ASWLog_WindowsEventLog.cpp
+++ b/tests/tests/Test_ASWLog_WindowsEventLog.cpp
@@ -88,6 +88,7 @@ ASWLog::TASWLogConfig MakeEventLogConfig()
     config.Line.ShowProcessId = false;
     config.Line.ShowThreadId = false;
     config.Shutdown.WriteLine = false;
+    config.Startup.WriteLoggerVersion = false;
     config.Startup.WriteTimeInfo = false;
     config.Startup.WriteOSInfo = false;
     config.Startup.WriteDriveInfo = false;

From 55c9e7e7bfcd54c6f6f0dc96c1d3db0a6b516be8 Mon Sep 17 00:00:00 2001
From: Anthony West <anthony.s.west@gmail.com>
Date: Sat, 10 Oct 2026 19:45:19 -0700
Subject: [PATCH 04/12] Write the application's version in the startup lines

---
 ASWLog/ASWLog_Config.h                  |  3 ++
 ASWLog/ASWLog_TextLogBase.cpp           | 13 ++++-
 ASWLog/ASWLog_Utils.cpp                 | 60 +++++++++++++++++++++
 ASWLog/ASWLog_Utils.h                   |  7 +++
 CHANGELOG.md                            |  8 +++
 README.md                               |  4 +-
 docs/Configuration.md                   |  3 +-
 tests/tests/Test_ASWLog_Config.cpp      |  1 +
 tests/tests/Test_ASWLog_TextLogBase.cpp | 56 ++++++++++++++++++++
 tests/tests/Test_ASWLog_TextLogBase.h   |  2 +
 tests/tests/Test_ASWLog_Utils.cpp       | 70 +++++++++++++++++++++++++
 tests/tests/Test_ASWLog_Utils.h         |  2 +
 12 files changed, 225 insertions(+), 4 deletions(-)

diff --git a/ASWLog/ASWLog_Config.h b/ASWLog/ASWLog_Config.h
index ffdb7d5..7159c2b 100644
--- a/ASWLog/ASWLog_Config.h
+++ b/ASWLog/ASWLog_Config.h
@@ -301,6 +301,9 @@ struct TASWShutdownConfig
 /////////////////////////////////////////////////////////////////////////////
 struct TASWStartupConfig
 {
+    // The application's version, written on the "App:" line as app_version='...' (see WriteApplicationInfo). Empty: on
+    // Windows, the executable's file version from its version resource, if it has one (see GetFileVersionString()).
+    std::string ApplicationVersion;
     std::string Banner; // Written first, if set
     bool WriteApplicationInfo  = true;
     bool WriteCommandLine      = false; // Added to the application info line
diff --git a/ASWLog/ASWLog_TextLogBase.cpp b/ASWLog/ASWLog_TextLogBase.cpp
index dbdeef4..20cadd2 100644
--- a/ASWLog/ASWLog_TextLogBase.cpp
+++ b/ASWLog/ASWLog_TextLogBase.cpp
@@ -863,7 +863,18 @@ void TASWTextLogBase::WaitForQueuedEntries()
 //---------------------------------------------------------------------------
 void TASWTextLogBase::WriteApplicationInfo()
 {
-    auto applicationInfo = std::format("app_exe='{}', app_target=", PathToUTF8String(GetExecutablePath()));
+    const auto executablePath = GetExecutablePath();
+    auto applicationInfo = std::format("app_exe='{}'", PathToUTF8String(executablePath));
+
+    // The configured version, or else the executable's file version (Windows)
+    auto applicationVersion = GetConfigUnlocked().Startup.ApplicationVersion;
+    if (applicationVersion.empty())
+        applicationVersion = GetFileVersionString(executablePath);
+
+    if (!applicationVersion.empty())
+        applicationInfo += std::format(", app_version='{}'", applicationVersion);
+
+    applicationInfo += ", app_target=";
 
 #if defined(_WIN64)
     applicationInfo += "Win64";
diff --git a/ASWLog/ASWLog_Utils.cpp b/ASWLog/ASWLog_Utils.cpp
index ca1688b..47145c4 100644
--- a/ASWLog/ASWLog_Utils.cpp
+++ b/ASWLog/ASWLog_Utils.cpp
@@ -30,18 +30,22 @@ limitations under the License.
 #include <charconv>
 #include <chrono>
 #include <climits>
+#include <cstddef>
 #include <cstdlib>
 #include <cstring>
 #include <ctime>
 #include <filesystem>
 #include <format>
 #include <fstream>
+#include <memory>
+#include <type_traits>
 #include <utility>
 #include <vector>
 
 #if defined(_WIN32)
 #include <windows.h>
 #include <psapi.h>
+#include <winver.h>
 #else
 #include <sys/syscall.h>
 #include <sys/sysinfo.h>
@@ -206,6 +210,62 @@ std::filesystem::path GetExecutablePath()
     return std::filesystem::path("unknown");
 }
 
+//---------------------------------------------------------------------------
+std::string GetFileVersionString(const std::filesystem::path& file)
+{
+#if defined(_WIN32)
+    // version.dll is loaded only for this call, from the system folder, so that no project has to link it
+    using FreeLibraryFunction = BOOL(WINAPI*)(HMODULE);
+    using GetFileVersionInfoFunction = BOOL(WINAPI*)(LPCWSTR, DWORD, DWORD, LPVOID);
+    using GetFileVersionInfoSizeFunction = DWORD(WINAPI*)(LPCWSTR, LPDWORD);
+    using VerQueryValueFunction = BOOL(WINAPI*)(LPCVOID, LPCWSTR, LPVOID*, PUINT);
+
+    const HMODULE versionLibrary = LoadLibraryExW(L"version.dll", nullptr, LOAD_LIBRARY_SEARCH_SYSTEM32);
+    if (versionLibrary == nullptr)
+        return {};
+
+    const std::unique_ptr<std::remove_pointer_t<HMODULE>, FreeLibraryFunction> libraryOwner(versionLibrary, &FreeLibrary);
+
+    // Through void (*)() so that GCC doesn't warn about casting between function types
+    const auto getVersionInfoSize = reinterpret_cast<GetFileVersionInfoSizeFunction>(
+        reinterpret_cast<void (*)()>(GetProcAddress(versionLibrary, "GetFileVersionInfoSizeW")));
+    const auto getVersionInfo = reinterpret_cast<GetFileVersionInfoFunction>(
+        reinterpret_cast<void (*)()>(GetProcAddress(versionLibrary, "GetFileVersionInfoW")));
+    const auto queryVersionValue = reinterpret_cast<VerQueryValueFunction>(
+        reinterpret_cast<void (*)()>(GetProcAddress(versionLibrary, "VerQueryValueW")));
+    if (getVersionInfoSize == nullptr || getVersionInfo == nullptr || queryVersionValue == nullptr)
+        return {};
+
+    const std::wstring path = file.wstring();
+    DWORD handle = 0;
+    const DWORD size = getVersionInfoSize(path.c_str(), &handle);
+    if (size == 0)
+        return {};
+
+    std::vector<std::byte> versionInfo(size);
+    void* fixedInfo = nullptr;
+    UINT fixedInfoSize = 0;
+    if (!getVersionInfo(path.c_str(), 0, size, versionInfo.data()) ||
+        !queryVersionValue(versionInfo.data(), L"\\", &fixedInfo, &fixedInfoSize) || fixedInfo == nullptr ||
+        fixedInfoSize < sizeof(VS_FIXEDFILEINFO))
+    {
+        return {};
+    }
+
+    VS_FIXEDFILEINFO fileInfo{};
+    std::memcpy(&fileInfo, fixedInfo, sizeof(fileInfo));
+    if (fileInfo.dwSignature != VS_FFI_SIGNATURE)
+        return {};
+
+    return std::format("{}.{}.{}.{}", HIWORD(fileInfo.dwFileVersionMS), LOWORD(fileInfo.dwFileVersionMS),
+        HIWORD(fileInfo.dwFileVersionLS), LOWORD(fileInfo.dwFileVersionLS));
+#else
+    static_cast<void>(file);
+
+    return {};
+#endif
+}
+
 //---------------------------------------------------------------------------
 TMemoryUsage GetMemoryUsage()
 {
diff --git a/ASWLog/ASWLog_Utils.h b/ASWLog/ASWLog_Utils.h
index 0613531..c30d996 100644
--- a/ASWLog/ASWLog_Utils.h
+++ b/ASWLog/ASWLog_Utils.h
@@ -88,6 +88,13 @@ struct TSystemMemoryUsage
 
 [[nodiscard]] std::string GetDriveInfoString();
 [[nodiscard]] std::filesystem::path GetExecutablePath();
+
+// The file version in the version resource of 'file' (e.g. an executable or DLL), as four numbers, e.g. "2.3.1.45",
+// what Explorer shows as "File version". Empty if the file has no version resource or can't be read, and always on
+// Linux, which has no version resources. Windows may report its own system files' version differently (e.g. 6.2 for
+// 10.0) to an application without a compatibility manifest. Throws std::bad_alloc if out of memory.
+[[nodiscard]] std::string GetFileVersionString(const std::filesystem::path& file);
+
 [[nodiscard]] TMemoryUsage GetMemoryUsage();
 [[nodiscard]] std::string GetMemoryUsageString();
 [[nodiscard]] std::string GetOSInfoString();
diff --git a/CHANGELOG.md b/CHANGELOG.md
index bc44842..bbbc7df 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -259,6 +259,14 @@ see [0.26.1](#0261---2026-09-17) for the initial versioned baseline.
   from the field says which ASWLog (and which logger) wrote it. On by
   default; `Startup.WriteLoggerVersion = false` leaves it out, which code that
   turns off every startup line one by one must now add.
+- The application's version in the startup lines: the "App:" line now has
+  `app_version='...'` after the executable's path, from the new
+  `Startup.ApplicationVersion`, or, when that is empty, on Windows, from the
+  executable's file version in its version resource (e.g. `2.3.1.45`, as
+  RAD Studio's Version Info sets it). Without either, the line is as before.
+  The new `ASWLog::GetFileVersionString(path)` reads any file's version
+  (Windows; empty on Linux). It loads `version.dll` at run time, so no
+  project needs a new library to link.
 
 ### Changed
 
diff --git a/README.md b/README.md
index f307b23..0e80d7f 100644
--- a/README.md
+++ b/README.md
@@ -24,8 +24,8 @@ pattern formatters, crash handlers, and the other extras below) is opt-in.
   against their arguments at compile time; wrap one built at run time in `ASWLog::RuntimeFormat()`.
 - Runtime `Open()`, `Close()`, `Flush()` and log rotation controls, and `Reconfigure()` to change settings safely
   while other threads log.
-- Optional startup diagnostics: the ASWLog version, application and system memory, OS, drive, time, and the command
-  line.
+- Optional startup diagnostics: the ASWLog and application versions (on Windows, the application's is read from its
+  version resource unless set), application and system memory, OS, drive, time, and the command line.
 - Retry handling for temporary file access conflicts and Windows reader-sharing support.
 - Crash durability: every entry is flushed by default, and with buffered flushing Error and Critical entries still
   are (`File.FlushImmediatelyAtLevel`). Entries at a chosen level can also be synced to disk to survive a power loss
diff --git a/docs/Configuration.md b/docs/Configuration.md
index baf40c8..d689cb9 100644
--- a/docs/Configuration.md
+++ b/docs/Configuration.md
@@ -84,9 +84,10 @@ The `Show*` settings are read by the built-in layout and by `TASWJSONFormatter`;
 
 | Setting | Default | What it does |
 |---|---|---|
+| `ApplicationVersion` | empty | The application's version, written on the application line as `app_version='...'`. Empty: on Windows, the executable's file version from its version resource (e.g. `2.3.1.45`, set in RAD Studio under Project > Options > Application > Version Info), if it has one; nothing on Linux. |
 | `Banner` | empty | A line written first, if set. |
 | `WriteLoggerVersion` | `true` | The ASWLog version and the logger's class, right after the banner, e.g. `ASWLog: version=1.0.0, logger=TASWFileLog`, so a log says which ASWLog wrote it. |
-| `WriteApplicationInfo` | `true` | The executable's path and build target, e.g. `App: app_exe='C:\MyApp\MyApp.exe', app_target=Win64`. |
+| `WriteApplicationInfo` | `true` | The executable's path, the application's version (see `ApplicationVersion`) and the build target, e.g. `App: app_exe='C:\MyApp\MyApp.exe', app_version='2.3.1.45', app_target=Win64`. |
 | `WriteCommandLine` | `false` | The command line, added to the application line. |
 | `WriteDriveInfo` | `true` | The disk's total, free and used space. |
 | `WriteMemoryUsage` | `true` | The process's memory use (working set and peak). |
diff --git a/tests/tests/Test_ASWLog_Config.cpp b/tests/tests/Test_ASWLog_Config.cpp
index 305dcc1..1564ac0 100644
--- a/tests/tests/Test_ASWLog_Config.cpp
+++ b/tests/tests/Test_ASWLog_Config.cpp
@@ -552,6 +552,7 @@ void TTest_ASWLog_Config::Test_Defaults_MatchDocumentedValues()
     CheckFalse(config.Line.ShowSourceLine, "Line.ShowSourceLine should default to false");
 
     // Assert: Startup
+    CheckEmpty(config.Startup.ApplicationVersion, "Startup.ApplicationVersion should default to empty");
     CheckEmpty(config.Startup.Banner, "Startup.Banner should default to empty");
     CheckTrue(config.Startup.WriteApplicationInfo, "Startup.WriteApplicationInfo should default to true");
     CheckFalse(config.Startup.WriteCommandLine, "Startup.WriteCommandLine should default to false");
diff --git a/tests/tests/Test_ASWLog_TextLogBase.cpp b/tests/tests/Test_ASWLog_TextLogBase.cpp
index 7dccc0c..4c16f55 100644
--- a/tests/tests/Test_ASWLog_TextLogBase.cpp
+++ b/tests/tests/Test_ASWLog_TextLogBase.cpp
@@ -49,6 +49,7 @@ limitations under the License.
 #include "ASWLog_FileLog.h"
 #include "ASWLog_Formatter.h"
 #include "ASWLog_TextLogBase.h"
+#include "ASWLog_Utils.h"
 #include "ASWLog_Version.h"
 //---------------------------------------------------------------------------
 
@@ -401,6 +402,8 @@ bool WaitUntil(const std::function<bool()>& condition)
 TTest_ASWLog_TextLogBase::TTest_ASWLog_TextLogBase()
     : inherited("ASWLog_TextLogBase_Tests")
 {
+    RegisterTest(&TTest_ASWLog_TextLogBase::Test_ApplicationInfo_WritesTheConfiguredVersion, "ApplicationInfo_WritesTheConfiguredVersion");
+    RegisterTest(&TTest_ASWLog_TextLogBase::Test_ApplicationInfo_WritesTheExecutablesFileVersionByDefault, "ApplicationInfo_WritesTheExecutablesFileVersionByDefault");
     RegisterTest(&TTest_ASWLog_TextLogBase::Test_Async_BacktraceIsTakenWhenTheTriggerIsLogged, "Async_BacktraceIsTakenWhenTheTriggerIsLogged");
     RegisterTest(&TTest_ASWLog_TextLogBase::Test_Async_BlockWaitsForRoomInTheQueue, "Async_BlockWaitsForRoomInTheQueue");
     RegisterTest(&TTest_ASWLog_TextLogBase::Test_Async_CallReturnsBeforeTheEntryIsWritten, "Async_CallReturnsBeforeTheEntryIsWritten");
@@ -474,6 +477,59 @@ void TTest_ASWLog_TextLogBase::TearDown_Test(ITestCase& testCase)
 
 // /////// Begin tests after this line ///////////////////////
 
+//---------------------------------------------------------------------------
+void TTest_ASWLog_TextLogBase::Test_ApplicationInfo_WritesTheConfiguredVersion()
+{
+    // Arrange
+    TMemoryOutput output;
+    TMemoryTextLog log(output);
+    auto config = MakeQuietConfig();
+    config.Startup.WriteApplicationInfo = true;
+    config.Startup.ApplicationVersion = "2.3.1 beta";
+
+    // Act
+    const bool initialized = log.Initialize(config);
+
+    // Assert
+    CheckTrue(initialized, "Initialize should succeed");
+    CheckEquals(1, output.Lines.size(), "Initialize should write the App line");
+    if (output.Lines.size() == 1)
+    {
+        CheckStartsWith(output.Lines[0], "[INFO]: App: app_exe='", "The App line should start with the executable's path");
+        CheckContains(output.Lines[0], "', app_version='2.3.1 beta', app_target=",
+            "The configured version should follow the executable's path: " + output.Lines[0]);
+    }
+}
+//---------------------------------------------------------------------------
+void TTest_ASWLog_TextLogBase::Test_ApplicationInfo_WritesTheExecutablesFileVersionByDefault()
+{
+    // Arrange: no configured version. The test executable has a version resource in some builds (e.g. the VCL GUI
+    // runner's 1.0.0.0) and none in others (e.g. MinGW's), where no version is written.
+    TMemoryOutput output;
+    TMemoryTextLog log(output);
+    auto config = MakeQuietConfig();
+    config.Startup.WriteApplicationInfo = true;
+    const std::string fileVersion = ASWLog::GetFileVersionString(ASWLog::GetExecutablePath());
+
+    // Act
+    const bool initialized = log.Initialize(config);
+
+    // Assert
+    CheckTrue(initialized, "Initialize should succeed");
+    CheckEquals(1, output.Lines.size(), "Initialize should write the App line");
+    if (output.Lines.size() == 1)
+    {
+        if (fileVersion.empty())
+        {
+            CheckNotContains(output.Lines[0], "app_version=", "Without a version resource, no version should be written: " + output.Lines[0]);
+        }
+        else
+        {
+            CheckContains(output.Lines[0], std::format("', app_version='{}', app_target=", fileVersion),
+                "The executable's file version should follow its path: " + output.Lines[0]);
+        }
+    }
+}
 //---------------------------------------------------------------------------
 void TTest_ASWLog_TextLogBase::Test_Async_BlockWaitsForRoomInTheQueue()
 {
diff --git a/tests/tests/Test_ASWLog_TextLogBase.h b/tests/tests/Test_ASWLog_TextLogBase.h
index e7b5819..d99173c 100644
--- a/tests/tests/Test_ASWLog_TextLogBase.h
+++ b/tests/tests/Test_ASWLog_TextLogBase.h
@@ -36,6 +36,8 @@ class TTest_ASWLog_TextLogBase : public TTestGroupBase
     typedef TTestGroupBase inherited;
 
 private: // Test methods
+    void Test_ApplicationInfo_WritesTheConfiguredVersion();
+    void Test_ApplicationInfo_WritesTheExecutablesFileVersionByDefault();
     void Test_Async_BacktraceIsTakenWhenTheTriggerIsLogged();
     void Test_Async_BlockWaitsForRoomInTheQueue();
     void Test_Async_CallReturnsBeforeTheEntryIsWritten();
diff --git a/tests/tests/Test_ASWLog_Utils.cpp b/tests/tests/Test_ASWLog_Utils.cpp
index b541ce5..ecff156 100644
--- a/tests/tests/Test_ASWLog_Utils.cpp
+++ b/tests/tests/Test_ASWLog_Utils.cpp
@@ -35,6 +35,7 @@ limitations under the License.
 #include <fstream>
 #include <iterator>
 #include <ratio>
+#include <regex>
 #include <string>
 #include <string_view>
 #include <system_error>
@@ -113,6 +114,8 @@ TTest_ASWLog_Utils::TTest_ASWLog_Utils()
     RegisterTest(&TTest_ASWLog_Utils::Test_GenerateLogFileName_PrefixAndPostfixAreOptional, "GenerateLogFileName_PrefixAndPostfixAreOptional");
     RegisterTest(&TTest_ASWLog_Utils::Test_GetCurrentOSProcessId_MatchesOS, "GetCurrentOSProcessId_MatchesOS");
     RegisterTest(&TTest_ASWLog_Utils::Test_GetCurrentOSThreadId_IdentifiesCallingThread, "GetCurrentOSThreadId_IdentifiesCallingThread");
+    RegisterTest(&TTest_ASWLog_Utils::Test_GetFileVersionString_IsEmptyWithoutAVersionResource, "GetFileVersionString_IsEmptyWithoutAVersionResource");
+    RegisterTest(&TTest_ASWLog_Utils::Test_GetFileVersionString_ReadsTheFileVersion, "GetFileVersionString_ReadsTheFileVersion");
     RegisterTest(&TTest_ASWLog_Utils::Test_GetOSInfoString_ContainsEdition, "GetOSInfoString_ContainsEdition");
     RegisterTest(&TTest_ASWLog_Utils::Test_GetTimeInfoString_ReportsCurrentOffset, "GetTimeInfoString_ReportsCurrentOffset");
     RegisterTest(&TTest_ASWLog_Utils::Test_GetWindowsEditionName_ProductTypes, "GetWindowsEditionName_ProductTypes");
@@ -370,6 +373,73 @@ void TTest_ASWLog_Utils::Test_GetCurrentOSThreadId_IdentifiesCallingThread()
 #endif
 }
 //---------------------------------------------------------------------------
+void TTest_ASWLog_Utils::Test_GetFileVersionString_IsEmptyWithoutAVersionResource()
+{
+    // Arrange: a text file, and a file that doesn't exist
+    const auto folder = std::filesystem::temp_directory_path() / "aswlog_utils_version_test";
+    std::filesystem::remove_all(folder);
+    std::filesystem::create_directories(folder);
+
+    const auto textFile = folder / "plain.txt";
+    {
+        std::ofstream stream(textFile);
+        stream << "no version resource";
+    }
+
+    // Act
+    const std::string textVersion = ASWLog::GetFileVersionString(textFile);
+    const std::string missingVersion = ASWLog::GetFileVersionString(folder / "missing.dll");
+
+    // Assert
+    CheckEmpty(textVersion, "A file without a version resource should have no version");
+    CheckEmpty(missingVersion, "A file that doesn't exist should have no version");
+
+    std::error_code errorCode;
+    std::filesystem::remove_all(folder, errorCode);
+}
+//---------------------------------------------------------------------------
+void TTest_ASWLog_Utils::Test_GetFileVersionString_ReadsTheFileVersion()
+{
+#if defined(_WIN32)
+    // Arrange: kernel32.dll, e.g. "10.0.19041.5794" on Windows 10. To an executable without a compatibility manifest,
+    // Windows reports its system files' version as 6.2 (e.g. "6.2.19041.5794"), so the exact version isn't known here.
+    wchar_t systemFolder[MAX_PATH]{};
+    const UINT folderLength = GetSystemDirectoryW(systemFolder, MAX_PATH);
+    // Not named "kernel32", which the VCL's Windows header declares
+    const auto kernel32Path = std::filesystem::path(std::wstring(systemFolder, folderLength)) / L"kernel32.dll";
+
+    // The Windows build, e.g. 19045, from the registry rather than an API that a compatibility shim could change
+    wchar_t osBuildText[16]{};
+    DWORD osBuildTextSize = sizeof(osBuildText);
+    const bool hasOSBuild = RegGetValueW(HKEY_LOCAL_MACHINE, L"SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion",
+        L"CurrentBuildNumber", RRF_RT_REG_SZ, nullptr, osBuildText, &osBuildTextSize) == ERROR_SUCCESS;
+
+    // Act
+    const std::string version = ASWLog::GetFileVersionString(kernel32Path);
+
+    // Assert: four numbers in the right order: a Windows major version (6 or more) above its minor version (6.2, 10.0),
+    // then the build of the Windows release the file came from: at most the Windows build, and less than 1000 below it
+    // (an enablement update raises the Windows build, e.g. 19041 to 19045, or 26100 to 26200). The revision can be any
+    // number, also above the build (e.g. 6.2.26100.33438 on Windows Server 2025).
+    std::smatch parts;
+    const bool isFourNumbers = std::regex_match(version, parts, std::regex(R"((\d+)\.(\d+)\.(\d+)\.(\d+))"));
+    CheckTrue(isFourNumbers, "The file version should be four numbers: " + version);
+    CheckTrue(hasOSBuild, "The Windows build should be in the registry");
+    if (isFourNumbers && hasOSBuild)
+    {
+        const auto major = std::stoul(parts[1].str());
+        const auto build = std::stoul(parts[3].str());
+        const auto osBuild = std::stoul(std::wstring(osBuildText));
+        CheckGreaterThanOrEqual(major, 6ul, "The major version should be a Windows version: " + version);
+        CheckGreaterThan(major, std::stoul(parts[2].str()), "The major version should come before the minor: " + version);
+        CheckLessThanOrEqual(build, osBuild, "The third number should be a Windows build, at most this one: " + version);
+        CheckLessThan(osBuild - build, 1000ul, "The third number should be this Windows release's build: " + version);
+    }
+#else
+    Skip("Only Windows files have version resources");
+#endif
+}
+//---------------------------------------------------------------------------
 void TTest_ASWLog_Utils::Test_GetOSInfoString_ContainsEdition()
 {
     // Arrange
diff --git a/tests/tests/Test_ASWLog_Utils.h b/tests/tests/Test_ASWLog_Utils.h
index e177b70..0e2af6f 100644
--- a/tests/tests/Test_ASWLog_Utils.h
+++ b/tests/tests/Test_ASWLog_Utils.h
@@ -45,6 +45,8 @@ class TTest_ASWLog_Utils : public TTestGroupBase
     void Test_GenerateLogFileName_PrefixAndPostfixAreOptional();
     void Test_GetCurrentOSProcessId_MatchesOS();
     void Test_GetCurrentOSThreadId_IdentifiesCallingThread();
+    void Test_GetFileVersionString_IsEmptyWithoutAVersionResource();
+    void Test_GetFileVersionString_ReadsTheFileVersion();
     void Test_GetOSInfoString_ContainsEdition();
     void Test_GetTimeInfoString_ReportsCurrentOffset();
     void Test_GetWindowsEditionName_ProductTypes();

From 0a5369b1fa449f575f1fd292dea11135466ce279 Mon Sep 17 00:00:00 2001
From: Anthony West <anthony.s.west@gmail.com>
Date: Sat, 10 Oct 2026 22:19:06 -0700
Subject: [PATCH 05/12] Write the startup lines at the top of each new log file

---
 ASWLog/ASWLog_Config.h              |   7 +
 ASWLog/ASWLog_FileLog.cpp           |  79 ++++++-
 ASWLog/ASWLog_FileLog.h             |   9 +-
 ASWLog/ASWLog_TextLogBase.cpp       |  43 ++--
 ASWLog/ASWLog_TextLogBase.h         |  14 ++
 CHANGELOG.md                        |  13 ++
 README.md                           |   3 +-
 docs/Configuration.md               |   6 +-
 tests/tests/Test_ASWLog_Config.cpp  |   1 +
 tests/tests/Test_ASWLog_FileLog.cpp | 345 ++++++++++++++++++++++++++++
 tests/tests/Test_ASWLog_FileLog.h   |  11 +
 11 files changed, 499 insertions(+), 32 deletions(-)

diff --git a/ASWLog/ASWLog_Config.h b/ASWLog/ASWLog_Config.h
index 7159c2b..29d7e2e 100644
--- a/ASWLog/ASWLog_Config.h
+++ b/ASWLog/ASWLog_Config.h
@@ -177,6 +177,13 @@ struct TASWFileConfig
     // Rolls the file over at midnight, and at Initialize() if the file was last written on an earlier day, both in
     // Line.TimestampZone (UTC by default). The backup is named for the day it holds.
     bool EnableDailyRolling   = false;
+    // Starts each file the logger begins after Initialize() (by rotation, daily rolling or Reconfigure() to a new path)
+    // with a line saying where the log continues from, e.g. "Log continued from aswlog.size.2026-10-10_143005_123.bak
+    // (size)" or "Log continued from logs\old.txt (reconfigure)", followed by the startup lines as Initialize() writes
+    // them (see TASWStartupConfig, whose settings still apply), so each file says what wrote it. They are Info lines,
+    // written before the entry that started the file. Not after a failed rotation, and with AutoOpenClosePerWrite, only
+    // by the process that rotated the shared log.
+    bool WriteStartupLinesInNewFiles = true;
 
     // --- Backup Event ---
     // Called once for each backup that rotation makes, e.g. to compress it, upload it or move it elsewhere. Called
diff --git a/ASWLog/ASWLog_FileLog.cpp b/ASWLog/ASWLog_FileLog.cpp
index aa00487..d3a6103 100644
--- a/ASWLog/ASWLog_FileLog.cpp
+++ b/ASWLog/ASWLog_FileLog.cpp
@@ -482,8 +482,8 @@ TASWFileLog::~TASWFileLog()
 //---------------------------------------------------------------------------
 void TASWFileLog::AfterEntryUnlocked()
 {
-    // In this mode the file is only open while an entry (or Initialize()'s startup lines) is written. Unlike Close(),
-    // this leaves the logger initialized.
+    // In this mode the file is only open while an entry (or the startup lines) is written. Unlike Close(), this leaves
+    // the logger initialized.
     if (GetConfigUnlocked().File.AutoOpenClosePerWrite)
         CloseFileUnlocked();
 }
@@ -704,6 +704,9 @@ bool TASWFileLog::InitializeUnlocked()
     if (GetConfigUnlocked().File.EnableDailyRolling)
         RotateDailyLogFromEarlierDayUnlocked();
 
+    // Initialize() writes the startup lines itself, and Reconfigure() its own continuation line
+    m_PendingContinuationLine.clear();
+
     if (!OpenUnlocked())
     {
         return false;
@@ -792,6 +795,9 @@ bool TASWFileLog::OpenUnlocked()
 
     m_IsOpen.store(true, std::memory_order_release);
     m_IsInitialized.store(true, std::memory_order_release);
+
+    WriteNewFileStartupLinesUnlocked();
+
     return true;
 }
 
@@ -799,8 +805,9 @@ bool TASWFileLog::OpenUnlocked()
 /*
     TASWFileLog::PrepareWriteUnlocked
 
-    Rotates the log file if the day has changed or the file has reached its maximum size, as configured. Returns false
-    if the file isn't open (e.g. it couldn't be reopened after a rotation), which drops the line.
+    Rotates the log file if the day has changed or the file has reached its maximum size, as configured, but not while
+    the startup lines are written (the new file's own, or Initialize()'s): the next entry rotates it. Returns false if
+    the file isn't open (e.g. it couldn't be reopened after a rotation), which drops the line.
 */
 bool TASWFileLog::PrepareWriteUnlocked(std::chrono::system_clock::time_point now)
 {
@@ -809,7 +816,7 @@ bool TASWFileLog::PrepareWriteUnlocked(std::chrono::system_clock::time_point now
         // Only rolls forward (ISO dates compare as text): an entry stamped just before midnight can get the lock after
         // another thread's entry has rolled the log over, and then goes into the new day's log
         const auto currentDateStr = Time::ToDateString(now, GetConfigUnlocked().Line.TimestampZone);
-        if (currentDateStr > m_LastLogDateStr)
+        if (currentDateStr > m_LastLogDateStr && !IsWritingStartupLinesUnlocked())
         {
             // Name the backup for the day its content is from, not the day that just started. A log shared with other
             // processes may already have been rolled over by one of them, so there the file's last write decides.
@@ -825,7 +832,8 @@ bool TASWFileLog::PrepareWriteUnlocked(std::chrono::system_clock::time_point now
     // Uses the size tracked by the stream, since on Windows the size read through the path isn't current while open.
     // After a failed rotation (e.g. another program holds the file), waits RotationRetryDelay before trying again.
     if (GetConfigUnlocked().File.EnableRotation && m_FileStream.IsOpen() && m_FileStream.GetSize() >= GetConfigUnlocked().File.MaxFileSizeBytes &&
-        IsRetryDue(m_LastRotationFailure, now, GetConfigUnlocked().File.RotationRetryDelay))
+        IsRetryDue(m_LastRotationFailure, now, GetConfigUnlocked().File.RotationRetryDelay) &&
+        !IsWritingStartupLinesUnlocked())
     {
         RotateLogFilesUnlocked("size", ToBackupTimeLabel(now, GetConfigUnlocked().Line.TimestampZone));
     }
@@ -838,9 +846,11 @@ bool TASWFileLog::PrepareWriteUnlocked(std::chrono::system_clock::time_point now
     TASWFileLog::ReconfigureUnlocked
 
     If the file path or AutoOpenClosePerWrite changed, closes the old file and starts on the new one as Initialize()
-    does (rolling over a file from an earlier day, if daily rolling is on, then opening it). With AutoOpenClosePerWrite
-    the new file is closed again until the next entry, but opening it here reports a file that can't be opened. A
-    failed open keeps the logger initialized, so later entries try again (see EnsureReadyUnlocked()).
+    does (rolling over a file from an earlier day, if daily rolling is on, then opening it). A new path starts with
+    the startup lines (see WriteNewFileStartupLinesUnlocked()). With AutoOpenClosePerWrite the new file is closed again
+    until the next entry, but opening it here reports a file that can't be opened. A failed open keeps the logger
+    initialized, so later entries try again (see EnsureReadyUnlocked()), and the first one that opens the file writes
+    the startup lines.
 
     Otherwise the file stays open: flushes what the previous flush mode may have buffered, and the other settings take
     effect with the next entry (a FlushMode::Periodic thread is started, stopped or given its new interval after the
@@ -853,8 +863,9 @@ bool TASWFileLog::ReconfigureUnlocked(const TASWLogConfig& previous)
     const auto& file = config.File;
     m_SyncsCrashLine.store(Level::Critical >= file.SyncToDiskAtLevel, std::memory_order_relaxed);
 
-    if (file.ResolvePath() == previous.File.ResolvePath() &&
-        file.AutoOpenClosePerWrite == previous.File.AutoOpenClosePerWrite)
+    const auto previousPath = previous.File.ResolvePath();
+    const bool isNewPath = file.ResolvePath() != previousPath;
+    if (!isNewPath && file.AutoOpenClosePerWrite == previous.File.AutoOpenClosePerWrite)
     {
         if (config.Line.TimestampZone != previous.Line.TimestampZone)
             m_LastLogDateStr = Time::ToDateString(NowUTC(), config.Line.TimestampZone);
@@ -867,6 +878,13 @@ bool TASWFileLog::ReconfigureUnlocked(const TASWLogConfig& previous)
 
     CloseFileUnlocked();
     const bool isOpen = InitializeUnlocked();
+
+    if (isNewPath && file.WriteStartupLinesInNewFiles)
+    {
+        m_PendingContinuationLine = std::format("Log continued from {} (reconfigure)", PathToUTF8String(previousPath));
+        WriteNewFileStartupLinesUnlocked();
+    }
+
     AfterEntryUnlocked();
 
     return isOpen;
@@ -913,7 +931,18 @@ bool TASWFileLog::RotateLogFiles(std::string_view reasonTag)
 {
     TDeferredWorkRunner deferredWorkRunner(*this);
     std::lock_guard<std::mutex> lock(m_Mutex);
-    return RotateLogFilesUnlocked(reasonTag, ToBackupTimeLabel(NowUTC(), GetConfigUnlocked().Line.TimestampZone));
+    const auto timeLabel = ToBackupTimeLabel(NowUTC(), GetConfigUnlocked().Line.TimestampZone);
+    const bool isRotated = RotateLogFilesUnlocked(reasonTag, timeLabel);
+
+    // A file that is closed between entries (AutoOpenClosePerWrite) is opened for its startup lines now, so they come
+    // first even if another process writes to it next
+    if (isRotated && !m_PendingContinuationLine.empty() && m_IsInitialized.load(std::memory_order_acquire) &&
+        EnsureReadyUnlocked())
+    {
+        AfterEntryUnlocked();
+    }
+
+    return isRotated;
 }
 
 //---------------------------------------------------------------------------
@@ -994,6 +1023,13 @@ bool TASWFileLog::RotateLogFilesUnlocked(std::string_view reasonTag, std::string
         return false;
     }
 
+    // The next file starts with the startup lines, written once it is open (see WriteNewFileStartupLinesUnlocked())
+    if (!backupPath.empty() && GetConfigUnlocked().File.WriteStartupLinesInNewFiles)
+    {
+        m_PendingContinuationLine = std::format("Log continued from {} ({})", PathToUTF8String(backupPath.filename()),
+            reasonTag);
+    }
+
     const bool isOpen = wasOpen ? OpenUnlocked() : true;
 
     // OnBackupCreated calls into the application and the cleanup scans the folder, so both run after the lock is
@@ -1060,6 +1096,25 @@ void TASWFileLog::WriteLineUnlocked(Level level, std::string_view line, bool end
     MaybeFlush(level, endsLine);
 }
 
+//---------------------------------------------------------------------------
+/*
+    TASWFileLog::WriteNewFileStartupLinesUnlocked
+
+    Starts a file the logger began after Initialize() (see TASWFileConfig::WriteStartupLinesInNewFiles), once it is
+    open: writes the line saying where the log continues from, then the startup lines. Called by OpenUnlocked(), so a
+    rotation writes them before the entry that triggered it, and a file that couldn't be opened right away gets them
+    from the open that succeeds. Does nothing if no new file is waiting for them.
+*/
+void TASWFileLog::WriteNewFileStartupLinesUnlocked()
+{
+    if (m_PendingContinuationLine.empty() || !m_FileStream.IsOpen())
+        return;
+
+    // Taken first, so that the lines are written once even if they fail
+    const auto continuationLine = std::exchange(m_PendingContinuationLine, std::string());
+    WriteStartupLinesUnlocked(continuationLine);
+}
+
 //---------------------------------------------------------------------------
 
 } // namespace ASWLog
diff --git a/ASWLog/ASWLog_FileLog.h b/ASWLog/ASWLog_FileLog.h
index 4746515..f2c0939 100644
--- a/ASWLog/ASWLog_FileLog.h
+++ b/ASWLog/ASWLog_FileLog.h
@@ -128,6 +128,9 @@ class TASWFileLog : public TASWTextLogBase
     std::string m_LastLogDateStr; // Stores YYYY-MM-DD state to detect structural calendar shifts
     std::chrono::system_clock::time_point m_LastOpenFailure{}; // NowUTC() when opening the file last failed
     std::chrono::system_clock::time_point m_LastRotationFailure{}; // NowUTC() when a rotation last failed
+    // The first line of a new file the logger started (see TASWFileConfig::WriteStartupLinesInNewFiles), waiting for
+    // the file to be open; empty if none
+    std::string m_PendingContinuationLine;
 
     // File.SyncToDiskAtLevel is Critical or lower, for WriteCrashLineDirect(), which may run without m_Mutex
     std::atomic<bool> m_SyncsCrashLine{ false };
@@ -142,6 +145,7 @@ class TASWFileLog : public TASWTextLogBase
     void RotateDailyLogFromEarlierDayUnlocked();
     bool RotateLogFilesUnlocked(std::string_view reasonTag, std::string_view timeLabel);
     void SyncToDiskUnlocked();
+    void WriteNewFileStartupLinesUnlocked();
 
 protected: // TASWTextLogBase hooks
     void AfterEntryUnlocked() override;
@@ -186,8 +190,9 @@ class TASWFileLog : public TASWTextLogBase
 
     // Renames the log file to "<stem>.<reasonTag>.<YYYY-MM-DD_HHMMSS_mmm>.bak" (the time in Line.TimestampZone, UTC by
     // default), adding "_1", "_2", ... to the time if that name is taken, so an existing backup is never replaced. Then
-    // reopens the log if it was open. A 'reasonTag' that contains '.' makes a backup that TASWFileConfig's backup
-    // cleanup doesn't recognize, so it is kept.
+    // reopens the log if it was open, and starts the new file with the startup lines (see
+    // TASWFileConfig::WriteStartupLinesInNewFiles; with AutoOpenClosePerWrite it is opened for them). A 'reasonTag'
+    // that contains '.' makes a backup that TASWFileConfig's backup cleanup doesn't recognize, so it is kept.
     bool RotateLogFiles(std::string_view reasonTag = "manual");
 };
 
diff --git a/ASWLog/ASWLog_TextLogBase.cpp b/ASWLog/ASWLog_TextLogBase.cpp
index 20cadd2..cd4ffb0 100644
--- a/ASWLog/ASWLog_TextLogBase.cpp
+++ b/ASWLog/ASWLog_TextLogBase.cpp
@@ -261,22 +261,8 @@ bool TASWTextLogBase::Initialize(const TASWLogConfig& config) noexcept
 
         Detail::TCrashHandling::Register(*this);
 
-        // The output is ready, so the startup lines are best effort: if one throws (e.g. a formatter that throws, or
-        // out of memory while gathering the system info), the rest are skipped but the logger is still initialized
-        try
-        {
-            if (!GetConfigUnlocked().Startup.Banner.empty())
-            {
-                WriteInfoLine(GetConfigUnlocked().Startup.Banner);
-            }
-
-            WriteInitializationInfo();
-        }
-        catch (...)
-        {
-            ReportCurrentExceptionUnlocked("Skipped the startup lines");
-        }
-
+        // The output is ready, so the startup lines are best effort: a failed one doesn't fail Initialize()
+        WriteStartupLinesUnlocked();
         AfterEntryUnlocked();
 
         return true;
@@ -1188,6 +1174,31 @@ void TASWTextLogBase::WriteRecord(const TASWLogRecord& record)
         DispatchLogCallback(*callbackConfig, record, writtenLine);
 }
 
+//---------------------------------------------------------------------------
+void TASWTextLogBase::WriteStartupLinesUnlocked(std::string_view firstLine) noexcept
+{
+    m_IsWritingStartupLines = true;
+
+    // If a line throws (e.g. a formatter that throws, or out of memory while gathering the system info), the rest are
+    // skipped
+    try
+    {
+        if (!firstLine.empty())
+            WriteInfoLine(firstLine);
+
+        if (!GetConfigUnlocked().Startup.Banner.empty())
+            WriteInfoLine(GetConfigUnlocked().Startup.Banner);
+
+        WriteInitializationInfo();
+    }
+    catch (...)
+    {
+        ReportCurrentExceptionUnlocked("Skipped the startup lines");
+    }
+
+    m_IsWritingStartupLines = false;
+}
+
 //---------------------------------------------------------------------------
 void TASWTextLogBase::WriteSystemMemoryInfo()
 {
diff --git a/ASWLog/ASWLog_TextLogBase.h b/ASWLog/ASWLog_TextLogBase.h
index 5cf6a89..6b15d77 100644
--- a/ASWLog/ASWLog_TextLogBase.h
+++ b/ASWLog/ASWLog_TextLogBase.h
@@ -145,6 +145,7 @@ class TASWTextLogBase : public TASWLogBase
     std::atomic<bool> m_IsAsync{ false };
 
     bool m_IsWritingQueuedEntries = false; // Guarded by m_Mutex (see IsWritingQueuedEntriesUnlocked())
+    bool m_IsWritingStartupLines = false; // Guarded by m_Mutex (see IsWritingStartupLinesUnlocked())
 
     // This logger's place on the list of loggers a crash flushes, guarded by that list's lock (see
     // Detail::TCrashHandling)
@@ -295,6 +296,13 @@ class TASWTextLogBase : public TASWLogBase
         return m_IsWritingQueuedEntries;
     }
 
+    // True while the startup lines are written (see WriteStartupLinesUnlocked()), so that PrepareWriteUnlocked() can
+    // leave starting a new output (e.g. rotating a file) until after them.
+    bool IsWritingStartupLinesUnlocked() const noexcept
+    {
+        return m_IsWritingStartupLines;
+    }
+
     // Called on the worker thread, every GetWorkerIntervalUnlocked() (measured from the start of the previous call),
     // e.g. to flush the output. Reports a failure with ReportErrorUnlocked(): the worker passes it on to OnError after
     // the unlock, on its own thread. An exception is caught and reported. Does nothing by default.
@@ -333,6 +341,12 @@ class TASWTextLogBase : public TASWLogBase
     // as is; see IASWLogFormatter::FormatsRawEntries()).
     virtual void WriteLineUnlocked(Level level, std::string_view line, bool endsLine) = 0;
 
+    // Writes the startup lines as Initialize() does: 'firstLine' if it isn't empty, the banner, then the lines
+    // TASWStartupConfig turns on, each as an Info line through PrepareWriteUnlocked() and WriteLineUnlocked(). For a
+    // derived logger that starts a new output, e.g. a file logger's next file after a rotation. A line that fails (e.g.
+    // its formatter throws) is reported and the rest are skipped. Never throws.
+    void WriteStartupLinesUnlocked(std::string_view firstLine = {}) noexcept;
+
 protected: // TASWLogBase hook
     // Writes the entry under m_Mutex, through the hooks above, then calls OnLogEntry. An asynchronous logger formats the
     // entry and queues it instead (see TASWAsyncConfig).
diff --git a/CHANGELOG.md b/CHANGELOG.md
index bbbc7df..f58d27a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -267,6 +267,19 @@ see [0.26.1](#0261---2026-09-17) for the initial versioned baseline.
   The new `ASWLog::GetFileVersionString(path)` reads any file's version
   (Windows; empty on Linux). It loads `version.dll` at run time, so no
   project needs a new library to link.
+- The startup lines at the top of each new log file: a file logger now starts
+  every file it begins after `Initialize()` (size rotation, daily rolling,
+  `RotateLogFiles()`, `Reconfigure()` to a new path) with a line saying where
+  the log continues from, e.g. `Log continued from
+  myapp.size.2026-10-10_143005_123.bak (size)` or `Log continued from
+  logs\old.txt (reconfigure)`, followed by the startup lines as
+  `Initialize()` writes them (the banner and each line its `Startup` setting
+  turns on), so a rotated log still says which version and system wrote it.
+  They come before the entry that started the file. On by default; the new
+  `File.WriteStartupLinesInNewFiles = false` keeps the old output, in which a
+  new file starts with that entry. A rotation no longer happens in the middle
+  of the startup lines: if they reach `File.MaxFileSizeBytes`, the next entry
+  rotates the file.
 
 ### Changed
 
diff --git a/README.md b/README.md
index 0e80d7f..f1c919d 100644
--- a/README.md
+++ b/README.md
@@ -25,7 +25,8 @@ pattern formatters, crash handlers, and the other extras below) is opt-in.
 - Runtime `Open()`, `Close()`, `Flush()` and log rotation controls, and `Reconfigure()` to change settings safely
   while other threads log.
 - Optional startup diagnostics: the ASWLog and application versions (on Windows, the application's is read from its
-  version resource unless set), application and system memory, OS, drive, time, and the command line.
+  version resource unless set), application and system memory, OS, drive, time, and the command line, written again
+  at the top of each new file after a rotation, saying which file the log continues from.
 - Retry handling for temporary file access conflicts and Windows reader-sharing support.
 - Crash durability: every entry is flushed by default, and with buffered flushing Error and Critical entries still
   are (`File.FlushImmediatelyAtLevel`). Entries at a chosen level can also be synced to disk to survive a power loss
diff --git a/docs/Configuration.md b/docs/Configuration.md
index d689cb9..0faf451 100644
--- a/docs/Configuration.md
+++ b/docs/Configuration.md
@@ -25,7 +25,8 @@ config.Line.ShowThreadId = false;
 log.Reconfigure(config);
 ```
 
-`Reconfigure()` doesn't change the minimum level (use `SetMinimumLevel()`) and doesn't write the startup lines again.
+`Reconfigure()` doesn't change the minimum level (use `SetMinimumLevel()`) and doesn't write the startup lines again,
+except in the new file of a file logger moved to a new path (see `File.WriteStartupLinesInNewFiles`).
 
 The header comments in `ASWLog_Config.h` have the full details of each setting; this page is the overview.
 
@@ -82,6 +83,8 @@ The `Show*` settings are read by the built-in layout and by `TASWJSONFormatter`;
 
 ## `Startup`: the lines `Initialize()` writes (`TASWStartupConfig`)
 
+A file logger also writes them at the top of each new file it starts (see `File.WriteStartupLinesInNewFiles`).
+
 | Setting | Default | What it does |
 |---|---|---|
 | `ApplicationVersion` | empty | The application's version, written on the application line as `app_version='...'`. Empty: on Windows, the executable's file version from its version resource (e.g. `2.3.1.45`, set in RAD Studio under Project > Options > Application > Version Info), if it has one; nothing on Linux. |
@@ -121,6 +124,7 @@ The `Show*` settings are read by the built-in layout and by `TASWJSONFormatter`;
 | `MaxFileSizeBytes` | 10 MB | The size that triggers a rotation. |
 | `RotationRetryDelay` | 500 ms | After a failed rotation, entries go on to the current file, and rotating isn't tried again until this long after the failure. |
 | `EnableDailyRolling` | `false` | Rotates the file at midnight (in `Line.TimestampZone`), and at `Initialize()` if the file was last written on an earlier day. |
+| `WriteStartupLinesInNewFiles` | `true` | Starts each file the logger begins after `Initialize()` (size rotation, daily rolling, `RotateLogFiles()`, `Reconfigure()` to a new path) with a line saying where the log continues from, e.g. `Log continued from myapp.size.2026-10-10_143005_123.bak (size)` or `Log continued from logs\old.txt (reconfigure)`, then the startup lines (see [`Startup`](#startup-the-lines-initialize-writes-taswstartupconfig), whose settings apply). They are Info lines, written before the entry that started the file. Not after a failed rotation; with `AutoOpenClosePerWrite`, only by the process that rotated the shared log. |
 | `OnBackupCreated` | empty | Called for each backup a rotation makes, with its path and reason, e.g. to compress, upload or move it. Runs outside the logger's lock, on the thread whose call rotated the log. |
 | `RetentionMaxAge` | 0 (off) | After each rotation, deletes this log's backups older than this. |
 | `MaxBackupFiles` | 0 (unlimited) | After each rotation, keeps only the newest this many backups. |
diff --git a/tests/tests/Test_ASWLog_Config.cpp b/tests/tests/Test_ASWLog_Config.cpp
index 1564ac0..942822a 100644
--- a/tests/tests/Test_ASWLog_Config.cpp
+++ b/tests/tests/Test_ASWLog_Config.cpp
@@ -590,6 +590,7 @@ void TTest_ASWLog_Config::Test_Defaults_MatchDocumentedValues()
     CheckTrue(config.File.RotationRetryDelay == std::chrono::milliseconds(500),
         "File.RotationRetryDelay should default to 500 ms");
     CheckFalse(config.File.EnableDailyRolling, "File.EnableDailyRolling should default to false");
+    CheckTrue(config.File.WriteStartupLinesInNewFiles, "File.WriteStartupLinesInNewFiles should default to true");
     CheckTrue(config.File.RetentionMaxAge == std::chrono::hours(0), "File.RetentionMaxAge should default to 0 (disabled)");
     CheckNull(config.File.OnBackupCreated, "File.OnBackupCreated should default to unset");
     CheckEquals(0, config.File.MaxBackupFiles, "File.MaxBackupFiles should default to 0 (unlimited)");
diff --git a/tests/tests/Test_ASWLog_FileLog.cpp b/tests/tests/Test_ASWLog_FileLog.cpp
index fd0ad67..1e64720 100644
--- a/tests/tests/Test_ASWLog_FileLog.cpp
+++ b/tests/tests/Test_ASWLog_FileLog.cpp
@@ -56,6 +56,7 @@ limitations under the License.
 //---------------------------------------------------------------------------
 #include "ASWLog_FileLog.h"
 #include "ASWLog_Utils.h"
+#include "ASWLog_Version.h"
 //---------------------------------------------------------------------------
 #include "UT_Helper_DateTime.h"
 //---------------------------------------------------------------------------
@@ -280,6 +281,18 @@ void IgnoreError(const ASWLog::TASWLogError& /*error*/)
 {
 }
 
+ASWLog::TASWLogConfig MakeRotationTestConfig(const std::filesystem::path& logFile); // See below
+
+// A config for the tests of the startup lines in a new file (File.WriteStartupLinesInNewFiles): the rotation tests'
+// config with only the banner on, so a new file starts with ": Log continued from <file> (<reason>)" and ": banner"
+ASWLog::TASWLogConfig MakeNewFileTestConfig(const std::filesystem::path& logFile)
+{
+    auto config = MakeRotationTestConfig(logFile);
+    config.File.WriteStartupLinesInNewFiles = true;
+    config.Startup.Banner = "banner";
+    return config;
+}
+
 // A config for the rotation tests, with no line metadata or startup info, so each line is just its message
 ASWLog::TASWLogConfig MakeRotationTestConfig(const std::filesystem::path& logFile)
 {
@@ -301,6 +314,7 @@ ASWLog::TASWLogConfig MakeRotationTestConfig(const std::filesystem::path& logFil
     config.Startup.WriteApplicationInfo = false;
     config.Startup.WriteMemoryUsage = false;
     config.File.OpenRetryCount = 1;
+    config.File.WriteStartupLinesInNewFiles = false;
     config.Shutdown.WriteLine = false;
     return config;
 }
@@ -391,6 +405,17 @@ TTest_ASWLog_FileLog::TTest_ASWLog_FileLog()
     RegisterTest(&TTest_ASWLog_FileLog::Test_LogRawOptions, "LogRawOptions");
     RegisterTest(&TTest_ASWLog_FileLog::Test_MultiThreadedStress_WritesAllMessagesToDisk, "MultiThreadedStress_WritesAllMessagesToDisk");
     RegisterTest(&TTest_ASWLog_FileLog::Test_MultiThreadedStress_WritesAllMessagesToDisk_OpenClose, "MultiThreadedStress_WritesAllMessagesToDisk_OpenClose");
+    RegisterTest(&TTest_ASWLog_FileLog::Test_NewFile_AsyncWorkerWritesTheStartupLinesBeforeTheEntry, "NewFile_AsyncWorkerWritesTheStartupLinesBeforeTheEntry");
+    RegisterTest(&TTest_ASWLog_FileLog::Test_NewFile_DailyRollingStartsWithTheStartupLines, "NewFile_DailyRollingStartsWithTheStartupLines");
+    RegisterTest(&TTest_ASWLog_FileLog::Test_NewFile_FailedRotationWritesNoStartupLines, "NewFile_FailedRotationWritesNoStartupLines");
+    RegisterTest(&TTest_ASWLog_FileLog::Test_NewFile_InitializeWritesItsStartupLinesOnce, "NewFile_InitializeWritesItsStartupLinesOnce");
+    RegisterTest(&TTest_ASWLog_FileLog::Test_NewFile_ManualRotationOpensASharedLogForTheStartupLines, "NewFile_ManualRotationOpensASharedLogForTheStartupLines");
+    RegisterTest(&TTest_ASWLog_FileLog::Test_NewFile_MinimumLevelAboveInfoLeavesOutTheStartupLines, "NewFile_MinimumLevelAboveInfoLeavesOutTheStartupLines");
+    RegisterTest(&TTest_ASWLog_FileLog::Test_NewFile_ReconfigureToANewPathStartsWithTheStartupLines, "NewFile_ReconfigureToANewPathStartsWithTheStartupLines");
+    RegisterTest(&TTest_ASWLog_FileLog::Test_NewFile_RotationWaitsUntilTheStartupLinesAreWritten, "NewFile_RotationWaitsUntilTheStartupLinesAreWritten");
+    RegisterTest(&TTest_ASWLog_FileLog::Test_NewFile_SharedLogGetsTheStartupLinesOnce, "NewFile_SharedLogGetsTheStartupLinesOnce");
+    RegisterTest(&TTest_ASWLog_FileLog::Test_NewFile_SizeRotationStartsWithTheStartupLines, "NewFile_SizeRotationStartsWithTheStartupLines");
+    RegisterTest(&TTest_ASWLog_FileLog::Test_NewFile_UnopenedFileGetsTheStartupLinesWhenItOpens, "NewFile_UnopenedFileGetsTheStartupLinesWhenItOpens");
     RegisterTest(&TTest_ASWLog_FileLog::Test_OnBackupCreated_IsNotCalledWhenRotationFails, "OnBackupCreated_IsNotCalledWhenRotationFails");
     RegisterTest(&TTest_ASWLog_FileLog::Test_OnBackupCreated_LeavesARenamedBackupToTheApp, "OnBackupCreated_LeavesARenamedBackupToTheApp");
     RegisterTest(&TTest_ASWLog_FileLog::Test_OnBackupCreated_ReportsDailyBackupAtInitialize, "OnBackupCreated_ReportsDailyBackupAtInitialize");
@@ -1858,6 +1883,326 @@ void TTest_ASWLog_FileLog::Test_MultiThreadedStress_WritesAllMessagesToDisk_Open
     }
 }
 //---------------------------------------------------------------------------
+void TTest_ASWLog_FileLog::Test_NewFile_AsyncWorkerWritesTheStartupLinesBeforeTheEntry()
+{
+    // Arrange: the first entry reaches the 50-byte limit, so the logger's thread rotates the log for the second one
+    using namespace std::chrono_literals;
+    const auto logFile = TestTempDir / "new_async.log";
+    auto config = MakeNewFileTestConfig(logFile);
+    config.Async.Enabled = true;
+    config.File.EnableRotation = true;
+    config.File.MaxFileSizeBytes = 50;
+
+    TFixedClockFileLog logger;
+    logger.CurrentTime = std::chrono::sys_days{ 2026y / 1 / 15 } + 10h + 30min + 5s + 250ms;
+
+    // Act
+    const bool initialized = logger.Initialize(config);
+    logger.LogInfo("first_entry_long_enough_to_reach_the_size_limit");
+    logger.LogInfo("second_entry");
+    logger.Close();
+
+    // Assert
+    CheckTrue(initialized, "Initialize should succeed");
+    CheckEquals(std::string(": Log continued from new_async.size.2026-01-15_103005_250.bak (size)\n: banner\n: second_entry\n"),
+        ReadFileText(logFile), "The logger's thread should write the startup lines at the top of the new file, before the entry");
+}
+//---------------------------------------------------------------------------
+void TTest_ASWLog_FileLog::Test_NewFile_DailyRollingStartsWithTheStartupLines()
+{
+    // Arrange
+    using namespace std::chrono_literals;
+    const auto logFile = TestTempDir / "new_daily.log";
+    auto config = MakeNewFileTestConfig(logFile);
+    config.File.EnableDailyRolling = true;
+
+    const auto dayOne = std::chrono::sys_days{ 2026y / 1 / 15 };
+    TFixedClockFileLog logger;
+    logger.CurrentTime = dayOne + 23h + 59min;
+
+    // Act: log just before and just after UTC midnight
+    const bool initialized = logger.Initialize(config);
+    logger.LogInfo("day_one_entry");
+    logger.CurrentTime = dayOne + 24h + 30s;
+    logger.LogInfo("day_two_entry");
+    logger.Close();
+
+    // Assert
+    CheckTrue(initialized, "Initialize should succeed");
+    CheckEquals(std::string(": banner\n: day_one_entry\n"), ReadFileText(TestTempDir / "new_daily.daily.2026-01-15.bak"),
+        "The daily backup should hold the first day's file as it was");
+    CheckEquals(std::string(": Log continued from new_daily.daily.2026-01-15.bak (daily)\n: banner\n: day_two_entry\n"),
+        ReadFileText(logFile), "The new day's file should start with the startup lines, before the entry that rolled it over");
+    CheckEquals(1, CountFilesStartingWith("new_daily.daily."), "Writing the startup lines should not roll the log over again");
+}
+//---------------------------------------------------------------------------
+void TTest_ASWLog_FileLog::Test_NewFile_FailedRotationWritesNoStartupLines()
+{
+    // Arrange
+    if (!CanBlockFiles())
+        Skip("File permissions don't stop the root user, so the failure can't be simulated");
+
+    const auto logFile = TestTempDir / "new_failed.log";
+    auto config = MakeNewFileTestConfig(logFile);
+    config.File.EnableRotation = true;
+    config.File.MaxFileSizeBytes = 50;
+    config.OnError = IgnoreError;
+
+    ASWLog::TASWFileLog logger;
+
+    // Act
+    const bool initialized = logger.Initialize(config);
+    logger.LogInfo("line_one_long_enough_to_reach_the_size_limit_alone");
+    {
+        // The size rotation's rename fails, but the log reopens, so the entry is still written
+        TFileBlocker blocker(logFile, false);
+        logger.LogInfo("line_two");
+    }
+    logger.Close();
+
+    // Assert
+    CheckTrue(initialized, "Initialize should succeed");
+    CheckEquals(0, CountFilesStartingWith("new_failed.size."), "The rotation should have failed");
+    CheckEquals(std::string(": banner\n: line_one_long_enough_to_reach_the_size_limit_alone\n: line_two\n"),
+        ReadFileText(logFile), "A failed rotation starts no new file, so it should write no startup lines");
+}
+//---------------------------------------------------------------------------
+void TTest_ASWLog_FileLog::Test_NewFile_InitializeWritesItsStartupLinesOnce()
+{
+    // Arrange: a log last written 30 hours before the logger starts, which Initialize() rolls over
+    using namespace std::chrono_literals;
+    const auto logFile = TestTempDir / "new_initialize.log";
+    std::ofstream(logFile) << "yesterday_entry\n";
+    std::filesystem::last_write_time(logFile, std::chrono::file_clock::now() - 30h);
+
+    auto config = MakeNewFileTestConfig(logFile);
+    config.File.EnableDailyRolling = true;
+
+    TFixedClockFileLog logger;
+    logger.CurrentTime = std::chrono::sys_days{ 2026y / 1 / 15 } + 10h;
+
+    // Act
+    const bool initialized = logger.Initialize(config);
+    logger.LogInfo("today_entry");
+    logger.Close();
+
+    // Assert
+    CheckTrue(initialized, "Initialize should succeed");
+    CheckTrue(std::filesystem::exists(TestTempDir / "new_initialize.daily.2026-01-14.bak"), "Initialize() should roll the earlier day's log over");
+    CheckEquals(std::string(": banner\n: today_entry\n"), ReadFileText(logFile),
+        "The file Initialize() starts should get its startup lines once, without a continuation line");
+}
+//---------------------------------------------------------------------------
+void TTest_ASWLog_FileLog::Test_NewFile_ManualRotationOpensASharedLogForTheStartupLines()
+{
+    // Arrange
+    using namespace std::chrono_literals;
+    const auto logFile = TestTempDir / "new_manual.log";
+    auto config = MakeNewFileTestConfig(logFile);
+    config.File.AutoOpenClosePerWrite = true;
+
+    TFixedClockFileLog logger;
+    logger.CurrentTime = std::chrono::sys_days{ 2026y / 1 / 15 } + 10h + 30min + 5s + 250ms;
+
+    // Act
+    const bool initialized = logger.Initialize(config);
+    logger.LogInfo("before_rotation");
+    const bool rotated = logger.RotateLogFiles("deploy");
+    const auto contentsAfterRotation = ReadFileText(logFile);
+    const bool openAfterRotation = logger.IsOpen();
+    logger.LogInfo("after_rotation");
+    logger.Close();
+
+    // Assert
+    constexpr std::string_view startupLines = ": Log continued from new_manual.deploy.2026-01-15_103005_250.bak (deploy)\n: banner\n";
+    CheckTrue(initialized, "Initialize should succeed");
+    CheckTrue(rotated, "RotateLogFiles should succeed");
+    CheckEquals(std::string(startupLines), contentsAfterRotation,
+        "With File.AutoOpenClosePerWrite, RotateLogFiles() should open the new file for its startup lines at once, naming the reason tag");
+    CheckFalse(openAfterRotation, "The file should be closed again after its startup lines");
+    CheckEquals(std::string(startupLines) + ": after_rotation\n", ReadFileText(logFile), "The next entry should follow the startup lines");
+}
+//---------------------------------------------------------------------------
+void TTest_ASWLog_FileLog::Test_NewFile_MinimumLevelAboveInfoLeavesOutTheStartupLines()
+{
+    // Arrange
+    const auto logFile = TestTempDir / "new_level.log";
+    auto config = MakeNewFileTestConfig(logFile);
+    config.InitialMinimumLevel = ASWLog::Level::Warn;
+
+    ASWLog::TASWFileLog logger;
+
+    // Act
+    const bool initialized = logger.Initialize(config);
+    logger.LogWarn("before_rotation");
+    const bool rotated = logger.RotateLogFiles("manual");
+    logger.LogWarn("after_rotation");
+    logger.Close();
+
+    // Assert
+    CheckTrue(initialized, "Initialize should succeed");
+    CheckTrue(rotated, "RotateLogFiles should succeed");
+    CheckEquals(std::string(": after_rotation\n"), ReadFileText(logFile),
+        "The startup lines are Info lines, so a minimum level above Info should leave them out of a new file too");
+}
+//---------------------------------------------------------------------------
+void TTest_ASWLog_FileLog::Test_NewFile_ReconfigureToANewPathStartsWithTheStartupLines()
+{
+    // Arrange
+    const auto firstFile = TestTempDir / "new_reconfigure_first.log";
+    const auto secondFile = TestTempDir / "new_reconfigure_second.log";
+    auto config = MakeNewFileTestConfig(firstFile);
+    const auto firstPath = ASWLog::PathToUTF8String(config.File.ResolvePath());
+
+    ASWLog::TASWFileLog logger;
+    const bool initialized = logger.Initialize(config);
+
+    // Act: a new path, then only File.AutoOpenClosePerWrite, which keeps the file
+    logger.LogInfo("to_first");
+    config.File.FilePath = secondFile;
+    const bool movedToSecond = logger.Reconfigure(config);
+    logger.LogInfo("to_second");
+    config.File.AutoOpenClosePerWrite = true;
+    const bool switchedToAutoOpenClose = logger.Reconfigure(config);
+    logger.LogInfo("auto_open_close");
+    logger.Close();
+
+    // Assert
+    CheckTrue(initialized, "Initialize should succeed");
+    CheckTrue(movedToSecond, "Reconfigure() to a new file path should succeed");
+    CheckTrue(switchedToAutoOpenClose, "Reconfigure() to File.AutoOpenClosePerWrite should succeed");
+    CheckEquals(std::string(": banner\n: to_first\n"), ReadFileText(firstFile), "The first file should end as it was");
+    CheckEquals(std::format(": Log continued from {} (reconfigure)\n: banner\n: to_second\n: auto_open_close\n", firstPath),
+        ReadFileText(secondFile), "The new file should start with the startup lines, naming the previous file's path, and only once");
+}
+//---------------------------------------------------------------------------
+void TTest_ASWLog_FileLog::Test_NewFile_RotationWaitsUntilTheStartupLinesAreWritten()
+{
+    // Arrange: the banner alone reaches the 50-byte limit, so each block of startup lines is longer than the limit
+    using namespace std::chrono_literals;
+    const auto logFile = TestTempDir / "new_guard.log";
+    auto config = MakeNewFileTestConfig(logFile);
+    config.File.EnableRotation = true;
+    config.File.MaxFileSizeBytes = 50;
+    config.Startup.Banner = "banner_long_enough_to_reach_the_size_limit_on_its_own";
+    config.Startup.WriteLoggerVersion = true;
+
+    TFixedClockFileLog logger;
+    logger.CurrentTime = std::chrono::sys_days{ 2026y / 1 / 15 } + 10h + 30min + 5s + 250ms;
+
+    // Act
+    const bool initialized = logger.Initialize(config);
+    logger.LogInfo("entry");
+    logger.Close();
+
+    // Assert
+    const auto startupLines = std::format(": {}\n: ASWLog: version={}, logger=TASWFileLog\n", config.Startup.Banner, ASWLog::Version);
+    CheckTrue(initialized, "Initialize should succeed");
+    CheckEquals(1, CountFilesStartingWith("new_guard.size."), "Only the entry should rotate the log, not a startup line");
+    CheckEquals(startupLines, ReadFileText(TestTempDir / "new_guard.size.2026-01-15_103005_250.bak"),
+        "Initialize()'s startup lines should stay together in the first file");
+    CheckEquals(": Log continued from new_guard.size.2026-01-15_103005_250.bak (size)\n" + startupLines + ": entry\n",
+        ReadFileText(logFile), "The new file's startup lines should stay together, followed by the entry");
+}
+//---------------------------------------------------------------------------
+void TTest_ASWLog_FileLog::Test_NewFile_SharedLogGetsTheStartupLinesOnce()
+{
+    // Arrange: two loggers sharing one log, as two processes would (File.AutoOpenClosePerWrite), both logging at 23:59 UTC
+    using namespace std::chrono_literals;
+    const auto logFile = TestTempDir / "new_shared.log";
+    auto config = MakeNewFileTestConfig(logFile);
+    config.File.EnableDailyRolling = true;
+    config.File.AutoOpenClosePerWrite = true;
+
+    const auto dayOne = std::chrono::sys_days{ 2026y / 1 / 15 };
+    TFixedClockFileLog firstLogger;
+    TFixedClockFileLog secondLogger;
+    firstLogger.CurrentTime = dayOne + 23h + 59min;
+    secondLogger.CurrentTime = dayOne + 23h + 59min;
+
+    const bool firstInitialized = firstLogger.Initialize(config);
+    const bool secondInitialized = secondLogger.Initialize(config);
+    firstLogger.LogInfo("first_day_one_entry");
+    secondLogger.LogInfo("second_day_one_entry");
+
+    // The file was written at 23:59; make its age match the clocks' jump past midnight below
+    std::filesystem::last_write_time(logFile, std::chrono::file_clock::now() - 2min);
+    firstLogger.CurrentTime = dayOne + 24h + 30s;
+    secondLogger.CurrentTime = dayOne + 24h + 40s;
+
+    // Act: the first logger rolls the log over; the second then finds a log from today
+    firstLogger.LogInfo("first_day_two_entry");
+    secondLogger.LogInfo("second_day_two_entry");
+    firstLogger.Close();
+    secondLogger.Close();
+
+    // Assert
+    CheckTrue(firstInitialized && secondInitialized, "Initialize should succeed");
+    CheckEquals(std::string(": Log continued from new_shared.daily.2026-01-15.bak (daily)\n: banner\n: first_day_two_entry\n: second_day_two_entry\n"),
+        ReadFileText(logFile), "Only the logger that rolled the shared log over should write the startup lines");
+}
+//---------------------------------------------------------------------------
+void TTest_ASWLog_FileLog::Test_NewFile_SizeRotationStartsWithTheStartupLines()
+{
+    // Arrange: Initialize()'s lines and the first entry reach the 100-byte limit, so the second entry rotates the log
+    using namespace std::chrono_literals;
+    const auto logFile = TestTempDir / "new_size.log";
+    auto config = MakeNewFileTestConfig(logFile);
+    config.File.EnableRotation = true;
+    config.File.MaxFileSizeBytes = 100;
+    config.Startup.WriteLoggerVersion = true;
+
+    TFixedClockFileLog logger;
+    logger.CurrentTime = std::chrono::sys_days{ 2026y / 1 / 15 } + 10h + 30min + 5s + 250ms;
+
+    // Act
+    const bool initialized = logger.Initialize(config);
+    logger.LogInfo("first_entry_long_enough_to_reach_the_size_limit");
+    logger.LogInfo("second_entry");
+    logger.Close();
+
+    // Assert
+    const auto startupLines = std::format(": banner\n: ASWLog: version={}, logger=TASWFileLog\n", ASWLog::Version);
+    CheckTrue(initialized, "Initialize should succeed");
+    CheckEquals(startupLines + ": first_entry_long_enough_to_reach_the_size_limit\n",
+        ReadFileText(TestTempDir / "new_size.size.2026-01-15_103005_250.bak"), "The backup should hold the first file as it was");
+    CheckEquals(": Log continued from new_size.size.2026-01-15_103005_250.bak (size)\n" + startupLines + ": second_entry\n",
+        ReadFileText(logFile), "The new file should start with the continuation line and the startup lines, before the entry that rotated the log");
+}
+//---------------------------------------------------------------------------
+void TTest_ASWLog_FileLog::Test_NewFile_UnopenedFileGetsTheStartupLinesWhenItOpens()
+{
+    // Arrange: a "folder" that is a file can't hold the new log, on any OS and for any user
+    using namespace std::chrono_literals;
+    const auto logFile = TestTempDir / "new_unopened.log";
+    const auto laterFolder = TestTempDir / "later_folder";
+    std::ofstream(laterFolder) << "file";
+
+    auto config = MakeNewFileTestConfig(logFile);
+    config.File.CircuitBreakerResetDelay = 0ms;
+    config.OnError = IgnoreError;
+    const auto firstPath = ASWLog::PathToUTF8String(config.File.ResolvePath());
+
+    auto laterConfig = config;
+    laterConfig.File.FilePath = laterFolder / "later.log";
+
+    ASWLog::TASWFileLog logger;
+    const bool initialized = logger.Initialize(config);
+
+    // Act: the new file can't be opened at first; once its folder can be made, the next entry opens it
+    const bool reconfigured = logger.Reconfigure(laterConfig);
+    logger.LogInfo("dropped");
+    std::filesystem::remove(laterFolder);
+    logger.LogInfo("written");
+    logger.Close();
+
+    // Assert
+    CheckTrue(initialized, "Initialize should succeed");
+    CheckFalse(reconfigured, "Reconfigure() should fail while the new file can't be opened");
+    CheckEquals(std::format(": Log continued from {} (reconfigure)\n: banner\n: written\n", firstPath),
+        ReadFileText(laterFolder / "later.log"), "The open that succeeds should write the startup lines, before its entry");
+}
+//---------------------------------------------------------------------------
 void TTest_ASWLog_FileLog::Test_OnBackupCreated_IsNotCalledWhenRotationFails()
 {
     // Arrange
diff --git a/tests/tests/Test_ASWLog_FileLog.h b/tests/tests/Test_ASWLog_FileLog.h
index c18e7ba..d7d1d7e 100644
--- a/tests/tests/Test_ASWLog_FileLog.h
+++ b/tests/tests/Test_ASWLog_FileLog.h
@@ -77,6 +77,17 @@ class TTest_ASWLog_FileLog : public TTestGroupBase
     void Test_LogRawOptions();
     void Test_MultiThreadedStress_WritesAllMessagesToDisk();
     void Test_MultiThreadedStress_WritesAllMessagesToDisk_OpenClose();
+    void Test_NewFile_AsyncWorkerWritesTheStartupLinesBeforeTheEntry();
+    void Test_NewFile_DailyRollingStartsWithTheStartupLines();
+    void Test_NewFile_FailedRotationWritesNoStartupLines();
+    void Test_NewFile_InitializeWritesItsStartupLinesOnce();
+    void Test_NewFile_ManualRotationOpensASharedLogForTheStartupLines();
+    void Test_NewFile_MinimumLevelAboveInfoLeavesOutTheStartupLines();
+    void Test_NewFile_ReconfigureToANewPathStartsWithTheStartupLines();
+    void Test_NewFile_RotationWaitsUntilTheStartupLinesAreWritten();
+    void Test_NewFile_SharedLogGetsTheStartupLinesOnce();
+    void Test_NewFile_SizeRotationStartsWithTheStartupLines();
+    void Test_NewFile_UnopenedFileGetsTheStartupLinesWhenItOpens();
     void Test_OnBackupCreated_IsNotCalledWhenRotationFails();
     void Test_OnBackupCreated_LeavesARenamedBackupToTheApp();
     void Test_OnBackupCreated_ReportsDailyBackupAtInitialize();

From 86d2fa34e773089963d1f7c68f7e188e2bf987e0 Mon Sep 17 00:00:00 2001
From: Anthony West <anthony.s.west@gmail.com>
Date: Sat, 10 Oct 2026 23:18:44 -0700
Subject: [PATCH 06/12] Test that DeleteOldLogs deletes only matching files

---
 tests/tests/Test_ASWLog_FileLog.cpp | 22 ++++++++++++++++++++++
 tests/tests/Test_ASWLog_FileLog.h   |  1 +
 tests/tests/Test_ASWLog_Utils.cpp   |  5 +++++
 3 files changed, 28 insertions(+)

diff --git a/tests/tests/Test_ASWLog_FileLog.cpp b/tests/tests/Test_ASWLog_FileLog.cpp
index 1e64720..6c5e6d2 100644
--- a/tests/tests/Test_ASWLog_FileLog.cpp
+++ b/tests/tests/Test_ASWLog_FileLog.cpp
@@ -385,6 +385,7 @@ TTest_ASWLog_FileLog::TTest_ASWLog_FileLog()
     RegisterTest(&TTest_ASWLog_FileLog::Test_DailyRolling_SharedLogRollsOverOnce, "DailyRolling_SharedLogRollsOverOnce");
     RegisterTest(&TTest_ASWLog_FileLog::Test_DeleteOldLogs_AcceptsShortRelativeFolder, "DeleteOldLogs_AcceptsShortRelativeFolder");
     RegisterTest(&TTest_ASWLog_FileLog::Test_DeleteOldLogs_EmptyPatternDeletesNothing, "DeleteOldLogs_EmptyPatternDeletesNothing");
+    RegisterTest(&TTest_ASWLog_FileLog::Test_DeleteOldLogs_KeepsNonMatchingFilesAndSubfolders, "DeleteOldLogs_KeepsNonMatchingFilesAndSubfolders");
     RegisterTest(&TTest_ASWLog_FileLog::Test_DeleteOldLogs_MatchesNonASCIIFileNames, "DeleteOldLogs_MatchesNonASCIIFileNames");
     RegisterTest(&TTest_ASWLog_FileLog::Test_DeleteOldLogs_RemovesOldFiles, "DeleteOldLogs_RemovesOldFiles");
     RegisterTest(&TTest_ASWLog_FileLog::Test_FailedReopen_RetriesAndResumesLogging, "FailedReopen_RetriesAndResumesLogging");
@@ -1159,6 +1160,27 @@ void TTest_ASWLog_FileLog::Test_DeleteOldLogs_EmptyPatternDeletesNothing()
     CheckFalse(std::filesystem::exists(oldFile), "The \"*\" pattern should remove the old file");
 }
 //---------------------------------------------------------------------------
+void TTest_ASWLog_FileLog::Test_DeleteOldLogs_KeepsNonMatchingFilesAndSubfolders()
+{
+    // Arrange: an empty subfolder whose name matches the pattern, besides a matching and a non-matching file
+    const auto matchingFile = TestTempDir / "old_example.log";
+    const auto otherFile = TestTempDir / "old_example.txt";
+    const auto subfolder = TestTempDir / "sub_example.log";
+    std::ofstream(matchingFile) << "old";
+    std::ofstream(otherFile) << "old";
+    std::filesystem::create_directory(subfolder);
+
+    // Act: a negative age puts the cutoff an hour from now, so every entry counts as old, also the subfolder (Windows
+    // can't set a folder's last write time through std::filesystem)
+    const auto deletedCount = ASWLog::TASWFileLog::DeleteOldLogs(TestTempDir, "*example.log", std::chrono::hours(-1));
+
+    // Assert
+    CheckEquals(1, deletedCount, "DeleteOldLogs should delete only the old file matching the pattern");
+    CheckFalse(std::filesystem::exists(matchingFile), "The old file matching the pattern should be deleted");
+    CheckTrue(std::filesystem::exists(otherFile), "An old file that doesn't match the pattern should be kept");
+    CheckTrue(std::filesystem::is_directory(subfolder), "A subfolder should be kept, even if its name matches the pattern");
+}
+//---------------------------------------------------------------------------
 void TTest_ASWLog_FileLog::Test_DeleteOldLogs_MatchesNonASCIIFileNames()
 {
     // Arrange: a file name with a character outside the Windows ANSI code page (Greek small lambda, U+03BB, which is
diff --git a/tests/tests/Test_ASWLog_FileLog.h b/tests/tests/Test_ASWLog_FileLog.h
index d7d1d7e..fd7ca6a 100644
--- a/tests/tests/Test_ASWLog_FileLog.h
+++ b/tests/tests/Test_ASWLog_FileLog.h
@@ -57,6 +57,7 @@ class TTest_ASWLog_FileLog : public TTestGroupBase
     void Test_DailyRolling_SharedLogRollsOverOnce();
     void Test_DeleteOldLogs_AcceptsShortRelativeFolder();
     void Test_DeleteOldLogs_EmptyPatternDeletesNothing();
+    void Test_DeleteOldLogs_KeepsNonMatchingFilesAndSubfolders();
     void Test_DeleteOldLogs_MatchesNonASCIIFileNames();
     void Test_DeleteOldLogs_RemovesOldFiles();
     void Test_FailedReopen_RetriesAndResumesLogging();
diff --git a/tests/tests/Test_ASWLog_Utils.cpp b/tests/tests/Test_ASWLog_Utils.cpp
index ecff156..5f03940 100644
--- a/tests/tests/Test_ASWLog_Utils.cpp
+++ b/tests/tests/Test_ASWLog_Utils.cpp
@@ -686,6 +686,11 @@ void TTest_ASWLog_Utils::Test_MatchesWildcard_Patterns()
     CheckTrue(ASWLog::MatchesWildcard(fileName2, "n?tes.*"), "Question mark wildcard should match a single character");
     CheckFalse(ASWLog::MatchesWildcard(fileName, "*.txt"), "Wildcard should reject non-matching files");
     CheckTrue(ASWLog::MatchesWildcard("no_extension", "*"), "A lone '*' should match any name, with or without a dot");
+    CheckFalse(ASWLog::MatchesWildcard(fileName, "app_123.txt"), "A pattern without wildcards should reject a different name");
+    CheckFalse(ASWLog::MatchesWildcard(fileName, "app_123.lo"), "A pattern without wildcards should reject a name that goes on past it");
+    CheckFalse(ASWLog::MatchesWildcard(fileName, "app_123.log.bak"), "A pattern without wildcards should reject a name that ends before it");
+    CheckTrue(ASWLog::MatchesWildcard(fileName, "app_123.log**"), "Trailing '*'s should also match nothing");
+    CheckFalse(ASWLog::MatchesWildcard("", "?"), "'?' should need a character");
 }
 //---------------------------------------------------------------------------
 void TTest_ASWLog_Utils::Test_ReadEnvironmentVariable_ReadsUTF8Values()

From dc95cf9055f5f73d77727a7f881bab56d6e03958 Mon Sep 17 00:00:00 2001
From: Anthony West <anthony.s.west@gmail.com>
Date: Sat, 10 Oct 2026 23:26:32 -0700
Subject: [PATCH 07/12] Test backup name exhaustion and open retries

---
 tests/tests/Test_ASWLog_FileLog.cpp | 95 +++++++++++++++++++++++++++++
 tests/tests/Test_ASWLog_FileLog.h   |  3 +
 2 files changed, 98 insertions(+)

diff --git a/tests/tests/Test_ASWLog_FileLog.cpp b/tests/tests/Test_ASWLog_FileLog.cpp
index 6c5e6d2..1305dc9 100644
--- a/tests/tests/Test_ASWLog_FileLog.cpp
+++ b/tests/tests/Test_ASWLog_FileLog.cpp
@@ -388,6 +388,7 @@ TTest_ASWLog_FileLog::TTest_ASWLog_FileLog()
     RegisterTest(&TTest_ASWLog_FileLog::Test_DeleteOldLogs_KeepsNonMatchingFilesAndSubfolders, "DeleteOldLogs_KeepsNonMatchingFilesAndSubfolders");
     RegisterTest(&TTest_ASWLog_FileLog::Test_DeleteOldLogs_MatchesNonASCIIFileNames, "DeleteOldLogs_MatchesNonASCIIFileNames");
     RegisterTest(&TTest_ASWLog_FileLog::Test_DeleteOldLogs_RemovesOldFiles, "DeleteOldLogs_RemovesOldFiles");
+    RegisterTest(&TTest_ASWLog_FileLog::Test_FailedOpen_TriesOpenRetryCountTimes, "FailedOpen_TriesOpenRetryCountTimes");
     RegisterTest(&TTest_ASWLog_FileLog::Test_FailedReopen_RetriesAndResumesLogging, "FailedReopen_RetriesAndResumesLogging");
     RegisterTest(&TTest_ASWLog_FileLog::Test_FailedReopen_ZeroResetDelayRetriesOnNextWrite, "FailedReopen_ZeroResetDelayRetriesOnNextWrite");
     RegisterTest(&TTest_ASWLog_FileLog::Test_FailedSizeRotation_WaitsBeforeRetrying, "FailedSizeRotation_WaitsBeforeRetrying");
@@ -430,6 +431,7 @@ TTest_ASWLog_FileLog::TTest_ASWLog_FileLog()
     RegisterTest(&TTest_ASWLog_FileLog::Test_OnError_ReportsFullDisk, "OnError_ReportsFullDisk");
     RegisterTest(&TTest_ASWLog_FileLog::Test_OnLogEntry_FiresForQualifyingLevelsOnly, "OnLogEntry_FiresForQualifyingLevelsOnly");
     RegisterTest(&TTest_ASWLog_FileLog::Test_OnLogEntry_ReentrantCallbackDoesNotDeadlock, "OnLogEntry_ReentrantCallbackDoesNotDeadlock");
+    RegisterTest(&TTest_ASWLog_FileLog::Test_Open_KeepsAnOpenFile, "Open_KeepsAnOpenFile");
     RegisterTest(&TTest_ASWLog_FileLog::Test_Periodic_CloseStopsAndOpenRestartsTheThread, "Periodic_CloseStopsAndOpenRestartsTheThread");
     RegisterTest(&TTest_ASWLog_FileLog::Test_Periodic_CloseStopsTheThreadWithoutWaitingForTheInterval, "Periodic_CloseStopsTheThreadWithoutWaitingForTheInterval");
     RegisterTest(&TTest_ASWLog_FileLog::Test_Periodic_ConcurrentLoggingAndReconfigure, "Periodic_ConcurrentLoggingAndReconfigure");
@@ -444,6 +446,7 @@ TTest_ASWLog_FileLog::TTest_ASWLog_FileLog()
     RegisterTest(&TTest_ASWLog_FileLog::Test_Reconfigure_UnopenableFileFailsButLoggerStaysInitialized, "Reconfigure_UnopenableFileFailsButLoggerStaysInitialized");
     RegisterTest(&TTest_ASWLog_FileLog::Test_RetentionMaxAge_DefaultDisabledPreservesOldBackups, "RetentionMaxAge_DefaultDisabledPreservesOldBackups");
     RegisterTest(&TTest_ASWLog_FileLog::Test_RetentionMaxAge_DeletesExpiredBackupsAfterRotation, "RetentionMaxAge_DeletesExpiredBackupsAfterRotation");
+    RegisterTest(&TTest_ASWLog_FileLog::Test_RotateLogFiles_FailsWhenEveryBackupNameIsTaken, "RotateLogFiles_FailsWhenEveryBackupNameIsTaken");
     RegisterTest(&TTest_ASWLog_FileLog::Test_RotateLogFiles_KeepsEveryBackup, "RotateLogFiles_KeepsEveryBackup");
     RegisterTest(&TTest_ASWLog_FileLog::Test_RotateLogFiles_NamesBackupInLocalTime, "RotateLogFiles_NamesBackupInLocalTime");
     RegisterTest(&TTest_ASWLog_FileLog::Test_SetEnabled_FalseStopsAutoOpenCloseLogging, "SetEnabled_FalseStopsAutoOpenCloseLogging");
@@ -1240,6 +1243,34 @@ void TTest_ASWLog_FileLog::Test_DeleteOldLogs_RemovesOldFiles()
     CheckTrue(std::filesystem::exists(newFile), "Recent log file should remain");
 }
 //---------------------------------------------------------------------------
+void TTest_ASWLog_FileLog::Test_FailedOpen_TriesOpenRetryCountTimes()
+{
+    // Arrange: a "folder" that is a file can't hold the log, on any OS and for any user
+    using namespace std::chrono_literals;
+    const auto notAFolder = TestTempDir / "retry_not_a_folder";
+    std::ofstream(notAFolder) << "file";
+
+    auto config = MakeRotationTestConfig(notAFolder / "unopenable.log");
+    config.File.OpenRetryCount = 3;
+    config.File.OpenRetryDelay = 50ms;
+    std::vector<ASWLog::TASWLogError> reports;
+    config.OnError = [&reports](const ASWLog::TASWLogError& error) {
+            reports.push_back(error);
+        };
+
+    ASWLog::TASWFileLog logger;
+
+    // Act
+    const auto start = std::chrono::steady_clock::now();
+    const bool initialized = logger.Initialize(config);
+    const auto elapsed = std::chrono::duration_cast<std::chrono::milliseconds>(std::chrono::steady_clock::now() - start);
+
+    // Assert: three tries, with File.OpenRetryDelay between them
+    CheckFalse(initialized, "Initialize should fail");
+    CheckGreaterThanOrEqual(elapsed.count(), 100, "Each try after the first should wait File.OpenRetryDelay");
+    CheckEquals(1, reports.size(), "The failed open should be reported once, after the last try");
+}
+//---------------------------------------------------------------------------
 void TTest_ASWLog_FileLog::Test_FailedReopen_RetriesAndResumesLogging()
 {
     // Arrange
@@ -2722,6 +2753,29 @@ void TTest_ASWLog_FileLog::Test_OnLogEntry_ReentrantCallbackDoesNotDeadlock()
     CheckContains(contents, "reentrant_message", "Re-entrant Log call from the callback should complete and be written");
 }
 //---------------------------------------------------------------------------
+void TTest_ASWLog_FileLog::Test_Open_KeepsAnOpenFile()
+{
+    // Arrange
+    const auto logFile = TestTempDir / "open_again.log";
+    const auto config = MakeRotationTestConfig(logFile);
+
+    ASWLog::TASWFileLog logger;
+
+    // Act
+    const bool initialized = logger.Initialize(config);
+    logger.LogInfo("before_open");
+    const bool opened = logger.Open();
+    const bool openAfterOpen = logger.IsOpen();
+    logger.LogInfo("after_open");
+    logger.Close();
+
+    // Assert
+    CheckTrue(initialized, "Initialize should succeed");
+    CheckTrue(opened, "Open() on an open logger should succeed");
+    CheckTrue(openAfterOpen, "The logger should still report open");
+    CheckEquals(std::string(": before_open\n: after_open\n"), ReadFileText(logFile), "The logger should go on writing to its file");
+}
+//---------------------------------------------------------------------------
 void TTest_ASWLog_FileLog::Test_Periodic_CloseStopsAndOpenRestartsTheThread()
 {
     // Arrange
@@ -3185,6 +3239,47 @@ void TTest_ASWLog_FileLog::Test_RetentionMaxAge_DeletesExpiredBackupsAfterRotati
     CheckTrue(std::filesystem::exists(logFile), "Log file should be recreated after rotation");
 }
 //---------------------------------------------------------------------------
+void TTest_ASWLog_FileLog::Test_RotateLogFiles_FailsWhenEveryBackupNameIsTaken()
+{
+    // Arrange: every name the rotation could use (the plain one, then "_1" to "_1000") is taken
+    using namespace std::chrono_literals;
+    const auto logFile = TestTempDir / "taken.log";
+    auto config = MakeRotationTestConfig(logFile);
+    std::vector<ASWLog::TASWLogError> reports;
+    config.OnError = [&reports](const ASWLog::TASWLogError& error) {
+            reports.push_back(error);
+        };
+
+    const std::string backupName = "taken.manual.2026-01-15_103005_250";
+    std::ofstream(TestTempDir / (backupName + ".bak")) << "kept";
+    for (int suffix = 1; suffix <= 1000; ++suffix)
+        std::ofstream(TestTempDir / std::format("{}_{}.bak", backupName, suffix)) << "kept";
+
+    TFixedClockFileLog logger;
+    logger.CurrentTime = std::chrono::sys_days{ 2026y / 1 / 15 } + 10h + 30min + 5s + 250ms;
+
+    // Act
+    const bool initialized = logger.Initialize(config);
+    logger.LogInfo("before_rotation");
+    const bool rotated = logger.RotateLogFiles("manual");
+    logger.LogInfo("after_rotation");
+    logger.Close();
+
+    // Assert
+    CheckTrue(initialized, "Initialize should succeed");
+    CheckFalse(rotated, "RotateLogFiles should fail when every backup name is taken");
+    CheckEquals(1, reports.size(), "The failed rotation should be reported");
+    if (reports.size() == 1)
+    {
+        CheckEquals(ASWLog::ErrorKind::RotationFailed, reports[0].Kind, "The failure should be reported as RotationFailed");
+        CheckTrue(reports[0].Code == std::errc::file_exists, "The report should say that the names are taken: " + reports[0].Code.message());
+    }
+
+    CheckEquals(std::string(": before_rotation\n: after_rotation\n"), ReadFileText(logFile), "The log should stay in place and take the next entries");
+    CheckEquals(std::string("kept"), ReadFileText(TestTempDir / (backupName + ".bak")), "The first backup name should not be replaced");
+    CheckEquals(std::string("kept"), ReadFileText(TestTempDir / (backupName + "_1000.bak")), "The last backup name should not be replaced");
+}
+//---------------------------------------------------------------------------
 void TTest_ASWLog_FileLog::Test_RotateLogFiles_KeepsEveryBackup()
 {
     // Arrange: a fixed clock makes both rotations want the same backup name
diff --git a/tests/tests/Test_ASWLog_FileLog.h b/tests/tests/Test_ASWLog_FileLog.h
index fd7ca6a..1cc715c 100644
--- a/tests/tests/Test_ASWLog_FileLog.h
+++ b/tests/tests/Test_ASWLog_FileLog.h
@@ -60,6 +60,7 @@ class TTest_ASWLog_FileLog : public TTestGroupBase
     void Test_DeleteOldLogs_KeepsNonMatchingFilesAndSubfolders();
     void Test_DeleteOldLogs_MatchesNonASCIIFileNames();
     void Test_DeleteOldLogs_RemovesOldFiles();
+    void Test_FailedOpen_TriesOpenRetryCountTimes();
     void Test_FailedReopen_RetriesAndResumesLogging();
     void Test_FailedReopen_ZeroResetDelayRetriesOnNextWrite();
     void Test_FailedSizeRotation_WaitsBeforeRetrying();
@@ -102,6 +103,7 @@ class TTest_ASWLog_FileLog : public TTestGroupBase
     void Test_OnError_ReportsFullDisk();
     void Test_OnLogEntry_FiresForQualifyingLevelsOnly();
     void Test_OnLogEntry_ReentrantCallbackDoesNotDeadlock();
+    void Test_Open_KeepsAnOpenFile();
     void Test_Periodic_CloseStopsAndOpenRestartsTheThread();
     void Test_Periodic_CloseStopsTheThreadWithoutWaitingForTheInterval();
     void Test_Periodic_ConcurrentLoggingAndReconfigure();
@@ -116,6 +118,7 @@ class TTest_ASWLog_FileLog : public TTestGroupBase
     void Test_Reconfigure_UnopenableFileFailsButLoggerStaysInitialized();
     void Test_RetentionMaxAge_DefaultDisabledPreservesOldBackups();
     void Test_RetentionMaxAge_DeletesExpiredBackupsAfterRotation();
+    void Test_RotateLogFiles_FailsWhenEveryBackupNameIsTaken();
     void Test_RotateLogFiles_KeepsEveryBackup();
     void Test_RotateLogFiles_NamesBackupInLocalTime();
     void Test_SetEnabled_FalseStopsAutoOpenCloseLogging();

From ce50957095696439b85b8903cd4f963ae3963f5c Mon Sep 17 00:00:00 2001
From: Anthony West <anthony.s.west@gmail.com>
Date: Sat, 10 Oct 2026 23:33:41 -0700
Subject: [PATCH 08/12] Test TASWFileStream's stream insertion

---
 tests/tests/Test_ASWLog_FileLog.cpp | 41 +++++++++++++++++++++++++++++
 tests/tests/Test_ASWLog_FileLog.h   |  2 ++
 2 files changed, 43 insertions(+)

diff --git a/tests/tests/Test_ASWLog_FileLog.cpp b/tests/tests/Test_ASWLog_FileLog.cpp
index 1305dc9..4bf6b53 100644
--- a/tests/tests/Test_ASWLog_FileLog.cpp
+++ b/tests/tests/Test_ASWLog_FileLog.cpp
@@ -393,6 +393,8 @@ TTest_ASWLog_FileLog::TTest_ASWLog_FileLog()
     RegisterTest(&TTest_ASWLog_FileLog::Test_FailedReopen_ZeroResetDelayRetriesOnNextWrite, "FailedReopen_ZeroResetDelayRetriesOnNextWrite");
     RegisterTest(&TTest_ASWLog_FileLog::Test_FailedSizeRotation_WaitsBeforeRetrying, "FailedSizeRotation_WaitsBeforeRetrying");
     RegisterTest(&TTest_ASWLog_FileLog::Test_FileStream_FlushWorksAfterFailedWrite, "FileStream_FlushWorksAfterFailedWrite");
+    RegisterTest(&TTest_ASWLog_FileLog::Test_FileStream_InsertionIntoAClosedStreamFails, "FileStream_InsertionIntoAClosedStreamFails");
+    RegisterTest(&TTest_ASWLog_FileLog::Test_FileStream_InsertionWritesAndCountsTheSize, "FileStream_InsertionWritesAndCountsTheSize");
     RegisterTest(&TTest_ASWLog_FileLog::Test_FlushImmediatelyAtLevel_FlushesEntriesAtOrAboveTheLevel, "FlushImmediatelyAtLevel_FlushesEntriesAtOrAboveTheLevel");
     RegisterTest(&TTest_ASWLog_FileLog::Test_FlushImmediatelyAtLevel_OffLeavesFlushingToFlushMode, "FlushImmediatelyAtLevel_OffLeavesFlushingToFlushMode");
     RegisterTest(&TTest_ASWLog_FileLog::Test_Flush_WritesBufferedManualModeEntries, "Flush_WritesBufferedManualModeEntries");
@@ -1430,6 +1432,45 @@ void TTest_ASWLog_FileLog::Test_FileStream_FlushWorksAfterFailedWrite()
     CheckEquals(std::string("buffered"), contents, "Flush should write the buffered data to the file");
 }
 //---------------------------------------------------------------------------
+void TTest_ASWLog_FileLog::Test_FileStream_InsertionIntoAClosedStreamFails()
+{
+    // Arrange
+    ASWLog::TASWFileStream textStream;
+    ASWLog::TASWFileStream characterStream;
+
+    // Act: a text goes through xsputn(), a single character through overflow()
+    textStream << "text";
+    characterStream.put('x');
+
+    // Assert
+    CheckTrue(textStream.bad(), "Inserting a text into a stream that isn't open should fail");
+    CheckTrue(characterStream.bad(), "Inserting a character into a stream that isn't open should fail");
+    CheckEquals(0, textStream.GetSize() + characterStream.GetSize(), "Nothing should be counted");
+}
+//---------------------------------------------------------------------------
+void TTest_ASWLog_FileLog::Test_FileStream_InsertionWritesAndCountsTheSize()
+{
+    // Arrange: a file that already holds 4 bytes
+    const auto file = TestTempDir / "insertion.log";
+    std::ofstream(file, std::ios::binary) << "old\n";
+    ASWLog::TASWFileStream stream;
+    const bool opened = stream.Open(file);
+
+    // Act: a text goes through xsputn(), a single character through overflow()
+    stream << "count=" << 42;
+    stream.put('\n');
+    const bool flushed = stream.Flush();
+    const auto size = stream.GetSize();
+    stream.Close();
+
+    // Assert
+    CheckTrue(opened, "Open should succeed");
+    CheckFalse(stream.fail(), "The insertions should succeed");
+    CheckTrue(flushed, "Flush should succeed");
+    CheckEquals(std::string("old\ncount=42\n"), ReadFileText(file), "operator<< and put() should append to the file");
+    CheckEquals(13, size, "GetSize() should count the file's bytes and every inserted one");
+}
+//---------------------------------------------------------------------------
 void TTest_ASWLog_FileLog::Test_FlushImmediatelyAtLevel_FlushesEntriesAtOrAboveTheLevel()
 {
     // Arrange: FlushMode::Manual keeps the entries below the level in the file's buffer
diff --git a/tests/tests/Test_ASWLog_FileLog.h b/tests/tests/Test_ASWLog_FileLog.h
index 1cc715c..dcd9dde 100644
--- a/tests/tests/Test_ASWLog_FileLog.h
+++ b/tests/tests/Test_ASWLog_FileLog.h
@@ -65,6 +65,8 @@ class TTest_ASWLog_FileLog : public TTestGroupBase
     void Test_FailedReopen_ZeroResetDelayRetriesOnNextWrite();
     void Test_FailedSizeRotation_WaitsBeforeRetrying();
     void Test_FileStream_FlushWorksAfterFailedWrite();
+    void Test_FileStream_InsertionIntoAClosedStreamFails();
+    void Test_FileStream_InsertionWritesAndCountsTheSize();
     void Test_FlushImmediatelyAtLevel_FlushesEntriesAtOrAboveTheLevel();
     void Test_FlushImmediatelyAtLevel_OffLeavesFlushingToFlushMode();
     void Test_Flush_WritesBufferedManualModeEntries();

From 17c92721395126575a83db8036274013f3d6cf75 Mon Sep 17 00:00:00 2001
From: Anthony West <anthony.s.west@gmail.com>
Date: Sat, 10 Oct 2026 23:39:09 -0700
Subject: [PATCH 09/12] Remove GetApplicationInfoString()

---
 ASWLog/ASWLog_Utils.cpp | 7 -------
 ASWLog/ASWLog_Utils.h   | 1 -
 CHANGELOG.md            | 8 ++++++++
 3 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/ASWLog/ASWLog_Utils.cpp b/ASWLog/ASWLog_Utils.cpp
index 47145c4..9f9ae6a 100644
--- a/ASWLog/ASWLog_Utils.cpp
+++ b/ASWLog/ASWLog_Utils.cpp
@@ -117,13 +117,6 @@ std::string GenerateLogFileName(std::string_view prefix, std::string_view custom
     return name;
 }
 
-//---------------------------------------------------------------------------
-std::string GetApplicationInfoString()
-{
-    auto exePath = GetExecutablePath();
-    return std::format("application_exe='{}', command_line='{}'", PathToUTF8String(exePath), GetCommandLineString());
-}
-
 //---------------------------------------------------------------------------
 std::string GetCommandLineString()
 {
diff --git a/ASWLog/ASWLog_Utils.h b/ASWLog/ASWLog_Utils.h
index c30d996..1a7dc25 100644
--- a/ASWLog/ASWLog_Utils.h
+++ b/ASWLog/ASWLog_Utils.h
@@ -76,7 +76,6 @@ struct TSystemMemoryUsage
 */
 [[nodiscard]] std::string GenerateLogFileName(std::string_view prefix, std::string_view customPostfix);
 
-[[nodiscard]] std::string GetApplicationInfoString();
 [[nodiscard]] std::string GetCommandLineString();
 
 // The operating system's id for the current process, as shown by Task Manager, ps, and debuggers.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f58d27a..9d63729 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -295,6 +295,14 @@ see [0.26.1](#0261---2026-09-17) for the initial versioned baseline.
   custom formatter. A time before 1970 is now written as the day and
   millisecond it falls in, instead of a malformed time.
 
+### Removed
+
+- `GetApplicationInfoString()` (from `ASWLog_Utils.h`). It was an older form
+  of the startup "App:" line and nothing in ASWLog used it. Breaking for code
+  that called it: build the text from `GetExecutablePath()` (with
+  `PathToUTF8String()`) and `GetCommandLineString()`, which it combined as
+  `application_exe='<path>', command_line='<command line>'`.
+
 ## [0.75.0] - 2026-10-06
 
 ### Added

From c5ce37d05531e03bef5c01d58766d96c82c51dc4 Mon Sep 17 00:00:00 2001
From: Anthony West <anthony.s.west@gmail.com>
Date: Sat, 10 Oct 2026 23:47:35 -0700
Subject: [PATCH 10/12] Test TASWMultiLog's Open() and failing loggers, and
 command line startup option

---
 tests/tests/Test_ASWLog_MultiLog.cpp    | 89 +++++++++++++++++++++++--
 tests/tests/Test_ASWLog_MultiLog.h      |  3 +
 tests/tests/Test_ASWLog_TextLogBase.cpp | 29 ++++++++
 tests/tests/Test_ASWLog_TextLogBase.h   |  1 +
 4 files changed, 118 insertions(+), 4 deletions(-)

diff --git a/tests/tests/Test_ASWLog_MultiLog.cpp b/tests/tests/Test_ASWLog_MultiLog.cpp
index e339dcb..b4b7d7c 100644
--- a/tests/tests/Test_ASWLog_MultiLog.cpp
+++ b/tests/tests/Test_ASWLog_MultiLog.cpp
@@ -103,8 +103,14 @@ class TRecordingLogger final : public ASWLog::TASWLogBase
 public:
     std::vector<std::string> Calls;
     std::vector<ASWLog::TASWLogRecord> Records; // Every field but Message
+    bool CloseResult = true; // Returned by Close()
     bool FlushResult = true; // Returned by Flush()
+    bool InitializeResult = true; // Returned by Initialize()
+    bool IsOpenResult = true; // Returned by IsOpen()
+    bool OpenResult = true; // Returned by Open()
     bool ReconfigureResult = true; // Returned by Reconfigure()
+    int CloseCount = 0; // How often Close() was called
+    int OpenCount = 0; // How often Open() was called
     bool WasInitialized = false; // Initialize() was called
     bool InitializeHadBeforeWrite = false; // The config passed to Initialize() had an OnBeforeWrite hook
 
@@ -112,7 +118,7 @@ class TRecordingLogger final : public ASWLog::TASWLogBase
     {
         WasInitialized = true;
         InitializeHadBeforeWrite = config.OnBeforeWrite != nullptr;
-        return true;
+        return InitializeResult;
     }
 
     bool Reconfigure(const ASWLog::TASWLogConfig& config) noexcept override
@@ -124,12 +130,14 @@ class TRecordingLogger final : public ASWLog::TASWLogBase
 
     bool Open() noexcept override
     {
-        return true;
+        ++OpenCount;
+        return OpenResult;
     }
 
     bool Close() noexcept override
     {
-        return true;
+        ++CloseCount;
+        return CloseResult;
     }
 
     bool Flush() noexcept override
@@ -140,7 +148,7 @@ class TRecordingLogger final : public ASWLog::TASWLogBase
 
     bool IsOpen() const noexcept override
     {
-        return true;
+        return IsOpenResult;
     }
 };
 
@@ -275,6 +283,7 @@ TTest_ASWLog_MultiLog::TTest_ASWLog_MultiLog()
     RegisterTest(&TTest_ASWLog_MultiLog::Test_Backtrace_EachLoggerKeepsItsOwn, "Backtrace_EachLoggerKeepsItsOwn");
     RegisterTest(&TTest_ASWLog_MultiLog::Test_Backtrace_IsNotKeptByTheMultiLog, "Backtrace_IsNotKeptByTheMultiLog");
     RegisterTest(&TTest_ASWLog_MultiLog::Test_Close_AllowsInitializeAgain, "Close_AllowsInitializeAgain");
+    RegisterTest(&TTest_ASWLog_MultiLog::Test_Close_ReachesEverySinkEvenAfterAFailure, "Close_ReachesEverySinkEvenAfterAFailure");
     RegisterTest(&TTest_ASWLog_MultiLog::Test_Contains_ReflectsRegistrationState, "Contains_ReflectsRegistrationState");
     RegisterTest(&TTest_ASWLog_MultiLog::Test_DumpBacktrace_ReachesEverySinkUnlessDisabled, "DumpBacktrace_ReachesEverySinkUnlessDisabled");
     RegisterTest(&TTest_ASWLog_MultiLog::Test_Flush_ReachesEverySinkEvenAfterAFailure, "Flush_ReachesEverySinkEvenAfterAFailure");
@@ -284,6 +293,7 @@ TTest_ASWLog_MultiLog::TTest_ASWLog_MultiLog()
     RegisterTest(&TTest_ASWLog_MultiLog::Test_GetLoggerCount_ReflectsAddAndRemove, "GetLoggerCount_ReflectsAddAndRemove");
     RegisterTest(&TTest_ASWLog_MultiLog::Test_GetLoggers_ReturnsSnapshotOfRegisteredSinks, "GetLoggers_ReturnsSnapshotOfRegisteredSinks");
     RegisterTest(&TTest_ASWLog_MultiLog::Test_Initialize_ConcurrentCallsSucceedOnce, "Initialize_ConcurrentCallsSucceedOnce");
+    RegisterTest(&TTest_ASWLog_MultiLog::Test_Initialize_FailsOnlyForASinkThatIsNotOpen, "Initialize_FailsOnlyForASinkThatIsNotOpen");
     RegisterTest(&TTest_ASWLog_MultiLog::Test_IsOpen_RequiresAllSinksOpen, "IsOpen_RequiresAllSinksOpen");
     RegisterTest(&TTest_ASWLog_MultiLog::Test_Log_AtLevelOffIsNotFannedOut, "Log_AtLevelOffIsNotFannedOut");
     RegisterTest(&TTest_ASWLog_MultiLog::Test_Log_FansOutToAllRegisteredSinks, "Log_FansOutToAllRegisteredSinks");
@@ -291,6 +301,7 @@ TTest_ASWLog_MultiLog::TTest_ASWLog_MultiLog()
     RegisterTest(&TTest_ASWLog_MultiLog::Test_LogFmt_FormatsOnceForAllSinks, "LogFmt_FormatsOnceForAllSinks");
     RegisterTest(&TTest_ASWLog_MultiLog::Test_LogForce_BypassesCompositeGate, "LogForce_BypassesCompositeGate");
     RegisterTest(&TTest_ASWLog_MultiLog::Test_OnBeforeWrite_RunsOnceBeforeTheFanOut, "OnBeforeWrite_RunsOnceBeforeTheFanOut");
+    RegisterTest(&TTest_ASWLog_MultiLog::Test_Open_ReachesEverySinkEvenAfterAFailure, "Open_ReachesEverySinkEvenAfterAFailure");
     RegisterTest(&TTest_ASWLog_MultiLog::Test_Reconfigure_PassesConfigToEverySink, "Reconfigure_PassesConfigToEverySink");
     RegisterTest(&TTest_ASWLog_MultiLog::Test_RemoveAllLoggers_ClearsRegistrationAndReturnsCount, "RemoveAllLoggers_ClearsRegistrationAndReturnsCount");
     RegisterTest(&TTest_ASWLog_MultiLog::Test_RemoveLogger_StopsReceivingEntries, "RemoveLogger_StopsReceivingEntries");
@@ -450,6 +461,29 @@ void TTest_ASWLog_MultiLog::Test_Close_AllowsInitializeAgain()
     CheckContains(ReadFileText(fileA), "after_reinitialize", "Initialize after Close should initialize the sinks again");
 }
 //---------------------------------------------------------------------------
+void TTest_ASWLog_MultiLog::Test_Close_ReachesEverySinkEvenAfterAFailure()
+{
+    // Arrange: the first sink's close fails
+    TRecordingLogger failingSink;
+    failingSink.CloseResult = false;
+    TRecordingLogger sink;
+
+    ASWLog::TASWMultiLog multiLog;
+    multiLog.AddLogger(failingSink);
+    multiLog.AddLogger(sink);
+
+    // Act
+    const bool closedWithFailure = multiLog.Close();
+    failingSink.CloseResult = true;
+    const bool closed = multiLog.Close();
+
+    // Assert
+    CheckFalse(closedWithFailure, "Close() should return false if any sink's close fails");
+    CheckTrue(closed, "Close() should return true once every sink's close succeeds");
+    CheckEquals(2, failingSink.CloseCount, "Each Close() should reach the failing sink");
+    CheckEquals(2, sink.CloseCount, "A sink's failed close should not stop the other sinks from being closed");
+}
+//---------------------------------------------------------------------------
 void TTest_ASWLog_MultiLog::Test_Contains_ReflectsRegistrationState()
 {
     // Arrange
@@ -695,6 +729,30 @@ void TTest_ASWLog_MultiLog::Test_Initialize_ConcurrentCallsSucceedOnce()
     CheckEquals(roundCount, roundsWithOneSuccess, "Exactly one of the concurrent Initialize calls should succeed");
 }
 //---------------------------------------------------------------------------
+void TTest_ASWLog_MultiLog::Test_Initialize_FailsOnlyForASinkThatIsNotOpen()
+{
+    // Arrange: the first sink's Initialize() fails, as it does for a logger that is already initialized
+    TRecordingLogger failingSink;
+    failingSink.InitializeResult = false;
+    failingSink.IsOpenResult = false;
+    TRecordingLogger sink;
+
+    ASWLog::TASWMultiLog multiLog;
+    multiLog.AddLogger(failingSink);
+    multiLog.AddLogger(sink);
+
+    // Act: first the sink isn't open, then it is (initialized earlier on its own)
+    const bool initializedWithClosedSink = multiLog.Initialize(ASWLog::TASWLogConfig());
+    multiLog.Close();
+    failingSink.IsOpenResult = true;
+    const bool initializedWithOpenSink = multiLog.Initialize(ASWLog::TASWLogConfig());
+
+    // Assert
+    CheckFalse(initializedWithClosedSink, "Initialize() should return false if a sink fails and isn't open");
+    CheckTrue(initializedWithOpenSink, "A sink that fails Initialize() but is open (initialized already) should count as ready");
+    CheckTrue(sink.WasInitialized, "A sink's failed Initialize() should not stop the other sinks from being initialized");
+}
+//---------------------------------------------------------------------------
 void TTest_ASWLog_MultiLog::Test_IsOpen_RequiresAllSinksOpen()
 {
     // Arrange
@@ -898,6 +956,29 @@ void TTest_ASWLog_MultiLog::Test_OnBeforeWrite_RunsOnceBeforeTheFanOut()
         "A sink's own hook should run after the multi-log's, until the multi-log's Reconfigure() replaces its config");
 }
 //---------------------------------------------------------------------------
+void TTest_ASWLog_MultiLog::Test_Open_ReachesEverySinkEvenAfterAFailure()
+{
+    // Arrange: the first sink's open fails
+    TRecordingLogger failingSink;
+    failingSink.OpenResult = false;
+    TRecordingLogger sink;
+
+    ASWLog::TASWMultiLog multiLog;
+    multiLog.AddLogger(failingSink);
+    multiLog.AddLogger(sink);
+
+    // Act
+    const bool openedWithFailure = multiLog.Open();
+    failingSink.OpenResult = true;
+    const bool opened = multiLog.Open();
+
+    // Assert
+    CheckFalse(openedWithFailure, "Open() should return false if any sink's open fails");
+    CheckTrue(opened, "Open() should return true once every sink's open succeeds");
+    CheckEquals(2, failingSink.OpenCount, "Each Open() should reach the failing sink");
+    CheckEquals(2, sink.OpenCount, "A sink's failed open should not stop the other sinks from being opened");
+}
+//---------------------------------------------------------------------------
 void TTest_ASWLog_MultiLog::Test_Reconfigure_PassesConfigToEverySink()
 {
     // Arrange: the first sink's Reconfigure() fails
diff --git a/tests/tests/Test_ASWLog_MultiLog.h b/tests/tests/Test_ASWLog_MultiLog.h
index 1330f30..f4311a6 100644
--- a/tests/tests/Test_ASWLog_MultiLog.h
+++ b/tests/tests/Test_ASWLog_MultiLog.h
@@ -41,6 +41,7 @@ class TTest_ASWLog_MultiLog : public TTestGroupBase
     void Test_Backtrace_EachLoggerKeepsItsOwn();
     void Test_Backtrace_IsNotKeptByTheMultiLog();
     void Test_Close_AllowsInitializeAgain();
+    void Test_Close_ReachesEverySinkEvenAfterAFailure();
     void Test_Contains_ReflectsRegistrationState();
     void Test_DumpBacktrace_ReachesEverySinkUnlessDisabled();
     void Test_Flush_ReachesEverySinkEvenAfterAFailure();
@@ -50,6 +51,7 @@ class TTest_ASWLog_MultiLog : public TTestGroupBase
     void Test_GetLoggerCount_ReflectsAddAndRemove();
     void Test_GetLoggers_ReturnsSnapshotOfRegisteredSinks();
     void Test_Initialize_ConcurrentCallsSucceedOnce();
+    void Test_Initialize_FailsOnlyForASinkThatIsNotOpen();
     void Test_IsOpen_RequiresAllSinksOpen();
     void Test_Log_AtLevelOffIsNotFannedOut();
     void Test_Log_FansOutToAllRegisteredSinks();
@@ -57,6 +59,7 @@ class TTest_ASWLog_MultiLog : public TTestGroupBase
     void Test_LogFmt_FormatsOnceForAllSinks();
     void Test_LogForce_BypassesCompositeGate();
     void Test_OnBeforeWrite_RunsOnceBeforeTheFanOut();
+    void Test_Open_ReachesEverySinkEvenAfterAFailure();
     void Test_Reconfigure_PassesConfigToEverySink();
     void Test_RemoveAllLoggers_ClearsRegistrationAndReturnsCount();
     void Test_RemoveLogger_StopsReceivingEntries();
diff --git a/tests/tests/Test_ASWLog_TextLogBase.cpp b/tests/tests/Test_ASWLog_TextLogBase.cpp
index 4c16f55..cbe15a7 100644
--- a/tests/tests/Test_ASWLog_TextLogBase.cpp
+++ b/tests/tests/Test_ASWLog_TextLogBase.cpp
@@ -402,6 +402,7 @@ bool WaitUntil(const std::function<bool()>& condition)
 TTest_ASWLog_TextLogBase::TTest_ASWLog_TextLogBase()
     : inherited("ASWLog_TextLogBase_Tests")
 {
+    RegisterTest(&TTest_ASWLog_TextLogBase::Test_ApplicationInfo_WritesTheCommandLineWhenAsked, "ApplicationInfo_WritesTheCommandLineWhenAsked");
     RegisterTest(&TTest_ASWLog_TextLogBase::Test_ApplicationInfo_WritesTheConfiguredVersion, "ApplicationInfo_WritesTheConfiguredVersion");
     RegisterTest(&TTest_ASWLog_TextLogBase::Test_ApplicationInfo_WritesTheExecutablesFileVersionByDefault, "ApplicationInfo_WritesTheExecutablesFileVersionByDefault");
     RegisterTest(&TTest_ASWLog_TextLogBase::Test_Async_BacktraceIsTakenWhenTheTriggerIsLogged, "Async_BacktraceIsTakenWhenTheTriggerIsLogged");
@@ -477,6 +478,34 @@ void TTest_ASWLog_TextLogBase::TearDown_Test(ITestCase& testCase)
 
 // /////// Begin tests after this line ///////////////////////
 
+//---------------------------------------------------------------------------
+void TTest_ASWLog_TextLogBase::Test_ApplicationInfo_WritesTheCommandLineWhenAsked()
+{
+    // Arrange
+    TMemoryOutput defaultOutput;
+    TMemoryTextLog defaultLog(defaultOutput);
+    TMemoryOutput commandLineOutput;
+    TMemoryTextLog commandLineLog(commandLineOutput);
+    auto config = MakeQuietConfig();
+    config.Startup.WriteApplicationInfo = true;
+    auto commandLineConfig = config;
+    commandLineConfig.Startup.WriteCommandLine = true;
+
+    // Act
+    const bool defaultInitialized = defaultLog.Initialize(config);
+    const bool commandLineInitialized = commandLineLog.Initialize(commandLineConfig);
+
+    // Assert
+    CheckTrue(defaultInitialized && commandLineInitialized, "Initialize should succeed");
+    CheckEquals(1, defaultOutput.Lines.size(), "Initialize should write the App line");
+    CheckEquals(1, commandLineOutput.Lines.size(), "Initialize should write the App line");
+    if (defaultOutput.Lines.size() == 1 && commandLineOutput.Lines.size() == 1)
+    {
+        CheckNotContains(defaultOutput.Lines[0], "command_line=", "By default the App line should leave out the command line");
+        CheckEndsWith(commandLineOutput.Lines[0], std::format(", command_line='{}'\n", ASWLog::GetCommandLineString()),
+            "Startup.WriteCommandLine should add the command line at the end of the App line");
+    }
+}
 //---------------------------------------------------------------------------
 void TTest_ASWLog_TextLogBase::Test_ApplicationInfo_WritesTheConfiguredVersion()
 {
diff --git a/tests/tests/Test_ASWLog_TextLogBase.h b/tests/tests/Test_ASWLog_TextLogBase.h
index d99173c..9bd407c 100644
--- a/tests/tests/Test_ASWLog_TextLogBase.h
+++ b/tests/tests/Test_ASWLog_TextLogBase.h
@@ -36,6 +36,7 @@ class TTest_ASWLog_TextLogBase : public TTestGroupBase
     typedef TTestGroupBase inherited;
 
 private: // Test methods
+    void Test_ApplicationInfo_WritesTheCommandLineWhenAsked();
     void Test_ApplicationInfo_WritesTheConfiguredVersion();
     void Test_ApplicationInfo_WritesTheExecutablesFileVersionByDefault();
     void Test_Async_BacktraceIsTakenWhenTheTriggerIsLogged();

From cc735690902734afe966c8ff5df3ac41a039d537 Mon Sep 17 00:00:00 2001
From: Anthony West <anthony.s.west@gmail.com>
Date: Sun, 11 Oct 2026 00:06:32 -0700
Subject: [PATCH 11/12] Test the remaining small edge cases

---
 tests/tests/Test_ASWLog_FileLog.cpp   | 42 +++++++++++++++++++++++++++
 tests/tests/Test_ASWLog_FileLog.h     |  1 +
 tests/tests/Test_ASWLog_Formatter.cpp | 19 ++++++++++++
 tests/tests/Test_ASWLog_Formatter.h   |  1 +
 tests/tests/Test_ASWLog_Types.cpp     |  1 +
 tests/tests/Test_ASWLog_Utils.cpp     | 24 +++++++++++++++
 tests/tests/Test_ASWLog_Utils.h       |  1 +
 7 files changed, 89 insertions(+)

diff --git a/tests/tests/Test_ASWLog_FileLog.cpp b/tests/tests/Test_ASWLog_FileLog.cpp
index 4bf6b53..1fbe523 100644
--- a/tests/tests/Test_ASWLog_FileLog.cpp
+++ b/tests/tests/Test_ASWLog_FileLog.cpp
@@ -364,6 +364,7 @@ bool WaitUntil(const std::function<bool()>& condition)
 TTest_ASWLog_FileLog::TTest_ASWLog_FileLog()
     : inherited("ASWLog_FileLog_Tests")
 {
+    RegisterTest(&TTest_ASWLog_FileLog::Test_Async_DropsAnEntryWhileTheFileCantBeOpened, "Async_DropsAnEntryWhileTheFileCantBeOpened");
     RegisterTest(&TTest_ASWLog_FileLog::Test_Async_EntryAtWaitAtLevelIsInTheFileWhenTheCallReturns, "Async_EntryAtWaitAtLevelIsInTheFileWhenTheCallReturns");
     RegisterTest(&TTest_ASWLog_FileLog::Test_Async_EveryWriteFlushesEachBatch, "Async_EveryWriteFlushesEachBatch");
     RegisterTest(&TTest_ASWLog_FileLog::Test_Async_PeriodicFlushesOnTheSameThread, "Async_PeriodicFlushesOnTheSameThread");
@@ -491,6 +492,47 @@ void TTest_ASWLog_FileLog::TearDown_Test(ITestCase& testCase)
 
 // /////// Begin tests after this line ///////////////////////
 
+//---------------------------------------------------------------------------
+void TTest_ASWLog_FileLog::Test_Async_DropsAnEntryWhileTheFileCantBeOpened()
+{
+    // Arrange: a "folder" that is a file can't hold the log, on any OS and for any user
+    using namespace std::chrono_literals;
+    const auto logFile = TestTempDir / "async_dropped.log";
+    const auto notAFolder = TestTempDir / "async_not_a_folder";
+    std::ofstream(notAFolder) << "file";
+
+    // OnLogEntry runs on the logger's thread, which Close() joins before the checks read this
+    std::vector<std::string> callbackMessages;
+    auto config = MakeRotationTestConfig(logFile);
+    config.Async.Enabled = true;
+    config.File.CircuitBreakerResetDelay = 1h; // The logger's thread doesn't try the file again for the entry
+    config.OnError = IgnoreError;
+    config.OnLogEntryMinimumLevel = ASWLog::Level::Info;
+    config.OnLogEntry = [&callbackMessages](const ASWLog::TASWLogRecord& record, std::string_view /*formattedLine*/) {
+            callbackMessages.emplace_back(record.Message);
+        };
+
+    auto unopenableConfig = config;
+    unopenableConfig.File.FilePath = notAFolder / "unopenable.log";
+
+    ASWLog::TASWFileLog logger;
+
+    // Act: Reconfigure() first writes what is queued, so each entry meets the file it was logged for
+    const bool initialized = logger.Initialize(config);
+    logger.LogInfo("before");
+    const bool reconfiguredToUnopenable = logger.Reconfigure(unopenableConfig);
+    logger.LogInfo("dropped");
+    const bool reconfiguredBack = logger.Reconfigure(config);
+    logger.LogInfo("after");
+    logger.Close();
+
+    // Assert
+    const std::vector<std::string> expectedMessages{ "before", "after" };
+    CheckTrue(initialized && reconfiguredBack, "Initialize and the Reconfigure() back should succeed");
+    CheckFalse(reconfiguredToUnopenable, "Reconfigure() to an unopenable file should fail");
+    CheckEquals(std::string(": before\n: after\n"), ReadFileText(logFile), "The queued entry should be dropped while the file can't be opened");
+    CheckTrue(callbackMessages == expectedMessages, "OnLogEntry should be called only for the entries written");
+}
 //---------------------------------------------------------------------------
 void TTest_ASWLog_FileLog::Test_Async_EntryAtWaitAtLevelIsInTheFileWhenTheCallReturns()
 {
diff --git a/tests/tests/Test_ASWLog_FileLog.h b/tests/tests/Test_ASWLog_FileLog.h
index dcd9dde..2bb9021 100644
--- a/tests/tests/Test_ASWLog_FileLog.h
+++ b/tests/tests/Test_ASWLog_FileLog.h
@@ -36,6 +36,7 @@ class TTest_ASWLog_FileLog : public TTestGroupBase
     typedef TTestGroupBase inherited;
 
 private: // Test methods
+    void Test_Async_DropsAnEntryWhileTheFileCantBeOpened();
     void Test_Async_EntryAtWaitAtLevelIsInTheFileWhenTheCallReturns();
     void Test_Async_EveryWriteFlushesEachBatch();
     void Test_Async_PeriodicFlushesOnTheSameThread();
diff --git a/tests/tests/Test_ASWLog_Formatter.cpp b/tests/tests/Test_ASWLog_Formatter.cpp
index dd3f3a7..2d06343 100644
--- a/tests/tests/Test_ASWLog_Formatter.cpp
+++ b/tests/tests/Test_ASWLog_Formatter.cpp
@@ -190,6 +190,7 @@ TTest_ASWLog_Formatter::TTest_ASWLog_Formatter()
     RegisterTest(&TTest_ASWLog_Formatter::Test_Formatter_SharedByTwoLoggers, "Formatter_SharedByTwoLoggers");
     RegisterTest(&TTest_ASWLog_Formatter::Test_JSONFormatter_DefaultFields, "JSONFormatter_DefaultFields");
     RegisterTest(&TTest_ASWLog_Formatter::Test_JSONFormatter_EachShowOption, "JSONFormatter_EachShowOption");
+    RegisterTest(&TTest_ASWLog_Formatter::Test_JSONFormatter_EmptyScopeLeavesOutTheFields, "JSONFormatter_EmptyScopeLeavesOutTheFields");
     RegisterTest(&TTest_ASWLog_Formatter::Test_JSONFormatter_EntryFields, "JSONFormatter_EntryFields");
     RegisterTest(&TTest_ASWLog_Formatter::Test_JSONFormatter_EscapesTheTexts, "JSONFormatter_EscapesTheTexts");
     RegisterTest(&TTest_ASWLog_Formatter::Test_JSONFormatter_FileLoggerWritesJSONLines, "JSONFormatter_FileLoggerWritesJSONLines");
@@ -555,6 +556,24 @@ void TTest_ASWLog_Formatter::Test_JSONFormatter_EachShowOption()
     CheckTrue(IsJSONObjectLine(allLine) && IsJSONObjectLine(memoryLine) && IsJSONObjectLine(noFieldsLine), "Each line should be one JSON object");
 }
 //---------------------------------------------------------------------------
+void TTest_ASWLog_Formatter::Test_JSONFormatter_EmptyScopeLeavesOutTheFields()
+{
+    // Arrange: an entry in a scope without fields
+    const auto config = MakeConfigWithoutFields("unused.log");
+    const ASWLog::TASWLogScope scope{};
+
+    auto record = MakeRecord("msg");
+    record.Scope = &scope;
+
+    const ASWLog::TASWJSONFormatter formatter;
+
+    // Act
+    const auto line = formatter.Format(record, config);
+
+    // Assert
+    CheckEquals(std::string(R"({"message":"msg"})"), line, "A scope without fields should add no \"fields\" object");
+}
+//---------------------------------------------------------------------------
 void TTest_ASWLog_Formatter::Test_JSONFormatter_EntryFields()
 {
     // Arrange: a scope and the entry's own fields, which replace the scope's n; a value of each kind, and the doubles
diff --git a/tests/tests/Test_ASWLog_Formatter.h b/tests/tests/Test_ASWLog_Formatter.h
index dcd24f4..5d5c19e 100644
--- a/tests/tests/Test_ASWLog_Formatter.h
+++ b/tests/tests/Test_ASWLog_Formatter.h
@@ -49,6 +49,7 @@ class TTest_ASWLog_Formatter : public TTestGroupBase
     void Test_Formatter_SharedByTwoLoggers();
     void Test_JSONFormatter_DefaultFields();
     void Test_JSONFormatter_EachShowOption();
+    void Test_JSONFormatter_EmptyScopeLeavesOutTheFields();
     void Test_JSONFormatter_EntryFields();
     void Test_JSONFormatter_EscapesTheTexts();
     void Test_JSONFormatter_FileLoggerWritesJSONLines();
diff --git a/tests/tests/Test_ASWLog_Types.cpp b/tests/tests/Test_ASWLog_Types.cpp
index d3950fd..a4bb888 100644
--- a/tests/tests/Test_ASWLog_Types.cpp
+++ b/tests/tests/Test_ASWLog_Types.cpp
@@ -311,6 +311,7 @@ void TTest_ASWLog_Types::Test_LineEnding_FromString()
     CheckEquals(ASWLog::LineEnding::LF, *lf_lower, "lf should map to LF");
     CheckEquals(ASWLog::LineEnding::CRLF, *crlf, "CRLF should map to CRLF");
     CheckEquals(ASWLog::LineEnding::CRLF, *crlfAlias, "WINDOWS should map to CRLF");
+    CheckFalse(ASWLog::LineEnding_FromString("CR").has_value(), "An unknown name should not parse");
 }
 //---------------------------------------------------------------------------
 void TTest_ASWLog_Types::Test_LineEnding_ToString()
diff --git a/tests/tests/Test_ASWLog_Utils.cpp b/tests/tests/Test_ASWLog_Utils.cpp
index 5f03940..dc1229a 100644
--- a/tests/tests/Test_ASWLog_Utils.cpp
+++ b/tests/tests/Test_ASWLog_Utils.cpp
@@ -44,6 +44,8 @@ limitations under the License.
 
 #if defined(_WIN32)
 #include <windows.h>
+#undef min
+#undef max
 #endif
 //---------------------------------------------------------------------------
 #include "ASWUnitTests_Registry.h"
@@ -136,6 +138,7 @@ TTest_ASWLog_Utils::TTest_ASWLog_Utils()
     RegisterTest(&TTest_ASWLog_Utils::Test_Time_WriteISO8601_CalendarEdges, "Time_WriteISO8601_CalendarEdges");
     RegisterTest(&TTest_ASWLog_Utils::Test_Time_WriteISO8601_LocalTimeWithEachPrecision, "Time_WriteISO8601_LocalTimeWithEachPrecision");
     RegisterTest(&TTest_ASWLog_Utils::Test_Time_WriteISO8601_UTCWithEachPrecision, "Time_WriteISO8601_UTCWithEachPrecision");
+    RegisterTest(&TTest_ASWLog_Utils::Test_Time_WriteISO8601_YearPast9999IsWrittenInFull, "Time_WriteISO8601_YearPast9999IsWrittenInFull");
     RegisterTest(&TTest_ASWLog_Utils::Test_TrimSpaces_RemovesOuterSpacesAndTabs, "TrimSpaces_RemovesOuterSpacesAndTabs");
 }
 //---------------------------------------------------------------------------
@@ -938,6 +941,27 @@ void TTest_ASWLog_Utils::Test_Time_WriteISO8601_UTCWithEachPrecision()
     }
 }
 //---------------------------------------------------------------------------
+void TTest_ASWLog_Utils::Test_Time_WriteISO8601_YearPast9999IsWrittenInFull()
+{
+    // Arrange: libstdc++'s system_clock counts nanoseconds, which end in 2262; libc++'s microseconds and MSVC's 100 ns
+    // ticks reach far past 9999. Compared in days, since converting the year to the clock's ticks could overflow.
+    using namespace std::chrono;
+    using namespace std::chrono_literals;
+    const sys_days firstDay{ 10000y / 1 / 1 };
+    if (floor<days>(system_clock::time_point::max()) <= firstDay)
+        Skip("This standard library's system_clock ends before the year 10000");
+
+    // Cast first: libc++ on Windows keeps minutes in a 32-bit long, so firstDay + 2min would overflow
+    const auto time = time_point_cast<system_clock::duration>(firstDay) + 1h + 2min + 3s + 4ms;
+
+    // Act
+    char buffer[ASWLog::Time::ISO8601BufferSize];
+    const auto size = ASWLog::Time::WriteISO8601(buffer, time);
+
+    // Assert
+    CheckEquals(std::string("10000-01-01T01:02:03.004Z"), std::string(buffer, size), "A year past 9999 should be written in full");
+}
+//---------------------------------------------------------------------------
 void TTest_ASWLog_Utils::Test_TrimSpaces_RemovesOuterSpacesAndTabs()
 {
     // Arrange / Act / Assert
diff --git a/tests/tests/Test_ASWLog_Utils.h b/tests/tests/Test_ASWLog_Utils.h
index 0e2af6f..0b9b2ad 100644
--- a/tests/tests/Test_ASWLog_Utils.h
+++ b/tests/tests/Test_ASWLog_Utils.h
@@ -67,6 +67,7 @@ class TTest_ASWLog_Utils : public TTestGroupBase
     void Test_Time_WriteISO8601_CalendarEdges();
     void Test_Time_WriteISO8601_LocalTimeWithEachPrecision();
     void Test_Time_WriteISO8601_UTCWithEachPrecision();
+    void Test_Time_WriteISO8601_YearPast9999IsWrittenInFull();
     void Test_TrimSpaces_RemovesOuterSpacesAndTabs();
 
 public:

From f17a469a1166fb9d0a1c5784dc8667770c27c933 Mon Sep 17 00:00:00 2001
From: Anthony West <anthony.s.west@gmail.com>
Date: Sun, 11 Oct 2026 00:18:01 -0700
Subject: [PATCH 12/12] Add a coverage job to CI

---
 .github/workflows/ci.yml | 54 ++++++++++++++++++++++++++++++++++++++++
 AGENTS.md                |  2 +-
 README.md                |  4 +++
 3 files changed, 59 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 44a97dd..d59c7d9 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -202,3 +202,57 @@ jobs:
             cmake --build build-package --config "$config"
             ctest --test-dir build-package -C "$config" --output-on-failure
           done
+
+  coverage:
+    # Which lines of the library (ASWLog/) the tests run, on Linux: a table on this job's summary page, and an HTML
+    # report (each source line marked) as an artifact. Informational: continue-on-error keeps it from failing the run;
+    # the jobs above are the ones that must pass.
+    name: Linux (GCC, coverage)
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    continue-on-error: true
+    env:
+      CMAKE_BUILD_PARALLEL_LEVEL: 4
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+        with:
+          submodules: true
+
+      - name: Configure
+        # Debug (no optimization), so each line is counted as written. -fprofile-update=atomic keeps the counts right
+        # in the tests that log from several threads at once; without it the threads' updates race and get lost.
+        env:
+          CC: gcc
+          CXX: g++
+          CXXFLAGS: "--coverage -fprofile-update=atomic"
+        run: cmake -S tests/cmake -B build -DCMAKE_BUILD_TYPE=Debug
+
+      - name: Build
+        run: cmake --build build
+
+      - name: Run unit tests
+        # A failing test fails the jobs above; the coverage of this run is still worth reporting
+        continue-on-error: true
+        run: ./build/bin/ASWLogTests --test-timeout-seconds 120 --catch-crashes
+
+      - name: Install gcovr
+        # 8.4 added the Markdown report. pipx installs it in an environment of its own (the runner's system Python
+        # refuses pip installs).
+        run: pipx install "gcovr>=8.4"
+
+      - name: Coverage report
+        # The crash handlers' tests crash child processes, which end before they can write their counts, so the crash
+        # paths show as not run.
+        run: |
+          mkdir -p coverage-html
+          gcovr --root . --filter 'ASWLog/' --print-summary --markdown coverage.md \
+            --html-details coverage-html/index.html
+          cat coverage.md >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload coverage report
+        uses: actions/upload-artifact@v7
+        with:
+          name: coverage-report
+          path: coverage-html/
+          if-no-files-found: error
diff --git a/AGENTS.md b/AGENTS.md
index 670ad39..e219277 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -12,7 +12,7 @@ ASWLog is a thread-safe, dependency-free C++20 logging library for Windows and L
 - `tests/` contains the unit tests: test modules (`Test_ASWLog_<Unit>`, the tests of `ASWLog_<Unit>`) and shared test helpers (`UT_Helper_<Topic>`, e.g. `UT_Helper_DateTime`) in `tests/tests/`, their CMake project in `tests/cmake/`, their RAD Studio console project in `tests/rad370/`, and their RAD Studio VCL GUI runner project in `tests/vcl/gui/rad370/` (built from the submodule's `vcl/gui/src`). `tests/compile_checks/` holds "must not compile" checks, which `tests/cmake/CMakeLists.txt` runs with `try_compile` when configuring (a failed check stops the configure). `tests/package/` is a project that builds against an installed ASWLog with `find_package` (CI installs the library and runs it).
 - `CMakeLists.txt` (the root) defines the `ASWLog::ASWLog` library target and its install rules; `cmake/ASWLogConfig.cmake.in` is the template of the installed package file. The project version is read from `ASWLog/ASWLog_Version.h`.
 - `third_party/asw-unit-tests/` is the ASWUnitTests framework, a git submodule pinned to a release tag. Never edit files in it; test modules self-register with `ASW_REGISTER_TEST_GROUP`, so adding a test only touches `tests/` and its build files.
-- `.github/workflows/ci.yml` builds and runs the unit tests on Windows (MSVC, MinGW) and Linux (GCC, Clang), plus Linux Clang builds with ThreadSanitizer and with AddressSanitizer + UBSan (`ASWLOG_SANITIZE`); the non-sanitizer jobs also check the installed CMake package (`tests/package/`).
+- `.github/workflows/ci.yml` builds and runs the unit tests on Windows (MSVC, MinGW) and Linux (GCC, Clang), plus Linux Clang builds with ThreadSanitizer and with AddressSanitizer + UBSan (`ASWLOG_SANITIZE`); the non-sanitizer jobs also check the installed CMake package (`tests/package/`). A Linux GCC coverage job (informational, it never fails the run) shows the library's line coverage on its summary page and uploads an HTML report.
 - `example/` contains example app that uses the logger.
 - `example/rad370/` contains the RAD Studio 13.1 project and Windows build scripts.
 - `README.md` contains repo details: features, quick start, project setup, API overview, versions and tests.
diff --git a/README.md b/README.md
index f1c919d..2bfd6bc 100644
--- a/README.md
+++ b/README.md
@@ -323,6 +323,10 @@ cmake --build tests/cmake/build-tsan
 
 CI runs both with Clang. `ASWLOG_SANITIZE` applies to the library and everything that links to it.
 
+CI also measures which lines of the library the tests run (a Linux GCC build with `--coverage`, read by gcovr): the
+"Linux (GCC, coverage)" job shows a table on its summary page and keeps an HTML report as the `coverage-report`
+artifact. It is informational and never fails the run.
+
 On Windows with RAD Studio, the tests can also run in the ASWUnitTests VCL GUI runner, a window for choosing tests and
 reading their results: build `tests/vcl/gui/rad370/ASWLogTests_VCL_GUI.cbproj` (or its `Build_Win64x_*.bat` scripts),
 which writes `ASWLogTests_VCL_GUI.exe` to `tests/build/bin/<Config>`. `ASWLogTests_Group.groupproj` in the same folder