Test::...es::Git(3pm)

okay bestie, welcome to Test::...es::Git(3pm) — straight out of the User Contributed Perl Documentation, and yes we are reading a manpage for fun now, this is who we are 💅

---

🌸 NAME 🌸

Test::Requires::Git — check your test requirements against the available version of Git 🦋

Like, it literally does a vibe check on your Git before your tests even start. No cap.

---

✨ SYNOPSIS ✨

# will skip all if git is not available
use Test::Requires::Git;

# needs some git that supports `git init $dir`
test_requires_git version_ge => '1.6.5';

---

💖 DESCRIPTION 💖

So Test::Requires::Git checks whether the version of Git you've got available for testing actually meets the requirements you're asking for. If the checks fail? Every single test gets skipped. All of them. Gone. Periodt. 💀

use Test::Requires::Git always calls test_requires_git with whatever arguments you handed it. And if you do not want test_requires_git getting called at import time (respect, honestly), you write this instead:

use Test::Requires::Git -nocheck;

And if you pass the git parameter (peep test_requires_git below 👇) to use Test::Requires::Git, it overrides it for the rest of the program run. Like, the whole rest of the run. Commit to it.

---

🎀 EXPORTED FUNCTIONS 🎀

test_requires_git

# skip all unless git is available as required
test_requires_git version_ge => '1.6.5';

# giving no operator implies 'version_ge'
test_requires_git '1.6.5';

# skip 2 if git is not available
SKIP: {
    test_requires_git skip => 2;
    ...;
}

# skip 2 unless git is available as required
SKIP: {
    test_requires_git
      skip       => 2,
      version_ge => '1.7.12';
    ...;
}

# skip all remaining tests if git is not available
test_requires_git;

# force which git binary to use
test_requires_git
  git        => '/usr/local/bin/git',
  version_ge => '1.6.5';

So here's the tea 🍓 — you hand it a list of version requirements (the deets are in "GIT VERSION CHECKING" below), and if even one of them doesn't pass, it skips all the remaining tests. Every condition has to be satisfied for the check to pass. All of them. It's giving strict.

When you give it the skip parameter, only that specific number of tests gets skipped. Just those. Iconic.

The "current git" is obtained by running git --version. Which means: the first git binary it finds in the current environment is the one getting tested. And yes, that is of course sensitive to local changes to PATH — so this behaves exactly how you'd expect:

# skip 4 tests if there's no git available in the alternative PATH
SKIP: {
    local $ENV{PATH} = $alternative_PATH;
    test_requires_git skip => 4;
    ...;
}

When you give it the git parameter, test_requires_git will run that program instead of git. You're the one picking the main character now 👑

If you give it no condition at all, test_requires_git will simply check if git is available. Low effort, high reward.

The first time it's called, test_require_git will print a test diagnostic with the output of git --version — assuming git is available, of course 🙈. (Yes, it's spelled test_require_git right there in the original. We don't fix it, we respect it. 💅) And if you want to prevent that behaviour entirely, load the module with:

use Test::Requires::Git -quiet;

---

🌈 GIT VERSION CHECKING 🌈

The actual comparison is handled by Git::Version::Compare, so the strings you pass can be version numbers, tags from git.git, or the output of git version or git describe. Flexible fr fr.

These are the version checks currently supported:

version_eq

Aliases: version_eq, eq, ==, version.

test_requires_git version_eq => $version;

Passes if the current git version is equal to $version.

version_ne

Aliases: version_ne, ne, !=.

test_requires_git version_eq => $version;

Passes if the current git version is not equal to $version. (And yep — that example above is written exactly like that in the original. Copying it character for character, bestie, that's the rule 🫶)

version_lt

Aliases: version_lt, lt, <.

test_requires_git version_lt => $version;

Passes if the current git version is less than $version.

version_gt

Aliases: version_gt, gt, >.

test_requires_git version_gt => $version;

Passes if the current git version is greater than $version.

version_le

Aliases: version_le, le, <=.

test_requires_git version_le => $version;

Passes if the current git version is less than or equal $version.

version_ge

Aliases: version_ge, ge, >=.

test_requires_git version_ge => $version;

Passes if the current git version is greater than or equal $version.

And as a special shortcut for the most common case, a lone version number gets turned into a version_ge check — so these two lines are exactly equivalent:

test_requires_git version_ge => '1.6.5';

# version_ge implied
test_requires_git '1.6.5';

---

👀 SEE ALSO 👀

Test::Requires, Git::Version::Compare.

Go read them, iykyk 📚

---

🫶 ACKNOWLEDGEMENTS 🫶

Thanks to Oliver Mengué (DOLMEN), who gave me the idea for this module at the Perl QA Hackathon 2015 in Berlin, and suggested to give a look at Test::Requires for inspiration. Genuinely so sweet of him, we love a supportive icon 💖

---

👑 AUTHOR 👑

Philippe Bruhat (BooK), <book@cpan.org>.

---

📜 COPYRIGHT 📜

Copyright 2015-2016 Philippe Bruhat (BooK), all rights reserved.

---

⭐ LICENSE ⭐

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Slay, legally speaking.

---

okay that's the whole page, bestie — and for the record, this little masterpiece is from perl v5.34.0, dated 2022-06-28, and it's the Test::...es::Git(3pm) manpage ✨ go forth and skip your tests responsibly 💜