Dist::...Version(3pm)

✨ NAME ✨

Dist::Zilla::Plugin::Git::NextVersion — bestie, this plugin hands you a version number by bumping the last git release tag 💅

You're reading the manual page for the Dist::...Version thing (that's the short title the man system gives it, the full name is the one right up there ⬆️).

🎀 VERSION 🎀

version 2.052 — that's the one you're looking at rn.

🦋 SYNOPSIS 🦋

Pop this into your dist.ini:

[Git::NextVersion]
first_version = 0.001       ; this is the default
version_by_branch = 0       ; this is the default
version_regexp  = ^v(.+)$   ; this is the default

💖 DESCRIPTION 💖

Okay so here's the tea ☕ — this plugin does the VersionProvider role. It goes snooping through your Git tags, finds the last version number hiding in there, bumps it using Version::Next, and then drops that result in as the version parameter for your distribution. Slay.

And like, extra bonus: when you're making a release, it makes sure the version you're releasing hasn't already been tagged. No duplicates on its watch 🫶

Ngl, the Git::Tag plugin has a similar check — but Git::Tag only checks for an exact match on the tag. Git::NextVersion actually knows how to extract version numbers from tags, so it can catch duplicates that Git::Tag would totally miss. Different energy fr fr.

The plugin accepts the following options:

• first_version — if your repo has literally no tags at all (empty, tragic, no tag history 💀), this version is used as the first version for the distribution. It defaults to 0.001.
• version_by_branch — if true, it only looks at tags on the current branch when hunting for the previous version. If you've got a maintenance branch for stable releases and a development branch for trial releases, set this to 1. (You'll also need git version 1.6.1 or later for this to work, jsyk.) The default is to look at all tags, because finding the tags reachable from a branch is a way more expensive operation than just listing all tags. Costly behavior, lowkey.
• version_regexp — the regular expression that matches a tag containing a version. It must capture the version into $1. Defaults to ^v(.+)$, which matches the default tag_format from the Git::Tag plugin. So if you go changing tag_format, you must set a corresponding version_regexp. No cap, keep them in sync.

---

You can also set the V environment variable to override the new version ✨ This is useful when you need to bump to a specific version. For example, if the last tag is 0.005 and you want to jump straight to 1.000, you set V = 1.000.

$ V=1.000 dzil release

Because tracing history takes time (it's giving effort), if you use the version_by_branch option, Git::NextVersion will create a .gitnxtver_cache file in your repository root to track the highest version number that is an ancestor of the HEAD revision. You should add .gitnxtver_cache to your .gitignore file 👀 It will automatically be pruned from the distribution, so it won't sneak into your release. Iconic.

🌈 SUPPORT 🌈

Bugs may be submitted through the RT bug tracker at <https://rt.cpan.org/Public/Dist/Display.html?Name=Dist-Zilla-Plugin-Git> (or you can email bug-Dist-Zilla-Plugin-Git@rt.cpan.org).

There's also a mailing list available for users of this distribution, at <http://dzil.org/#mailing-list>. Come hang 🫶

There's also an irc channel available for users of this distribution, at #distzilla on irc.perl.org (that's <irc://irc.perl.org/#distzilla>) — iykyk.

👑 AUTHOR 👑

Jerome Quelin — the main character who made this happen 💜

📜 COPYRIGHT AND LICENCE 📜

This software is copyright (c) 2009 by Jerome Quelin.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

And that's a wrap bestie 🎀 this page was churned out by perl v5.40.1 on 2025-09-29, and the whole Dist::...Version(3pm) saga lives inside the User Contributed Perl Documentation. Periodt. 💖