version

Section: Misc. Reference Manual Pages (February 2014)
Updated: BSD/Linux
Index

NAME

version - copy version numbers across source code files

SYNOPSIS

version

[ action file.name ] action file.name [ action ] action [ file.name action ] file.name action

DESCRIPTION

version is a commandline tool to extract version numbers from source code files, optionally modify it, write it back to source code, or synchronize package build scripts.

It's regex based, and looks for the common x.y.z version style, including build/patch suffixes. For reading and writing from and to source code it considers file extensions to infer the type and constrained context / syntax to modify.

OPTIONS

Action names may be prepended with a single - or double -- dash.

File actions

Every valid filename will be treated as such. The order of action and filename is insignificant for those actions that consume it.

get file.name

Reads and prints version number from source file.

read file.name

Just reads a version number from source code. Does not print it.

write file.name

Updates a file. Depending on file type inserts the currently proccessed version number into appropriate code context / syntax.

... last

Reuses the last consumed filename with a new action. For instance read file1.c write last

will update to where the read action did previously load from.

Version data

After reading from a file, the version number is kept as current value for further actions.

-show

Outputs the version number.

-incr/++

Increments the decimal after the last version dot (commonly understood as the patch version). For instance 0.0.x or 0.0.0.y

-bump

Adds or increments the build suffix, as in x.x.x-1

Additional alphanumeric suffixes or subversioning schemes may occur thereafter, like 1.2.3-1dev_2 or 3.5-0beta_2.7, and are ignored by the -bump action. Also allows a bump::2

count argument.

1.2.3-0alpha

Any commandline argument that matches the common numeric version number format will be understood as current version, for later modification or writing elsewhere.

Miscellaneous options

File actions may be preceded by a -format option, which takes two optional arguments separated by :colons.

And in addition to filenames, version numbers itself can be input sources.

-format:name

Specifies a file type or regex name. The type may be any known file extension, a list of file extensions, or an internal format name specifying just one constrained regex context / code syntax.

-format::count

The second option rules on how many regex replacements in a target file may occur. Which constrains the default mode to just replacing the first allowed format and version number. It's useful to allow updating two occurences in different --format:docblock,var:2

variations and locations.

Actually the --format action is a virtual action. And the optional arguments may as well be merged into write:fmt:cnt

or read:fmt

actions.

-dry/nowrite

This is a debugging option, which wakes writing operations non-destructive; but just outputs the modified target file.

EXAMPLES

version get file.c: Reads from filename and outputs found version number.
version read file.c write dist/header.c: Looks for the first version number, and writes it to another file where appropriate syntax was found.
version read file.php ++ write file.php: Increments patch version number, and updates file.
version -read file.php -incr -bump -write:_raw_:2 readme.txt: Reads from source, updates patch version and release suffix, then writes to a text file using the _raw_ format (any version number without context checks will be updated) two times.
version src/file.php read and then src/out.c write: The order of read/write actions and filenames may be reversed, "and" and "then" are just filler no-op commands.

VERSION=$(version get file.name)

version $VERSION write file.name

The version tool is meant to be utilized from build preparation scripts. While both actions can be done in one call, it's sometimes useful to keep the current $VERSION number in shell context (e.g. for adapting output filenames).

version get:php /usr/bin/version

Just shows the version of the version tool.

FORMATS

Common file extensions php, py, cpp, c, json, sh, xml, spec are understood and mapped already to some of the internal context / syntax formats (as implemented per regex):

debian (Debian package control)

Version: 1.0.0

rpmspec (RPM package spec)

%version 1.0.0

plugin (generic/php plugin meta data format in # or // or /** blocks)

# version: 1.0.0

docblock (documentation version numbers)

* @version 1.0.0

const (constant declarations)

const VERSION = '1.0.0';

var (scripting languages syntax)

$Xyz_version = "1.0.0";

define (PHP constant syntax)

define("XYZ_VERSION", '1.0.0');

ini (configuration files)

version = "1.0.0"

python (module numbers)

__version__ = "1.0.0"

composer (JSON)

{ "version": "1.0.0",

xmltag (XML)

_raw_ (match anything)

This matches virtually anywhere, as it just applies the common version number syntax regex, but does not take any syntax context into account.

manpage