'\" t
.\"     Title: autorevision
.\"    Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 2021-01-25
.\"    Manual: \ \&
.\"    Source: \ \& 1.22
.\"  Language: English
.\"
.TH "AUTOREVISION" "1" "2021\-01\-25" "\ \& 1\&.22" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
autorevision \- extract current\-revision metadata from version\-control repositories
.SH "SYNOPSIS"
.sp
\fBautorevision\fR \fB\-t\fR <output\-type> [\fB\-o\fR <cache\-file> [\fB\-f\fR] ] [\fB\-e\fR <name>] [\fB\-U\fR] [\fB\-C\fR <path>] [\fB\-q\fR]
.sp
\fBautorevision\fR \fB\-s\fR <symbol> [\fB\-o\fR <cache\-file> [\fB\-f\fR] ] [\fB\-e\fR <name>] [\fB\-U\fR] [\fB\-C\fR <path>] [\fB\-q\fR]
.sp
\fBautorevision\fR \fB\-V\fR
.SH "DESCRIPTION"
.sp
Extracts metadata about the head revision from your repository\&.
.sp
This program is meant to be used by project build systems to extract properties that can be used in version strings\&. It can emit source files containing variable and macro definitions suitable for use with C, C++, Java, Mac info\&.plist, sh, Python, Perl and many other types of files (see below for the full list)\&.
.sp
The generated source is written to the standard output\&.
.sp
This program can normally be called from anywhere within a repository copy\&. Under bzr the copy must be of a branch, not a full multibranch repository\&. Under Subversion it must be called under a repository checkout, not the repository itself\&.
.sp
If you specify a cache file, then when \fBautorevision\fR is run where no repository can be recognized, the values from the cache file will be used instead\&. If a repository can be recognized, the cache is rewritten\&. This feature makes it possible for your build to run from an unpacked tarball that includes the cache file\&.
.SS "Valid Repository Types"
.sp
\fBGit\fR: A version greater than 1\&.7\&.2\&.3 is recommended\&.
.sp
\fBMercurial\fR: A version greater than 1\&.6 is recommended\&.
.sp
\fBSubversion\fR: Any production version\&.
.sp
\fBBazaar\fR: Any production version\&.
.SS "Valid Output Types"
.PP
\fBclojure\fR
.RS 4
A clojure source file setting clojure variables\&.
.RE
.PP
\fBc\fR
.RS 4
A C/C++ source file\&.

autorevision_declr\&.h
in the contribs dir is provided for use with this output\&.
.RE
.PP
\fBcmake\fR
.RS 4
A cmake script file\&.
.RE
.PP
\fBcsharp\fR
.RS 4
C# file with Autorevision class
.RE
.PP
\fBh\fR
.RS 4
A header file suitable for C/C++\&.
.RE
.PP
\fBhpp\fR
.RS 4
Alternate C++ header file with namespace\&. Namespace is assigned from VCS_BASENAME\&.
.RE
.PP
\fBini\fR
.RS 4
A ini source file setting ini variables\&.
.RE
.PP
\fBjava\fR
.RS 4
A Java source file setting class properties\&.
.RE
.PP
\fBjavaprop\fR
.RS 4
A Java properties file (like ini); useful when META\-INF is readable in Java\&.
.RE
.PP
\fBjs\fR
.RS 4
A javascript source file setting javascript variables\&.
.RE
.PP
\fBjson\fR
.RS 4
A JSON format file\&.
.RE
.PP
\fBlua\fR
.RS 4
A lua source file setting lua variables\&.
.RE
.PP
\fBm4\fR
.RS 4
An m4 source file defining m4 macros\&.
.RE
.PP
\fBmatlab\fR
.RS 4
Matlab output\&.
.RE
.PP
\fBoctave\fR
.RS 4
Octave output\&.
.RE
.PP
\fBphp\fR
.RS 4
A PHP source file setting PHP variables\&.
.RE
.PP
\fBpl\fR
.RS 4
A Perl source file setting Perl variables (\fBperl\fR
is an acceptable synonym)\&.
.RE
.PP
\fBpy\fR
.RS 4
A Python source file setting Python variables (\fBpython\fR
is an acceptable synonym)\&.
.RE
.PP
\fBrpm\fR
.RS 4
A RPM spec file format setting spec file macros\&.
.RE
.PP
\fBscheme\fR
.RS 4
A scheme source file setting scheme variables\&.
.RE
.PP
\fBsed\fR
.RS 4
A sed script that replaces symbol names enclosed in @ symbols\&. It uses the | character as a separator in the sed commands\&. You can run it using
sed \-f script\&.sed file\-to\-edit\&.
.RE
.PP
\fBsh\fR
.RS 4
A text file suitable for including from a bash script\&. Will work with Ruby\&.
.RE
.PP
\fBswift\fR
.RS 4
A Swift source file setting Swift global constants\&.

Unless set
\fBVCS_EXTRA\fR
and any symbols that are missing because of repository support are set to
nil\&.
.RE
.PP
\fBtex\fR
.RS 4
A TeX source file defining TeX macros\&. Note that the symbols are given different names since the underscore has a special meaning in TeX\&. For example, VCS_SHORT_HASH is renamed to \evcsShortHash\&.
.RE
.PP
\fBxcode\fR
.RS 4
A header like output for use with xcode to populate info\&.plist strings\&.
.RE
.SS "Valid Symbol Names"
.PP
\fBVCS_TYPE\fR
.RS 4
The repository type \- "git", "hg", "bzr", or "svn"\&.
.RE
.PP
\fBVCS_BASENAME\fR
.RS 4
The basename of the directory root\&. For most VCSes this will simply be the basename of the repository root directory\&. For Subversion,
\fBautorevision\fR
will attempt to navigate up though trunk, branches, and tags directories to find the actual root\&.
.RE
.PP
\fBVCS_NUM\fR
.RS 4
A count of revisions between the current one and the initial one; useful for reporting build numbers\&.
.RE
.PP
\fBVCS_UUID\fR
.RS 4
A universally unique identifier, generated from the root commit in git and hg; for svn it uses the supplied UUID\&.

For git we choose the oldest commit if there is more than one\&.

Not currently implemented for bzr\&.
.RE
.PP
\fBVCS_DATE\fR
.RS 4
The date of the most recent commit in true ISO\-8601/RFC3339 format, including seconds\&.
.RE
.PP
\fBVCS_BRANCH\fR
.RS 4
The name of the branch of the commit graph that was selected when autoversion was run\&.

Under git, this will normally be the shortname of the current branch (the asterisked line in the output of "git branch") except that when the branch doesn\(cqt have a shortname it will be a full refspec\&.

Under hg the feature that is called
\fIbranches\fR
is actually a sort of graph coloring (multiple heads can have the same branch name) so this symbol is filled with the current bookmark if it exists, with the current branch name as a fallback\&.

Under Subversion this will normally be either
\fItrunk\fR
or the basename of some branch or tag subdirectory, depending on where
\fBautoversion\fR
was run\&.

Under bzr, this is the nick of the branch you are on\&.
.RE
.PP
\fBVCS_TAG\fR
.RS 4
The name of the most recent tag ancestral to the current commit\&.

Empty under Subversion\&.
.RE
.PP
\fBVCS_TAG_OPENPGP\fR
.RS 4
The fingerprint OpenPGP of the key that that signed the current tag\&.

Blank if the current tag is not signed or if no tags exist\&.

Currently only implemented for git\&.
.RE
.PP
\fBVCS_TICK\fR
.RS 4
A count of commits since most recent tag ancestral to the current commit or an alias of
\fBVCS_NUM\fR
if there are no prior tags\&.

Empty under Subversion\&.
.RE
.PP
\fBVCS_EXTRA\fR
.RS 4
A symbol set aside specifically to be set by the user through the environment or via scripts\&.

Additionally, the name of this symbol may be customized as well\&. (\fISee \fR\fI\fB\-e\fR\fR\fI for more info\&.\fR)
.RE
.PP
\fBVCS_ACTION_STAMP\fR
.RS 4
An "action stamp" consists of an RFC3339 timestamp in Zulu time, followed by an exclamation point, followed by an RFC822 address (technically, an "addr\-spec" as defined in 6\&.1)\&.

For svn the second part is simply the author name\&.

Not currently implemented for bzr\&.
.RE
.PP
\fBVCS_FULL_HASH\fR
.RS 4
A full unique identifier for the current revision\&.
.RE
.PP
\fBVCS_COMMIT_OPENPGP\fR
.RS 4
The fingerprint OpenPGP of the key that that signed the current revision\&.

Blank if the current revision is not signed\&.

Currently only implemented for git\&.
.RE
.PP
\fBVCS_SHORT_HASH\fR
.RS 4
A shortened version of
\fBVCS_FULL_HASH\fR, but
\fBVCS_FULL_HASH\fR
if it cannot be shortened\&.
.RE
.PP
\fBVCS_WC_MODIFIED\fR
.RS 4
Set to
1
if the current working directory has been modified and
0
if not\&. If the output language has native Boolean literals, true will mean modified and false unmodified\&. The C/C++ output is left as numeric so the preprocessor can test it\&.

\fIUntracked files are not ignored; see \fR\fI\fB\-U\fR\fR\fI for details\&.\fR
.RE
.SH "OPTIONS"
.PP
\fB\-t\fR \fI<output\-type>\fR
.RS 4
Sets the output type\&. It is required unless
\fB\-s\fR
is specified; both
\fB\-t\fR
and
\fB\-s\fR
cannot be used in the same invocation\&.
.RE
.PP
\fB\-s\fR \fI<symbol>\fR
.RS 4
Changes the reporting behavior; instead of emitting a symbol file to stdout, only the value of that individual symbol will be reported\&. It is required unless
\fB\-t\fR
is specified; both
\fB\-t\fR
and
\fB\-s\fR
cannot be used in the same invocation\&.
.RE
.PP
\fB\-o\fR \fI<cache\-file>\fR
.RS 4
Sets the name of the cache file\&.
.RE
.PP
\fB\-e\fR \fI<name>\fR
.RS 4
Sets the output name of
\fBVCS_EXTRA\fR
Defaults to
VCS_EXTRA\&.
.RE
.PP
\fB\-f\fR
.RS 4
Forces the use of cache data even when in a repo; useful for speeding up subsequent runs if more than one output format is needed\&.
.RE
.PP
\fB\-U\fR
.RS 4
Causes untracked files to be checked when determining if the working copy is modified
\fIfor Subversion only\fR\&. While this is the default behavior for all other repository types, it is off by default for Subversion because of speed concerns\&.
.RE
.PP
\fB\-C\fR \fI<path>\fR
.RS 4
Change working directory to given path\&. This allows autorevision to extract metadata from repositories found at a specific path to support VPATH or out\-of\-source builds\&.
.RE
.PP
\fB\-q\fR
.RS 4
Silence warnings\&.
.RE
.PP
\fB\-V\fR
.RS 4
Emits the autorevision version and exits\&.
.RE
.SH "BUGS"
.sp
The bzr extractor is not very well tested\&.
.sp
When a git repo is actually a git\-svn remote, this tool tries to do the right thing and return a Subversion revision\&. The bug is that the detector code for this case is somewhat unreliable; you will get the hash instead if your configuration doesn\(cqt use svn\-remote\&.svn\&.url\&.
.sp
Nested repositories, particularly repositories of different types, \fImay\fR result in incorrect and unintended behavior\&.
.sp
Unpacking a tarball into a repository \fIwill\fR result in incorrect and unintended behavior\&.
.SH "NOTES"
.sp
Development of autorevision is carried out at https://github\&.com/Autorevision/autorevision
.sp
HTML rendered docs and usage examples can be found at https://autorevision\&.github\&.io/
.SH "AUTHORS"
.sp
dak180 <dak180@users\&.sf\&.net>: concept, bash/C/C++/XCode/PHP/ini support, git and hg extraction\&. Eric S\&. Raymond <esr@thyrsus\&.com>: Python/Perl/lua/m4 support, svn and bzr extraction, git\-svn support, CLI design, man page\&. See AUTHORS\&.txt for a full list in order of number of contributions\&.