Git::DescribeVersion - Use git-describe to show a repo's version
version 1.015
use Git::DescribeVersion (); print Git::DescribeVersion->new({opt => 'value'})->version();
Use git describe to determine a git repo's version.
git describe
This is the main module, though it's probably more useful run from the shell:
$ git describe-version
The included git-describe-version script wraps Git::DescribeVersion::App.
git-describe-version
NOTE: This module requires git version 1.5.5 or greater.
1.5.5
The version is determined by counting the commits since the most recent tag (matching the "match_pattern") and using that count as the final part of the version.
So to create a typical three part version (v1.2.3) repo tags should be made of the first two parts (v1.2) and the number of commits counted by git-describe will become the third part (v1.2.35).
v1.2.3
v1.2
git-describe
v1.2.35
The constructor accepts a hash or hashref of options:
Git::DescribeVersion->new({opt => 'value'}); Git::DescribeVersion->new(opt1 => 'v1', opt2 => 'v2');
See "OPTIONS" for an explanation of the available options.
Format the supplied version object according to the "format" attribute.
A method to wrap the git commands. Attempts to use Git::Repository or Git::Wrapper. Falls back to using backticks.
A method to take the version parts found and return the end result.
Uses the version module to parse.
The version method is the main method of the class. It attempts to return the repository version.
version
It will first use "version_from_describe".
If that fails it will try to simulate the functionality with "version_from_count_objects" and will start the count from the "first_version" option.
Use git-describe to count the number of commits since the last tag matching "match_pattern".
It effectively calls
git describe --match "${match_pattern}" --tags --long
If no matching tags are found (or some other error occurs) it will return undef.
Use git-count-objects to count the number of commit objects in the repository. It then appends this count to "first_version".
git-count-objects
git count-objects -v
and sums up the counts for 'count' and 'in-pack'.
These options can be passed to "new":
Directory in which git should operate. Defaults to ".".
If the repository has no tags at all, this version is used as the first version for the distribution.
Then git objects will be counted and appended to create a version like v0.1.5.
v0.1.5
If set to undef then "version" will return undef if "version_from_describe" cannot determine a value.
undef
Defaults to v0.1.
v0.1
Specify the output format for the version number.
I had trouble determining the most reasonable names for the formats so a few variations are possible. (Pick the one which makes the most sense to you.)
dotted, normal, v-string or v
for values like v1.2.3.
no-v-string (or no-v or no_v)
to discard the opening v for values like 1.2.3.
v
1.2.3
decimal
for values like 1.002003.
1.002003
Defaults to decimal for compatibility.
Regular expression that matches a tag containing a version. It must capture the version into $1.
$1
Defaults to ([0-9._]+) which will simply capture the first dotted-decimal found. This matches tags like v0.1, rev-1.2 and even release-2.0-skippy.
([0-9._]+)
rev-1.2
release-2.0-skippy
A shell-glob-style pattern to match tags. This is passed to git-describe to help it find the right tag from which to count commits.
Defaults to v[0-9]*.
v[0-9]*
This module started out as a line in a Makefile:
VERSION = $(shell (cd $(srcdir); \ git describe --match 'v[0-9].[0-9]' --tags --long | \ grep -Eo 'v[0-9]+\.[0-9]+-[0-9]+' | tr - . | cut -c 2-))
As soon as I wanted it in another Makefile (in another repository) I knew I had a problem.
Then when I started learning Dist::Zilla I found Dist::Zilla::Plugin::Git::NextVersion but missed the functionality I was used to with git-describe.
I started by forking Dist::Zilla::Plugin::Git on github, but realized that if I wrote the logic into a Dist::Zilla plugin it wouldn't be available to my git repositories that weren't Perl distributions.
So I wanted to extract the functionality to a module, make a separate Dist::Zilla::Role::VersionProvider plugin, and include a quick version that could be run with a minimal command line statement (so that I could put that in my Makefiles).
Allow using git-log to count commits affecting a subdirectory
Allow for more complex regexps (multiple groups) if there is a need.
Options for raising errors versus swallowing them?
Consider a dynamic installation to test `git --version`.
`git --version`
Git::DescribeVersion::App
Dist::Zilla::Plugin::Git::DescribeVersion
Git::Repository or Git::Wrapper
http://www.git-scm.com
You can find documentation for this module with the perldoc command.
perldoc Git::DescribeVersion
The following websites have more information about this module, and may be of help to you. As always, in addition to those websites please use your favorite search engine to discover more resources.
Search CPAN
The default CPAN search engine, useful to view POD in HTML format.
http://search.cpan.org/dist/Git-DescribeVersion
RT: CPAN's Bug Tracker
The RT ( Request Tracker ) website is the default bug/issue tracking system for CPAN.
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Git-DescribeVersion
CPAN Ratings
The CPAN Ratings is a website that allows community ratings and reviews of Perl modules.
http://cpanratings.perl.org/d/Git-DescribeVersion
CPAN Testers
The CPAN Testers is a network of smokers who run automated tests on uploaded CPAN distributions.
http://www.cpantesters.org/distro/G/Git-DescribeVersion
CPAN Testers Matrix
The CPAN Testers Matrix is a website that provides a visual overview of the test results for a distribution on various Perls/platforms.
http://matrix.cpantesters.org/?dist=Git-DescribeVersion
CPAN Testers Dependencies
The CPAN Testers Dependencies is a website that shows a chart of the test results of all dependencies for a distribution.
http://deps.cpantesters.org/?module=Git::DescribeVersion
Please report any bugs or feature requests by email to bug-git-describeversion at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Git-DescribeVersion. You will be automatically notified of any progress on the request by the system.
bug-git-describeversion at rt.cpan.org
https://github.com/rwstauner/Git-DescribeVersion
git clone https://github.com/rwstauner/Git-DescribeVersion.git
Randy Stauner <rwstauner@cpan.org>
This software is copyright (c) 2010 by Randy Stauner.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Git::DescribeVersion, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Git::DescribeVersion
CPAN shell
perl -MCPAN -e shell install Git::DescribeVersion
For more information on module installation, please visit the detailed CPAN module installation guide.