D 2014-02-07T19:57:12.103
L manpage
P 7680418670458bb8205afabb52e8f41faa19d19c
U mario
W 7294
<H1>version</H1>
Section: Misc. Reference Manual Pages (February 2014)<BR>Updated: BSD/Linux<BR><A HREF="#index">Index</A>
<A NAME="lbAB"> </A>
<H2>NAME</H2>
version - copy version numbers across source code files
<A NAME="lbAC"> </A>
<H2>SYNOPSIS</H2>
<B>version</B>
[
<B>action</B><I> file.name</I>
] [
<B>action</B>
] [
<I>file.name </I><B>action</B>
]
<P>
<A NAME="lbAD"> </A>
<H2>DESCRIPTION</H2>
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.
<P>
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.
<A NAME="lbAE"> </A>
<H2>OPTIONS</H2>
Action names may be prepended with a single - or double -- dash.
<P>
<B>File actions</B>
<P>
Every valid filename will be treated as such. The order of action
and filename is insignificant for those actions that consume it.
<DL COMPACT>
<DT><B>get</B><I> file.name</I>
<DD>
Reads and prints version number from source file.
<DT><B>read</B><I> file.name</I>
<DD>
Just reads a version number from source code. Does not print it.
<DT><B>write</B><I> file.name</I>
<DD>
Updates a file. Depending on file type inserts the currently
proccessed version number into appropriate code context / syntax.
<DT><I>...</I><B> last</B>
<DD>
Reuses the last consumed filename with a new action. For instance
<B>read</B><I> file1.c </I><B>write last</B>
will update to where the read action did previously load from.
</DL>
<P>
<B>Version data</B>
<P>
After reading from a file, the version number is kept as current
value for further actions.
<DL COMPACT>
<DT>-<B>show</B>
<DD>
Outputs the version number.
<DT>-<B>incr</B>/<B>++</B>
<DD>
Increments the decimal after the last version dot (commonly understood as
the patch version). For instance 0.0.x or 0.0.0.y
<DT>-<B>bump</B>
<DD>
Adds or increments the build suffix, as in x.x.x-1
<BR>
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
<B>bump</B><I>::</I><B>2</B>
count argument.
<DT><I>1</I>.<I>2</I>.<I>3</I>-<I>0alpha</I>
<DD>
Any commandline argument that matches the common numeric version
number format will be understood as current version, for later
modification or writing elsewhere.
</DL>
<P>
<B>Miscellaneous options</B>
<P>
File actions may be preceded by a -format option, which takes
two optional arguments separated by
<B>:</B>colons.
And in addition to filenames, version numbers itself can be input sources.
<DL COMPACT>
<DT>-<B>format</B>:<B>name</B>
<DD>
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.
<DT>-<B>format</B>::<B>count</B>
<DD>
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
<B>--format</B>:<B>docblock,var</B>:<B>2</B>
variations and locations.
<P>
Actually the --format action is a virtual action. And the optional
arguments may as well be merged into
<B>write</B>:<B>fmt</B>:<B>cnt</B>
or
<B>read</B>:<B>fmt</B>
actions.
<DT>-<B>dry</B>/<B>nowrite</B>
<DD>
This is a debugging option, which wakes writing operations non-destructive;
but just outputs the modified target file.
<P>
</DL>
<A NAME="lbAF"> </A>
<H2>EXAMPLES</H2>
<DL COMPACT>
<DT><I>version</I><B> get</B><I> file.c</I>
<DD>
Reads from filename and outputs found version number.
<DT><I>version</I><B> read</B><I> file.c</I><B> write</B><I> dist/header.c</I>
<DD>
Looks for the first version number, and writes it to another file
where appropriate syntax was found.
<DT><I>version</I><B> read</B><I> file.php</I><B> ++ write</B><I> file.php</I>
<DD>
Increments patch version number, and updates file.
<DT><I>version</I><B> -read</B><I> file.php</I><B> -incr -bump -write</B><I>:</I><B>_raw_</B><I>:</I><B>2</B><I> readme.txt</I>
<DD>
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.
<DT><I>version src/file.php</I><B> read and then </B><I>src/out.c</I><B> write</B>
<DD>
The order of read/write actions and filenames may be reversed, "and" and
"then" are just filler no-op commands.
</DL>
<P>
<P>
<I>VERSION=$(</I><B>version get file.name</B><I>)</I>
<BR>
<B>version</B><I> $VERSION </I><B>write file.name</B>
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).
<DL COMPACT>
<DT><I>version</I><B> get:php</B><I> /usr/bin/version</I>
<DD>
Just shows the version of the version tool.
<P>
</DL>
<A NAME="lbAG"> </A>
<H2>FORMATS</H2>
<DL COMPACT>
<DT>Common file extensions <I>php</I>, <I>py</I>, <I>cpp</I>, <I>c</I>, <I>json</I>, <I>sh</I>, <I>xml</I>, <I>spec</I> are understood and mapped already to <I>some</I> of the internal context / syntax formats (as implemented per regex):
<DD>
<DT><B>debian</B> (Debian package control)
<DD>
Version: 1.0.0
<DT><B>rpmspec</B> (RPM package spec)
<DD>
%version 1.0.0
<DT><B>plugin</B> (generic/php plugin meta data format in <B>#</B> or <B>//</B> or <B>/**</B> blocks)
<DD>
# version: 1.0.0
<DT><B>docblock (documentation version numbers)</B>
<DD>
* @version 1.0.0
<DT><B>const (constant declarations)</B>
<DD>
const VERSION = '1.0.0';
<DT><B>var</B> (scripting languages syntax)
<DD>
$Xyz_version = "1.0.0";
<DT><B>define</B> (PHP constant syntax)
<DD>
define("XYZ_VERSION", '1.0.0');
<DT><B>ini</B> (configuration files)
<DD>
version = "1.0.0"
<DT><B>python</B> (module numbers)
<DD>
__version__ = "1.0.0"
<DT><B>composer</B> (JSON)
<DD>
{ "version": "1.0.0",
<DT><B>xmltag</B> (XML)
<DD>
<version>1.0.0</version>
<DT><B>_raw_</B> (match anything)
<DD>
This matches virtually anywhere, as it just applies the common version
number syntax regex, but does not take any syntax context into account.
<P>
</DL>
<A NAME="lbAH"> </A>
<H2>SEE ALSO</H2>
<B><A HREF="http://semver.org/#">http://semver.org/#</A></B>(2.0.0)
<P>
<HR>
<A NAME="index"> </A><H2>Index</H2>
<DL>
<DT><A HREF="#lbAB">NAME</A><DD>
<DT><A HREF="#lbAC">SYNOPSIS</A><DD>
<DT><A HREF="#lbAD">DESCRIPTION</A><DD>
<DT><A HREF="#lbAE">OPTIONS</A><DD>
<DT><A HREF="#lbAF">EXAMPLES</A><DD>
<DT><A HREF="#lbAG">FORMATS</A><DD>
<DT><A HREF="#lbAH">SEE ALSO</A><DD>
</DL>
<HR>
Z abd3610366b5974c56f6573a27d3e56f