/ 
Git-DescribeVersion-0.005011-TRIAL
River stage one • 1 direct dependent • 1 total dependent
/ Git::DescribeVersion

NAME

Git::DescribeVersion - Use git-describe to show a repo's version

VERSION

version 0.005011

SYNOPSIS

use Git::DescribeVersion ();
Git::DescribeVersion->new({opt => 'value'})->version();

Or this one-liner:

perl -MGit::DescribeVersion::App -e run

See Git::DescribeVersion::App for more examples of that usage.

METHODS

new

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.

parse_version

A method to take the version parts found and return the end result.

Uses the version module to parse.

version

The version method is the main method of the class. It attempts to return the repo 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.

version_from_describe

Use git-describe to count the number of commits since the last tag matching match_pattern.

It effectively calls

git describe --tags --long --match_pattern "${match_pattern}"

If no matching tags are found (or some other error occurs) it will return undef.

version_from_count_objects

Use git-count-objects to count the number of commit objects in the repo. It then appends this count to first_version.

It effectively calls

git count-objects -v

and sums up the counts for 'count' and 'in-pack'.

OPTIONS

These options can be passed to "new":

directory

Directory in which git should operate. Defaults to ".".

first_version

If the repository has no tags at all, this version is used as the first version for the distribution. It defaults to v0.1. Then git objects will be counted and appended to create a version like v0.1.5.

version_regexp

Regular expression that matches a tag containing a version. It must capture the version into $1. Defaults to ^v([0-9._]+)$ which matches tags like v0.1.

match_pattern

A shell-glob-style pattern to match tags (default v[0-9]*). This is passed to git-describe to help it find the right tag from which to count commits.

HISTORY / RATIONALE

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 repo) 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 repos that weren't Perl distributions.

So I wanted to extract the functionality to a module, include a Dist::Zilla::Role::VerionProvider 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).

TODO

  • An attribute for specifying the output as floating point or dotted decimal.

  • Allow for more complex regexps (multiple groups) if there is a need.

  • Options for raising errors versus swallowing them?

SEE ALSO

AUTHOR

Randy Stauner <rwstauner@cpan.org>

COPYRIGHT AND LICENSE

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.