NAME

       autorevision - extract current-revision metadata from version-control repositories

SYNOPSIS

       autorevision -t <output-type> [-o <cache-file> [-f] ] [-e <name>] [-U] [-C <path>] [-q]

       autorevision -s <symbol> [-o <cache-file> [-f] ] [-e <name>] [-U] [-C <path>] [-q]

       autorevision -V

DESCRIPTION

       Extracts metadata about the head revision from your repository.

       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).

       The generated source is written to the standard output.

       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.

       If you specify a cache file, then when autorevision 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.

   Valid Repository Types
       Git: A version greater than 1.7.2.3 is recommended.

       Mercurial: A version greater than 1.6 is recommended.

       Subversion: Any production version.

       Bazaar: Any production version.

   Valid Output Types
       clojure
           A clojure source file setting clojure variables.

       c
           A C/C++ source file.

           autorevision_declr.h in the contribs dir is provided for use with this output.

       cmake
           A cmake script file.

       csharp
           C# file with Autorevision class

       h
           A header file suitable for C/C++.

       hpp
           Alternate C++ header file with namespace. Namespace is assigned from VCS_BASENAME.

       ini
           A ini source file setting ini variables.

       java
           A Java source file setting class properties.

       javaprop
           A Java properties file (like ini); useful when META-INF is readable in Java.

       js
           A javascript source file setting javascript variables.

       json
           A JSON format file.

       lua
           A lua source file setting lua variables.

       m4
           An m4 source file defining m4 macros.

       matlab
           Matlab output.

       octave
           Octave output.

       php
           A PHP source file setting PHP variables.

       pl
           A Perl source file setting Perl variables (perl is an acceptable synonym).

       py
           A Python source file setting Python variables (python is an acceptable synonym).

       rpm
           A RPM spec file format setting spec file macros.

       scheme
           A scheme source file setting scheme variables.

       sed
           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.

       sh
           A text file suitable for including from a bash script. Will work with Ruby.

       swift
           A Swift source file setting Swift global constants.

           Unless set VCS_EXTRA and any symbols that are missing because of repository support
           are set to nil.

       tex
           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 \vcsShortHash.

       xcode
           A header like output for use with xcode to populate info.plist strings.

   Valid Symbol Names
       VCS_TYPE
           The repository type - "git", "hg", "bzr", or "svn".

       VCS_BASENAME
           The basename of the directory root. For most VCSes this will simply be the basename of
           the repository root directory. For Subversion, autorevision will attempt to navigate
           up though trunk, branches, and tags directories to find the actual root.

       VCS_NUM
           A count of revisions between the current one and the initial one; useful for reporting
           build numbers.

       VCS_UUID
           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.

       VCS_DATE
           The date of the most recent commit in true ISO-8601/RFC3339 format, including seconds.

       VCS_BRANCH
           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’t have a
           shortname it will be a full refspec.

           Under hg the feature that is called branches 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 trunk or the basename of some branch or
           tag subdirectory, depending on where autoversion was run.

           Under bzr, this is the nick of the branch you are on.

       VCS_TAG
           The name of the most recent tag ancestral to the current commit.

           Empty under Subversion.

       VCS_TAG_OPENPGP
           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.

       VCS_TICK
           A count of commits since most recent tag ancestral to the current commit or an alias
           of VCS_NUM if there are no prior tags.

           Empty under Subversion.

       VCS_EXTRA
           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. (See -e for more
           info.)

       VCS_ACTION_STAMP
           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.

       VCS_FULL_HASH
           A full unique identifier for the current revision.

       VCS_COMMIT_OPENPGP
           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.

       VCS_SHORT_HASH
           A shortened version of VCS_FULL_HASH, but VCS_FULL_HASH if it cannot be shortened.

       VCS_WC_MODIFIED
           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.

           Untracked files are not ignored; see -U for details.

OPTIONS

       -t <output-type>
           Sets the output type. It is required unless -s is specified; both -t and -s cannot be
           used in the same invocation.

       -s <symbol>
           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 -t is
           specified; both -t and -s cannot be used in the same invocation.

       -o <cache-file>
           Sets the name of the cache file.

       -e <name>
           Sets the output name of VCS_EXTRA Defaults to VCS_EXTRA.

       -f
           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.

       -U
           Causes untracked files to be checked when determining if the working copy is modified
           for Subversion only. While this is the default behavior for all other repository
           types, it is off by default for Subversion because of speed concerns.

       -C <path>
           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.

       -q
           Silence warnings.

       -V
           Emits the autorevision version and exits.

BUGS

       The bzr extractor is not very well tested.

       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’t use
       svn-remote.svn.url.

       Nested repositories, particularly repositories of different types, may result in incorrect
       and unintended behavior.

       Unpacking a tarball into a repository will result in incorrect and unintended behavior.

NOTES

       Development of autorevision is carried out at https://github.com/Autorevision/autorevision

       HTML rendered docs and usage examples can be found at https://autorevision.github.io/

AUTHORS

       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.

  1.22                                      2021-01-25                            AUTOREVISION(1)