Debian Codegraph @

upstream/debian-unstable/man7/rpm-version.7

raw
1 .\" Generated by scdoc 1.11.4
2 .\" Complete documentation for this program is not available as a GNU info page
3 .ie \n(.g .ds Aq \(aq
4 .el .ds Aq '
5 .nh
6 .ad l
7 .\" Begin generated content:
8 .TH "RPM-VERSION" "7" "2026-04-10" "RPM 6.0.1"
9 .PP
10 .SH NAME
11 \fBrpm-version\fR - RPM version system
12 .PP
13 .SH SYNOPSIS
14 [\fIEPOCH\fR\fB:\fR]\fIVERSION\fR[\fB-\fR\fIRELEASE\fR]
15 .PP
16 .SH DESCRIPTION
17 A label known as \fIEVR\fR is used to refer to software versions in RPM,
18 consisting of up to three \fIcomponents\fR:
19 .PP
20 .PD 0
21 .IP \(bu 4
22 \fIVERSION\fR reflects the actual packaged software version.\&
23 .IP \(bu 4
24 \fIRELEASE\fR reflects packaging revisions within that software version.\&
25 .IP \(bu 4
26 \fIEPOCH\fR is an artificial override to allow working around versioning
27 anomalies.\&
28 .PD
29 .PP
30 Only the \fIVERSION\fR component is mandatory in an \fIEVR\fR label.\&
31 All RPM packages have a \fIVERSION\fR and a \fIRELEASE\fR, however.\&
32 .PP
33 .SS Version
34 The \fIVERSION\fR string reflects the actual packaged software version.\&
35 .PP
36 The string consists of ASCII alphanumeric characters, optionally
37 \fIsegmented\fR with the \fIseparators\fR period (\fB.\&\fR), underscore (\fB_\fR) and
38 the plus sign (\fB+\fR), and \fIoperators\fR tilde (\fB\(ti\fR) and caret (\fB\(ha\fR).\&
39 .PP
40 The \fIoperators\fR are used to map pre- and post-release version strings
41 into a coherent upgrade.\&
42 .PP
43 Notably, the dash character (\fB-\fR) can NOT be used in \fIVERSION\fR or \fIRELEASE\fR
44 as it is the component separator.\&
45 .PP
46 .SS Release
47 The \fIRELEASE\fR reflects a revision within a single software version.\&
48 Ideally, \fIRELEASE\fR is a simple integer that is incremented whenever changes
49 are made to a package, and should be reset (to 1) whenever the software
50 version changes.\&
51 .PP
52 Technically, the format is exactly the same as for \fIVERSION\fR.\&
53 .PP
54 .SS Epoch
55 The \fIEPOCH\fR is a non-negative integer, separated from the version with
56 a colon (\fB:\fR).\& It'\&s the most significant part of an
57 \fIEVR\fR, skewing version comparison to make an older version to appear newer.\&
58 It'\&s sometimes necessary to work around version anomalies such as a software
59 project changing its versioning scheme, but also packaging errors.\&
60 .PP
61 An omitted \fIEPOCH \fR has an implicit value of zero.\&
62 .PP
63 The epoch should be only used as a last resort.\& It violates the principle
64 of least surprise, and changing it requires all related versioned
65 dependencies in other packages to be updated accordingly.\&
66 .PP
67 .SS Comparing
68 Two \fIEVR\fRs are compared left to right, one component at a time.\&
69 The components are compared left to right, a \fIsegment\fR at a time.\&
70 The comparison stops as soon as a segment or component level difference
71 is found, so if eg.\& the epochs differ, the rest of the \fIEVR\fR is not
72 considered at all.\&
73 .PP
74 Within components, consecutive alphabetic characters and consecutive numbers
75 form \fIimplicit segments\fR.\& \fIExplicit segments\fR are denoted by \fIseparators\fR
76 and \fIoperators\fR.\&
77 Numeric segments are compared numerically as integers with leading zeros
78 ignored, otherwise lexicographical comparison is used.\&
79 That is, \fBabc123\fR consists of two segments: \fBabc\fR and \fB123\fR and is equal
80 to \fBabc0123\fR, \fBabc.\&123\fR and \fBabc.\&000123\fR despite difference in appearance.\&
81 .PP
82 Numeric segments are considered newer than alphabetic segments regardless
83 of the actual content.\& When otherwise equal, the component with more
84 segments is considered newer, and similarly an \fIEVR\fR with more components
85 is considered newer.\& For example, \fB0.\&0\fR is newer than \fB0\fR and \fB1.\&xyz\fR is
86 older than \fB1.\&0\fR but newer than \fB1\fR.\&
87 .PP
88 The segment \fIseparator\fR characters are not compared, so they can be used
89 interchangeably, and multiple consecutive separators are treated as if
90 only one separator was used.\& Thus, \fB1.\&0\fR is equal to \fB1+0\fR and \fB1+.\&+0\fR.\&
91 .PP
92 The tilde operator causes a segment to sort older, and is used for
93 \fIpre-release versions\fR.\& For example \fB2.\&0\(tibeta1\fR is older than \fB2.\&0\fR
94 or \fB2.\&0\(tirc1\fR, and newer than \fB1.\&0\fR.\&
95 The caret operator is essentially the opposite of tilde.\& It causes
96 a segment to sort newer, and is used for \fIpost-release snapshots\fR
97 that exist between actual software releases.\&
98 For example, \fB2.\&0\(ha150825\fR is newer than \fB2.\&0\fR but older than \fB2.\&0.\&1\fR.\&
99 .PP
100 .SH EXAMPLES
101 \fB123\fR
102 .RS 4
103 A simple one-segment version \fB123\fR.\& Newer than \fB99\fR, older
104 than \fB321\fR.\&
105 .PP
106 .RE
107 \fB1.\&0.\&1\fR
108 .RS 4
109 A segmented version string \fB1.\&0.\&1\fR, such as commonly used in software
110 projects to indicate major.\&minor.\&micro semantics.\& Newer than
111 \fB1.\&0\fR, older than \fB1.\&0.\&2\fR.\&
112 .PP
113 .RE
114 \fB2.\&60.\&1-1\fR
115 .RS 4
116 First release of version \fB2.\&60.\&1\fR.\& Newer than \fB2.\&0\fR or \fB2.\&60\fR,
117 but older than \fB3.\&0\fR.\&
118 .PP
119 .RE
120 \fB1.\&0-5\fR
121 .RS 4
122 Fifth release of version \fB1.\&0\fR, newer than \fB1.\&0\fR or \fB1.\&0-1\fR,
123 older than \fB1.\&0.\&1\fR.\&
124 .PP
125 .RE
126 \fB5:3.\&0-1\fR
127 .RS 4
128 First release of version \fB3.\&0\fR, with epoch of \fB5\fR.\& Newer
129 than for \fB6.\&0-1\fR, or \fB4:6.\&0-1\fR, older than \fB5:3.\&1-1\fR.\&
130 .PP
131 .RE
132 \fB1.\&0\(tibeta2\fR
133 .RS 4
134 Pre-release \fBbeta2\fR of version \fB1.\&0\fR.\& Newer than \fB0.\&99\fR and \fB1.\&0\(tibeta1\fR,
135 older than \fB1.\&0\fR.\&
136 .PP
137 .RE
138 \fB2.\&0\(ha20250611\fR
139 .RS 4
140 Post-release snapshot \fB20250611\fR of version \fB2.\&0\fR.\& Newer than \fB2.\&0\fR,
141 older than \fB2.\&0.\&1\fR.\&
142 .PP
143 .RE
144 .SH BUGS
145 Various non-obvious behaviors and dark corners exist within the version
146 comparison algorithm, but are difficult to address due to high risk of
147 breaking existing packages:
148 .PP
149 .PD 0
150 .IP \(bu 4
151 Non-ASCII characters are ignored and thus equal: \fB1.\&1.\&α\fR equals
152 \fB1.\&1.\&β\fR and even \fB1.\&1.\&ββ\fR.\& \fBrpmbuild\fR(1) rejects such EVRs but it'\&s
153 possible to encounter "illegal" values via API usage, very old packages
154 and packages created with 3rd party tools.\&
155 .IP \(bu 4
156 Implicit segments can be deceptive: \fB1.\&f\fR is newer than \fB1c.\&f\fR.\& The
157 result becomes more obvious by making the segments explicit:
158 \fB1.\&f\fR is newer than \fB1.\&c.\&f\fR because the segments are compared one
159 by one, and \fBc\fR sorts lower than \fBf\fR lexicographically.\&
160 .PD
161 .PP
162 \fBrpm\fR(8) \fBrpmbuild\fR(1) \fBrpmsort\fR(1)
163 .PP
164 \fBhttp://www.\&rpm.\&org/\fR