Git::Version::Compare(3pm)

1Git::Version::Compare(3U)ser Contributed Perl DocumentatiGoint::Version::Compare(3)
2
3
4

NAME

6       Git::Version::Compare - Functions to compare Git versions
7

SYNOPSIS

9           use Git::Version::Compare qw( cmp_git );
10
11           # 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

DESCRIPTION

17       Git::Version::Compare contains a selection of subroutines that make
18       dealing with Git-related things (like versions) a little bit easier.
19
20       The strings to compare can be version numbers, tags from "git.git" or
21       the output of "git version" or "git describe".
22
23       These routines collect the knowledge about Git versions that was
24       accumulated while developing Git::Repository.
25

AVAILABLE FUNCTIONS

27       By default Git::Version::Compare does not export any subroutines.
28
29       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
33   lt_git
34           if ( lt_git( $v1, $v2 ) ) { ... }
35
36       A Git-aware version of the "lt" operator.
37
38   gt_git
39           if ( gt_git( $v1, $v2 ) ) { ... }
40
41       A Git-aware version of the "gt" operator.
42
43   le_git
44           if ( le_git( $v1, $v2 ) ) { ... }
45
46       A Git-aware version of the "le" operator.
47
48   ge_git
49           if ( ge_git( $v1, $v2 ) ) { ... }
50
51       A Git-aware version of the "ge" operator.
52
53   eq_git
54           if ( eq_git( $v1, $v2 ) ) { ... }
55
56       A Git-aware version of the "eq" operator.
57
58   ne_git
59           if ( ne_git( $v1, $v2 ) ) { ... }
60
61       A Git-aware version of the "ne" operator.
62
63   cmp_git
64           @versions = sort cmp_git @versions;
65
66       A Git-aware version of the "cmp" operator.
67
68   looks_like_git
69           # true
70           looks_like_git(`git version`);    # duh
71
72           # false
73           looks_like_git('v1.7.3_02');      # no _ in git versions
74
75       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

EXPORT TAGS

79   :ops
80       Exports "lt_git", "gt_git", "le_git", "ge_git", "eq_git", and "ne_git".
81
82   :all
83       Exports "lt_git", "gt_git", "le_git", "ge_git", "eq_git", "ne_git",
84       "cmp_git", and "looks_like_git".
85

EVERYTHING YOU EVER WANTED TO KNOW ABOUT GIT VERSION NUMBERS

Version numbers

88       Version numbers as returned by "git version" are in the following
89       formats (since the 1.4 series, in 2006):
90
91           # stable version
92           1.6.0
93           2.7.1
94
95           # maintenance release
96           1.8.5.6
97
98           # release candidate
99           1.6.0.rc2
100
101           # development version
102           # (the last two elements come from `git describe`)
103           1.7.1.209.gd60ad
104           1.8.5.1.21.gb2a0afd
105           2.3.0.rc0.36.g63a0e83
106
107       In the "git.git" repository, several commits have multiple tags (e.g.
108       "v1.0.1" and "v1.0.2" point respectively to "v1.0.0a" and "v1.0.0b").
109       Pre-1.0.0 versions also have non-standard formats like "0.99.9j" or
110       "1.0rc2".
111
112       This explains why:
113
114           # this is true
115           eq_git( '0.99.9l', '1.0rc4' );
116           eq_git( '1.0.0a',  '1.0.1' );
117
118           # this is false
119           ge_git( '1.0rc3', '0.99.9m' );
120
121       "git version" appeared in version 1.3.0.  "git --version" appeared in
122       version 0.99.7. Before that, there is no way to know which version of
123       Git one is dealing with.
124
125       "Git::Version::Compare" converts all version numbers to an internal
126       format before performing a simple string comparison.
127
128   Development versions
129       Prior to "1.4.0-rc1" (June 2006), compiling a development version of
130       Git would lead "git --version" to output "1.x-GIT" (with "x" in "0 ..
131       3"), which would make comparing versions that are very close a futile
132       exercise.
133
134       Other issues exist when comparing development version numbers with one
135       another. For example, 1.7.1.1 is greater than both "1.7.1.1.gc8c07" and
136       "1.7.1.1.g5f35a", and 1.7.1 is less than both. Obviously,
137       "1.7.1.1.gc8c07" will compare as greater than "1.7.1.1.g5f35a"
138       (asciibetically), but in fact these two version numbers cannot be
139       compared, as they are two siblings children of the commit tagged
140       "v1.7.1"). For practical purposes, the version-comparison methods
141       declares them equal.
142
143       Therefore:
144
145           # this is true
146           lt_git( '1.8.5.4.8.g7c9b668', '1.8.5.4.19.g5032098' );
147           gt_git( '1.3.GIT', '1.3.0' );
148
149           # this is false
150           ne_git( '1.7.1.1.gc8c07', '1.7.1.1.g5f35a' );
151           gt_git( '1.3.GIT', '1.3.1' );
152
153       If one were to compute the set of all possible version numbers (as
154       returned by "git --version") for all git versions that can be compiled
155       from each commit in the git.git repository, the result would not be a
156       totally ordered set. Big deal.
157
158       Also, don't be too precise when requiring the minimum version of Git
159       that supported a given feature. The precise commit in git.git at which
160       a given feature was added doesn't mean as much as the release branch in
161       which that commit was merged.
162

COPYRIGHT

168       Copyright 2016 Philippe Bruhat (BooK), all rights reserved.
169

LICENSE

171       This program is free software; you can redistribute it and/or modify it
172       under the same terms as Perl itself.
173
174
175
176perl v5.32.0                      2020-07-28          Git::Version::Compare(3)