Skip to main content

How to Add a Version History, Track Date, Author and Description to Batch Scripts

As a batch script evolves from a simple, personal tool into a critical piece of automation used by you or your team, tracking its changes becomes essential. A version history block at the top of your file is the simplest and most effective way to document the script's evolution. It makes the script easier to maintain, debug, and understand for anyone who opens it—including your future self.

This guide will explain the importance of versioning, present the recommended best practice for creating a "self-documenting" script header, and analyze the clever but less readable method from the original prompt to highlight why clarity is often better than cleverness.

Why You Need a Version History in Your Scripts​

A well-maintained version history provides immediate value:

  • Maintainability: Know at a glance what the latest version is and what changes have been made recently.
  • Collaboration: When multiple people work on a script, the history provides a clear log of who changed what, when, and why.
  • Debugging: If a new version introduces a bug, the history helps you quickly identify recent changes that might be the cause, drastically reducing troubleshooting time.
  • Professionalism: It's a hallmark of well-managed and thoughtfully constructed code, signaling that the script is a reliable tool.

The best practice is to use a simple, readable comment block using the standard REM (Remark) command, combined with a single variable that holds the current version number. This makes the script "self-documenting"—it contains its own history and can even report its own version when asked.

The Best-Practice Template​

@ECHO OFF
SETLOCAL

REM ============================================================================
REM SCRIPT:      DeployApplication.bat
REM AUTHOR:      Your Name / Your Team
REM DESCRIPTION: A script to deploy the new application version to test servers.
REM ----------------------------------------------------------------------------
REM                            VERSION HISTORY
REM ----------------------------------------------------------------------------
SET "SCRIPT_VERSION=1.1.0"
REM Version    Date        Author      Description
REM ----------------------------------------------------------------------------
REM 1.1.0      2024-01-15  J. Doe      Added /MIR flag to robocopy for faster sync.
REM 1.0.1      2023-12-10  A. Smith    Fixed bug with spaces in destination path.
REM 1.0.0      2023-11-20  J. Doe      Initial release of the deployment script.
REM ============================================================================

REM --- Add a --version or /v switch to the script ---
IF /I "%~1"=="--version" GOTO :displayVersion
IF /I "%~1"=="/v"        GOTO :displayVersion

REM --- Main script logic starts here ---
ECHO Executing deployment logic for version %SCRIPT_VERSION%...
ECHO Done.

GOTO :EOF

:displayVersion
ECHO %~n0, Version %SCRIPT_VERSION%
GOTO :EOF

How to Update: To add a new version, simply update the SET "SCRIPT_VERSION=..." line with the new version number and add a new REM line at the top of the history log.

Key Features of This Method​

  1. Clarity and Readability: It uses the standard REM command for comments. Anyone opening the file, regardless of their batch scripting skill level, immediately understands what they are looking at.
  2. Single Source of Truth: The SET "SCRIPT_VERSION=..." line acts as the definitive current version for the script's logic. You can use %SCRIPT_VERSION% in log messages, output files, etc.
  3. Self-Reporting Functionality: The IF statements at the top allow your script to report its own version number without running its main logic—an incredibly useful feature for verification in automated systems.

Making Your Script Report Its Own Version​

  • %~1: Refers to the first argument passed to the script.
  • IF /I "%~1"=="--version" ...: The /I makes the comparison case-insensitive. It checks if the first argument is --version or /v.
  • :displayVersion: A label for the version-displaying code block.
  • %~n0: A special batch variable that expands to the filename (without the extension) of the current script.

Running the version check from the command line:

C:\Scripts> DeployApplication.bat --version
DeployApplication.bat, Version 1.1.0

The "Clever" but Obscure Method Explained​

The script snippet from the prompt uses an interesting but non-obvious trick to embed comments on the same line as a SET command.

Original Code Snippet:

SET "version=01.000"      &:20051202 p.h.   framework ready

How the &: Trick Works​

  • The ampersand (&) is a command separator, allowing multiple commands on one line. The processor first executes SET "version=01.000".
  • It then moves to the next command on the line, which is :20051202 ....
  • The colon (:) at the beginning of a word on a line is interpreted as the start of a label (like a target for a GOTO statement).
  • However, the command processor has a rule that labels cannot begin with a number.
  • When the processor encounters this invalid label (:2005...), it silently stops processing the rest of the line, effectively turning the rest of the line into a comment.
  • Obscure and Unreadable: This is a non-obvious trick. A new person maintaining the script (or even you, six months later) would have to stop and figure out why it works instead of immediately understanding it. Code should be clear first, and clever second.
  • Fragile: It relies on a quirk of the command processor's error handling for invalid labels, which is less robust than using the designated comment syntax (REM). If the text after the colon accidentally started with a valid label name, it could cause unexpected behavior.
  • Poor Separation of Concerns: It mixes executable code (SET) with what is intended to be a comment on the same line, which can be confusing. The "self-documenting" REM block is much cleaner.

Best Practices for Maintaining a Version History​

  • Keep it at the Top: The version block should be one of the first things in the file so it's easy to find.
  • Be Consistent: Use a consistent format for dates (ISO YYYY-MM-DD is recommended as it sorts correctly), author initials, and version numbers (e.g., Semantic Versioning).
  • Newest First: List the most recent changes at the top of the history log.
  • Concise Descriptions: Briefly explain the what and why of the change. "Fixed bug" is okay, but "Fixed bug related to spaces in network path" is much better.

Conclusion​

While clever tricks like &: exist, writing maintainable and professional batch scripts favors clarity and standard practices.

Using a well-formatted header with REM comments for the version history and a SET command for the current version variable is the recommended best practice.

This approach makes your script self-documenting, easier for others (and your future self) to understand and maintain, and allows for useful features like a --version switch.

Table of Contents