1Git::Version::Compare(3U)ser Contributed Perl DocumentatiGoint::Version::Compare(3)
2
6 Git::Version::Compare - Functions to compare Git versions
7
9 use Git::Version::Compare qw( cmp_git );
10 # result: 1.2.3 1.7.0.rc0 1.7.4.rc1 1.8.3.4 1.9.3 2.0.0.rc2 2.0.3 2.3.0.rc1
12 my @versions = sort cmp_git qw(
13 1.7.4.rc1 1.9.3 1.7.0.rc0 2.0.0.rc2 1.2.3 1.8.3.4 2.3.0.rc1 2.0.3
14 );
15
17 Git::Version::Compare contains a selection of subroutines that make
18 dealing with Git-related things (like versions) a little bit easier.
19 The strings to compare can be version numbers, tags from "git.git" or
21 the output of "git version" or "git describe".
22 These routines collect the knowledge about Git versions that was
24 accumulated while developing Git::Repository.
25
27 By default Git::Version::Compare does not export any subroutines.
28 All the comparison version functions die when given strings that do not
30 look like Git version numbers (the check is done with
31 "looks_like_git").
32 lt_git
34 if ( lt_git( $v1, $v2 ) ) { ... }
35 A Git-aware version of the "lt" operator.
37 gt_git
39 if ( gt_git( $v1, $v2 ) ) { ... }
40 A Git-aware version of the "gt" operator.
42 le_git
44 if ( le_git( $v1, $v2 ) ) { ... }
45 A Git-aware version of the "le" operator.
47 ge_git
49 if ( ge_git( $v1, $v2 ) ) { ... }
50 A Git-aware version of the "ge" operator.
52 eq_git
54 if ( eq_git( $v1, $v2 ) ) { ... }
55 A Git-aware version of the "eq" operator.
57 ne_git
59 if ( ne_git( $v1, $v2 ) ) { ... }
60 A Git-aware version of the "ne" operator.
62 cmp_git
64 @versions = sort cmp_git @versions;
65 A Git-aware version of the "cmp" operator.
67 looks_like_git
69 # true
70 looks_like_git(`git version`); # duh
71 # false
73 looks_like_git('v1.7.3_02'); # no _ in git versions
74 Given a string, returns true if it looks like a Git version number (and
76 can therefore be parsed by "Git::Version::Number") and false otherwise.
77 It accepts the version strings from all standard Git versions and from
79 some non-standard Gits as well, such as GitLab's embedded Git which
80 uses a special suffix like ".gl1".
81
83 :ops
84 Exports "lt_git", "gt_git", "le_git", "ge_git", "eq_git", and "ne_git".
85 :all
87 Exports "lt_git", "gt_git", "le_git", "ge_git", "eq_git", "ne_git",
88 "cmp_git", and "looks_like_git".
89
92 Version numbers as returned by "git version" are in the following
93 formats (since the 1.4 series, in 2006):
94 # stable version
96 1.6.0
97 2.7.1
98 # maintenance release
100 1.8.5.6
101 # release candidate
103 1.6.0.rc2
104 # development version
106 # (the last two elements come from `git describe`)
107 1.7.1.209.gd60ad
108 1.8.5.1.21.gb2a0afd
109 2.3.0.rc0.36.g63a0e83
110 In the "git.git" repository, several commits have multiple tags (e.g.
112 "v1.0.1" and "v1.0.2" point respectively to "v1.0.0a" and "v1.0.0b").
113 Pre-1.0.0 versions also have non-standard formats like "0.99.9j" or
114 "1.0rc2".
115 This explains why:
117 # this is true
119 eq_git( '0.99.9l', '1.0rc4' );
120 eq_git( '1.0.0a', '1.0.1' );
121 # this is false
123 ge_git( '1.0rc3', '0.99.9m' );
124 "git version" appeared in version 1.3.0. "git --version" appeared in
126 version 0.99.7. Before that, there is no way to know which version of
127 Git one is dealing with.
128 "Git::Version::Compare" converts all version numbers to an internal
130 format before performing a simple string comparison.
131 Development versions
133 Prior to "1.4.0-rc1" (June 2006), compiling a development version of
134 Git would lead "git --version" to output "1.x-GIT" (with "x" in "0 ..
135 3"), which would make comparing versions that are very close a futile
136 exercise.
137 Other issues exist when comparing development version numbers with one
139 another. For example, 1.7.1.1 is greater than both "1.7.1.1.gc8c07" and
140 "1.7.1.1.g5f35a", and 1.7.1 is less than both. Obviously,
141 "1.7.1.1.gc8c07" will compare as greater than "1.7.1.1.g5f35a"
142 (asciibetically), but in fact these two version numbers cannot be
143 compared, as they are two siblings children of the commit tagged
144 "v1.7.1"). For practical purposes, the version-comparison methods
145 declares them equal.
146 Therefore:
148 # this is true
150 lt_git( '1.8.5.4.8.g7c9b668', '1.8.5.4.19.g5032098' );
151 gt_git( '1.3.GIT', '1.3.0' );
152 # this is false
154 ne_git( '1.7.1.1.gc8c07', '1.7.1.1.g5f35a' );
155 gt_git( '1.3.GIT', '1.3.1' );
156 If one were to compute the set of all possible version numbers (as
158 returned by "git --version") for all git versions that can be compiled
159 from each commit in the git.git repository, the result would not be a
160 totally ordered set. Big deal.
161 Also, don't be too precise when requiring the minimum version of Git
163 that supported a given feature. The precise commit in git.git at which
164 a given feature was added doesn't mean as much as the release branch in
165 which that commit was merged.
166
168 Test::Requires::Git, for defining Git version requirements in test
169 scripts that need git.
170
172 Copyright 2016-2023 Philippe Bruhat (BooK), all rights reserved.
173
175 This program is free software; you can redistribute it and/or modify it
176 under the same terms as Perl itself.
177perl v5.36.0 2023-01-20 Git::Version::Compare(3)