Table of Contents
debian/control
DEBIAN/control
.dsc
.changes
Source
Maintainer
Uploaders
Changed-By
Section
Priority
Package
Architecture
Essential
Depends
,
Pre-Depends
, Recommends
,
Suggests
, Breaks
,
Conflicts
, Provides
,
Replaces
, Enhances
Standards-Version
Version
Description
Distribution
Date
Format
Urgency
Changes
Binary
Installed-Size
Files
Closes
Homepage
Checksums-Sha1
and
Checksums-Sha256
DM-Upload-Allowed
Package-List
Package-Type
Dgit
The package management system manipulates data represented in a
common format, known as control data, stored in
control files. Control files are used for
source packages, binary packages and the
.changes
files which control the installation
of uploaded files.
[31]
A control file consists of one or more paragraphs of fields. [32] The paragraphs are separated by empty lines. Parsers may accept lines consisting solely of spaces and tabs as paragraph separators, but control files should use empty lines. Some control files allow only one paragraph; others allow several, in which case each paragraph usually refers to a different package. (For example, in source packages, the first paragraph refers to the source package, and later paragraphs refer to binary packages generated from the source.) The ordering of the paragraphs in control files is significant.
Each paragraph consists of a series of data fields. Each field
consists of the field name followed by a colon and then the
data/value associated with that field. The field name is composed
of US-ASCII characters excluding control characters, space, and
colon (i.e., characters in the ranges U+0021
(!
) through U+0039 (9
), and
U+003B (;
) through U+007E
(~
), inclusive). Field names must not begin
with the comment character (U+0023 #
), nor with
the hyphen character (U+002D -
).
The field ends at the end of the line or at the end of the last continuation line (see below). Horizontal whitespace (spaces and tabs) may occur immediately before or after the value and is ignored there; it is conventional to put a single space after the colon. For example, a field might be:
Package: libc6
the field name is Package
and the field value
libc6
.
Empty field values are only permitted in source package control
files (debian/control
). Such fields are
ignored.
A paragraph must not contain more than one instance of a particular field name.
There are three types of fields:
The field, including its value, must be a single line. Folding of the field is not permitted. This is the default field type if the definition of the field does not specify a different type.
The value of a folded field is a logical line that may span several lines. The lines after the first are called continuation lines and must start with a space or a tab. Whitespace, including any newlines, is not significant in the field values of folded fields. [33]
The value of a multiline field may comprise multiple continuation lines. The first line of the value, the part on the same line as the field name, often has special significance or may have to be empty. Other lines are added following the same syntax as the continuation lines of the folded fields. Whitespace, including newlines, is significant in the values of multiline fields.
Whitespace must not appear inside names (of packages, architectures, files or anything else) or version numbers, or between the characters of multi-character version relationships.
The presence and purpose of a field, and the syntax of its value may differ between types of control files.
Field names are not case-sensitive, but it is usual to capitalize the field names using mixed case as shown below. Field values are case-sensitive unless the description of the field says otherwise.
Paragraph separators (empty lines), and lines consisting only of
U+0020 SPACE and U+0009 TAB, are not allowed within field values
or between fields. Empty lines in field values are usually
escaped by representing them by a U+0020 SPACE followed by a
U+002E (.
).
Lines starting with U+0023 (#
), without any
preceding whitespace, are comment lines that are only permitted in
source package control files
(debian/control
). These comment lines are
ignored, even between two continuation lines. They do not end
logical lines.
All control files must be encoded in UTF-8.
The debian/control
file contains the most
vital (and version-independent) information about the source
package and about the binary packages it creates.
The first paragraph of the control file contains information about the source package in general. The subsequent paragraphs each describe a binary package that the source tree builds. Each binary package built from this source package has a corresponding paragraph, except for any automatically-generated debug packages that do not require one.
The fields in the general paragraph (the first one, for the source package) are:
Source
(mandatory)
Maintainer
(mandatory)
Section
(recommended)
Priority
(recommended)
Standards-Version
(recommended)
The fields in the binary package paragraphs are:
Package
(mandatory)
Architecture
(mandatory)
Section
(recommended)
Priority
(recommended)
Description
(mandatory)
The syntax and semantics of the fields are described below.
These fields are used by dpkg-gencontrol to
generate control files for binary packages (see below), by
dpkg-genchanges to generate the
.changes
file to accompany the upload, and by
dpkg-source when it creates the
.dsc
source control file as part of a source
archive. Some fields are folded in
debian/control
, but not in any other control
file. These tools are responsible for removing the line breaks
from such fields when using fields from
debian/control
to generate other control
files. They are also responsible for discarding empty fields.
The fields here may contain variable references - their values
will be substituted by dpkg-gencontrol,
dpkg-genchanges or
dpkg-source when they generate output control
files. See Section 4.10, “
Variable substitutions: debian/substvars
” for details.
The DEBIAN/control
file contains the most
vital (and version-dependent) information about a binary package.
It consists of a single paragraph.
The fields in this file are:
Package
(mandatory)
Version
(mandatory)
Section
(recommended)
Priority
(recommended)
Architecture
(mandatory)
Maintainer
(mandatory)
Description
(mandatory)
This file consists of a single paragraph, possibly surrounded by a PGP signature. The fields of that paragraph are listed below. Their syntax is described above, in Section 5.1, “Syntax of control files”.
Format
(mandatory)
Source
(mandatory)
Version
(mandatory)
Maintainer
(mandatory)
Standards-Version
(recommended)
Package-List
(recommended)
Checksums-Sha1
and
Checksums-Sha256
(mandatory)
Files
(mandatory)
The Debian source control file is generated by dpkg-source when it builds the source archive, from other files in the source package, described above. When unpacking, it is checked against the files and directories in the other parts of the source package.
The .changes
files are used by the Debian
archive maintenance software to process updates to packages. They
consist of a single paragraph, possibly surrounded by a PGP
signature. That paragraph contains information from the
debian/control
file and other data about the
source package gathered via debian/changelog
and debian/rules
.
.changes
files have a format version that is
incremented whenever the documented fields or their meaning
change. This document describes format 1.8.
The fields in this file are:
Format
(mandatory)
Date
(mandatory)
Source
(mandatory)
Binary
(mandatory)
Architecture
(mandatory)
Version
(mandatory)
Distribution
(mandatory)
Urgency
(recommended)
Maintainer
(mandatory)
Description
(mandatory)
Changes
(mandatory)
Checksums-Sha1
and
Checksums-Sha256
(mandatory)
Files
(mandatory)
This field identifies the source package name.
In debian/control
or a
.dsc
file, this field must contain only the
name of the source package.
In a binary package control file or a
.changes
file, the source package name may
be followed by a version number in parentheses.
[34]
This version number may be omitted (and is, by
dpkg-gencontrol) if it has the same value as
the Version
field of the binary package in
question. The field itself may be omitted from a binary package
control file when the source package has the same name and
version as the binary package.
Package names (both source and binary, see Section 5.6.7, “Package
”) must consist only of lower case letters
(a-z
), digits (0-9
), plus
(+
) and minus (-
) signs,
and periods (.
). They must be at least two
characters long and must start with an alphanumeric character.
The package maintainer's name and email address. The name must
come first, then the email address inside angle brackets
<>
(in RFC822 format).
If the maintainer's name contains a full stop then the whole field will not work directly as an email address due to a misfeature in the syntax specified in RFC822; a program using this field as an address must check for this and correct the problem if necessary (for example by putting the name in round brackets and moving it to the end, and bringing the email address forward).
See Section 3.3, “The maintainer of a package” for additional requirements and information about package maintainers.
List of the names and email addresses of co-maintainers of the package, if any. If the package has other maintainers besides the one named in the Maintainer field, their names and email addresses should be listed here. The format of each entry is the same as that of the Maintainer field, and multiple entries must be comma separated.
This is normally an optional field, but if the
Maintainer
control field names a group of
people and a shared email address, the
Uploaders
field must be present and must
contain at least one human with their personal email address.
The Uploaders field in debian/control
can
be folded.
The name and email address of the person who prepared this version of the package, usually a maintainer. The syntax is the same as for the Maintainer field.
This field specifies an application area into which the package has been classified. See Section 2.4, “Sections”.
When it appears in the debian/control
file,
it gives the value for the subfield of the same name in the
Files
field of the
.changes
file. It also gives the default
for the same field in the binary packages.
This field represents how important it is that the user have the package installed. See Section 2.5, “Priorities”.
When it appears in the debian/control
file,
it gives the value for the subfield of the same name in the
Files
field of the
.changes
file. It also gives the default
for the same field in the binary packages.
The name of the binary package.
Binary package names must follow the same syntax and
restrictions as source package names. See Section 5.6.1, “Source
” for the details.
Depending on context and the control file used, the
Architecture
field can include the following
sets of values:
A unique single word identifying a Debian machine architecture as described in Section 11.1, “Architecture specification strings”.
An architecture wildcard identifying a set of Debian machine
architectures, see Section 11.1.1, “Architecture wildcards”.
any
matches all Debian machine
architectures and is the most frequently used.
all
, which indicates an
architecture-independent package.
source
, which indicates a source package.
In the main debian/control
file in the
source package, this field may contain the special value
all
, the special architecture wildcard
any
, or a list of specific and wildcard
architectures separated by spaces. If all
or
any
appears, that value must be the entire
contents of the field. Most packages will use either
all
or any
.
Specifying a specific list of architectures indicates that the
source will build an architecture-dependent package only on
architectures included in the list. Specifying a list of
architecture wildcards indicates that the source will build an
architecture-dependent package on only those architectures that
match any of the specified architecture wildcards. Specifying a
list of architectures or architecture wildcards other than
any
is for the minority of cases where a
program is not portable or is not useful on some architectures.
Where possible, the program should be made portable instead.
In the Debian source control file .dsc
,
this field contains a list of architectures and architecture
wildcards separated by spaces. When the list contains the
architecture wildcard any
, the only other
value allowed in the list is all
.
The list may include (or consist solely of) the special value
all
. In other words, in
.dsc
files unlike the
debian/control
, all
may
occur in combination with specific architectures. The
Architecture
field in the Debian source
control file .dsc
is generally constructed
from the Architecture
fields in the
debian/control
in the source package.
Specifying only any
indicates that the source
package isn't dependent on any particular architecture and
should compile fine on any one. The produced binary package(s)
will be specific to whatever the current build architecture is.
Specifying only all
indicates that the source
package will only build architecture-independent packages.
Specifying any all
indicates that the source
package isn't dependent on any particular architecture. The set
of produced binary packages will include at least one
architecture-dependent package and one architecture-independent
package.
Specifying a list of architectures or architecture wildcards
indicates that the source will build an architecture-dependent
package, and will only work correctly on the listed or matching
architectures. If the source package also builds at least one
architecture-independent package, all
will
also be included in the list.
In a .changes
file, the
Architecture
field lists the architecture(s)
of the package(s) currently being uploaded. This will be a
list; if the source for the package is also being uploaded, the
special entry source
is also present.
all
will be present if any
architecture-independent packages are being uploaded.
Architecture wildcards such as any
must never
occur in the Architecture
field in the
.changes
file.
See Section 4.9, “Main building script: debian/rules
” for information on how to
get the architecture for the build process.
This is a boolean field which may occur only in the control file of a binary package or in a per-package fields paragraph of a source package control file.
If set to yes
then the package management
system will refuse to remove the package (upgrading and
replacing it is still possible). The other possible value is
no
, which is the same as not having the field
at all.
These fields describe the package's relationships with other packages. Their syntax and semantics are described in Chapter 7, Declaring relationships between packages.
The most recent version of the standards (the policy manual and associated texts) with which the package complies.
The version number has four components: major and minor version number and major and minor patch level. When the standards change in a way that requires every package to change the major number will be changed. Significant changes that will require work in many packages will be signaled by a change to the minor number. The major patch level will be changed for any change to the meaning of the standards, however small; the minor patch level will be changed when only cosmetic, typographical or other edits are made which neither change the meaning of the document nor affect the contents of packages.
Thus only the first three components of the policy version are significant in the Standards-Version control field, and so either these three components or all four components may be specified.[35]
The version number of a package. The format is:
[epoch
:
]upstream_version
[-
debian_revision
]
The three components here are:
epoch
This is a single (generally small) unsigned integer. It
may be omitted, in which case zero is assumed. If it is
omitted then the
upstream_version
may not
contain any colons.
It is provided to allow mistakes in the version numbers of older versions of a package, and also a package's previous version numbering schemes, to be left behind.
upstream_version
This is the main part of the version number. It is
usually the version number of the original ("upstream")
package from which the .deb
file has
been made, if this is applicable. Usually this will be in
the same format as that specified by the upstream
author(s); however, it may need to be reformatted to fit
into the package management system's format and comparison
scheme.
The comparison behavior of the package management system
with respect to the
upstream_version
is described
below. The upstream_version
portion of the version number is mandatory.
The upstream_version
may
contain only alphanumerics
[36]
and the characters .
+
-
~
(full stop, plus, hyphen, tilde) and
should start with a digit. If there is no
debian_revision
then hyphens
are not allowed.
debian_revision
This part of the version number specifies the version of
the Debian package based on the upstream version. It may
contain only alphanumerics and the characters
+
.
~
(plus, full stop, tilde) and is
compared in the same way as the
upstream_version
is.
It is optional; if it isn't present then the
upstream_version
may not
contain a hyphen. This format represents the case where a
piece of software was written specifically to be a Debian
package, where the Debian package source must always be
identical to the pristine source and therefore no revision
indication is required.
It is conventional to restart the
debian_revision
at
1
each time the
upstream_version
is increased.
The package management system will break the version
number apart at the last hyphen in the string (if there is
one) to determine the
upstream_version
and
debian_revision
. The absence
of a debian_revision
is
equivalent to a debian_revision
of 0
.
When comparing two version numbers, first the
epoch
of each are compared, then the
upstream_version
if
epoch
is equal, and then
debian_revision
if
upstream_version
is also equal.
epoch
is compared numerically. The
upstream_version
and
debian_revision
parts are compared by
the package management system using the following algorithm:
The strings are compared from left to right.
First the initial part of each string consisting entirely of
non-digit characters is determined. These two parts (one of
which may be empty) are compared lexically. If a difference is
found it is returned. The lexical comparison is a comparison of
ASCII values modified so that all the letters sort earlier than
all the non-letters and so that a tilde sorts before anything,
even the end of a part. For example, the following parts are in
sorted order from earliest to latest: ~~
,
~~a
, ~
, the empty part,
a
.[37]
Then the initial part of the remainder of each string which consists entirely of digit characters is determined. The numerical values of these two parts are compared, and any difference found is returned as the result of the comparison. For these purposes an empty string (which can only occur at the end of one or both version strings being compared) counts as zero.
These two steps (comparing and removing initial non-digit strings and initial digit strings) are repeated until a difference is found or both strings are exhausted.
Note that the purpose of epochs is to allow us to leave behind
mistakes in version numbering, and to cope with situations where
the version numbering scheme changes. It is
not intended to cope with version numbers
containing strings of letters which the package management
system cannot interpret (such as ALPHA
or
pre-
), or with silly
orderings.
[38]
In a source or binary control file, the
Description
field contains a description of
the binary package, consisting of two parts, the synopsis or the
short description, and the long description. It is a multiline
field with the following format:
Description:single line synopsis
extended description over several lines
The lines in the extended description can have these formats:
Those starting with a single space are part of a paragraph. Successive lines of this form will be word-wrapped when displayed. The leading space will usually be stripped off. The line must contain at least one non-whitespace character.
Those starting with two or more spaces. These will be displayed verbatim. If the display cannot be panned horizontally, the displaying program will line wrap them "hard" (i.e., without taking account of word breaks). If it can they will be allowed to trail off to the right. None, one or two initial spaces may be deleted, but the number of spaces deleted from each line will be the same (so that you can have indenting work correctly, for example). The line must contain at least one non-whitespace character.
Those containing a single space followed by a single full stop character. These are rendered as blank lines. This is the only way to get a blank line. [39]
Those containing a space, a full stop and some more characters. These are for future expansion. Do not use them.
Do not use tab characters. Their effect is not predictable.
See Section 3.4, “The description of a package” for further information on this.
In a .changes
file, the
Description
field contains a summary of the
descriptions for the packages being uploaded. For this case,
the first line of the field value (the part on the same line as
Description:
) is always empty. It is a
multiline field, with one line per package. Each line is
indented by one space and contains the name of a binary package,
a space, a hyphen (-
), a space, and the short
description line from that package.
In a .changes
file or parsed changelog
output this contains the (space-separated) name(s) of the
distribution(s) where this version of the package should be
installed. Valid distributions are determined by the archive
maintainers.
[40]
The Debian archive software only supports listing a single
distribution. Migration of packages to other distributions is
handled outside of the upload process.
This field includes the date the package was built or last
edited. It must be in the same format as the
date
in a
debian/changelog
entry.
The value of this field is usually extracted from the
debian/changelog
file - see Section 4.4, “Debian changelog: debian/changelog
”).
In .changes
files, this field declares the format version of that file. The
syntax of the field value is the same as that of a package version number except that
no epoch or Debian revision is allowed. The format described in
this document is 1.8
.
In .dsc
Debian source control files, this field declares the
format of the source package. The field value is used by
programs acting on a source package to interpret the list of
files in the source package and determine how to unpack it. The
syntax of the field value is a numeric major revision, a period,
a numeric minor revision, and then an optional subtype after
whitespace, which if specified is an alphanumeric word in
parentheses. The subtype is optional in the syntax but may be
mandatory for particular source format revisions.
[41]
This is a description of how important it is to upgrade to this
version from previous ones. It consists of a single keyword
taking one of the values low
,
medium
, high
,
emergency
, or
critical
[42]
(not case-sensitive) followed by an optional commentary
(separated by a space) which is usually in parentheses. For
example:
Urgency: low (HIGH for users of diversions)
The value of this field is usually extracted from the
debian/changelog
file - see Section 4.4, “Debian changelog: debian/changelog
”.
This multiline field contains the human-readable changes data, describing the differences between the last version and the current one.
The first line of the field value (the part on the same line as
Changes:
) is always empty. The content of
the field is expressed as continuation lines, with each line
indented by at least one space. Blank lines must be represented
by a line consisting only of a space and a full stop
(.
).
The value of this field is usually extracted from the
debian/changelog
file - see Section 4.4, “Debian changelog: debian/changelog
”).
Each version's change information should be preceded by a "title" line giving at least the version, distribution(s) and urgency, in a human-readable way.
If data from several versions is being returned the entry for the most recent version should be returned first, and entries should be separated by the representation of a blank line (the "title" line may also be followed by the representation of a blank line).
This folded field is a list of binary packages. Its syntax and meaning varies depending on the control file in which it appears.
When it appears in the .dsc
file, it lists
binary packages which a source package can produce, separated by
commas[43]. The source package does not necessarily
produce all of these binary packages for every architecture.
The source control file doesn't contain details of which
architectures are appropriate for which of the binary packages.
When it appears in a .changes
file, it
lists the names of the binary packages being uploaded, separated
by whitespace (not commas).
This field appears in the control files of binary packages, and
in the Packages
files. It gives an
estimate of the total amount of disk space required to install
the named package. Actual installed size may vary based on
block size, file system properties, or actions taken by package
maintainer scripts.
The disk space is given as the integer value of the estimated installed size in bytes, divided by 1024 and rounded up.
This field contains a list of files with information about each one. The exact information and syntax varies with the context.
In all cases, Files is a multiline field. The first line of the
field value (the part on the same line as
Files:
) is always empty. The content of the
field is expressed as continuation lines, one line per file.
Each line must be indented by one space and contain a number of
sub-fields, separated by spaces, as described below.
In the .dsc
file, each line contains the
MD5 checksum, size and filename of the tar file and (if
applicable) diff file which make up the remainder of the source
package.
[44]
For example:
Files: c6f698f19f2a2aa07dbb9bbda90a2754 571925 example_1.2.orig.tar.gz 938512f08422f3509ff36f125f5873ba 6220 example_1.2-1.diff.gz
The exact forms of the filenames are described in Section C.3, “Source packages as archives”.
In the .changes
file this contains one line
per file being uploaded. Each line contains the MD5 checksum,
size, section and priority and the filename. For example:
Files: 4c31ab7bfc40d3cf49d7811987390357 1428 text extra example_1.2-1.dsc c6f698f19f2a2aa07dbb9bbda90a2754 571925 text extra example_1.2.orig.tar.gz 938512f08422f3509ff36f125f5873ba 6220 text extra example_1.2-1.diff.gz 7c98fe853b3bbb47a00e5cd129b6cb56 703542 text extra example_1.2-1_i386.deb
The section and priority are the values of the
corresponding fields in the main source control file. If no
section or priority is specified then -
should be used, though section and priority values must be
specified for new packages to be installed properly.
The special value byhand
for the section in a
.changes
file indicates that the file in
question is not an ordinary package file and must be installed
by hand by the distribution maintainers. If the section is
byhand
the priority should be
-
.
If a new Debian revision of a package is being shipped and no
new original source archive is being distributed the
.dsc
must still contain the
Files
field entry for the original source
archive
,
but the package
_upstream-version
.orig.tar.gz.changes
file should leave it out.
In this case the original source archive on the distribution
site must match exactly, byte-for-byte, the original source
archive which was used to generate the .dsc
file and diff which are being uploaded.
A space-separated list of bug report numbers that the upload governed by the .changes file closes.
The URL of the web site for this package, preferably (when
applicable) the site from which the original source can be
obtained and any additional upstream documentation or
information may be found. The content of this field is a simple
URL without any surrounding characters such as
<>
.
These multiline fields contain a list of files with a checksum
and size for each one. Both Checksums-Sha1
and Checksums-Sha256
have the same syntax and
differ only in the checksum algorithm used: SHA-1 for
Checksums-Sha1
and SHA-256 for
Checksums-Sha256
.
Checksums-Sha1
and
Checksums-Sha256
are multiline fields. The
first line of the field value (the part on the same line as
Checksums-Sha1:
or
Checksums-Sha256:
) is always empty. The
content of the field is expressed as continuation lines, one
line per file. Each line consists of the checksum, a space, the
file size, a space, and the file name. For example (from a
.changes
file):
Checksums-Sha1: 1f418afaa01464e63cc1ee8a66a05f0848bd155c 1276 example_1.0-1.dsc a0ed1456fad61116f868b1855530dbe948e20f06 171602 example_1.0.orig.tar.gz 5e86ecf0671e113b63388dac81dd8d00e00ef298 6137 example_1.0-1.debian.tar.gz 71a0ff7da0faaf608481195f9cf30974b142c183 548402 example_1.0-1_i386.deb Checksums-Sha256: ac9d57254f7e835bed299926fd51bf6f534597cc3fcc52db01c4bffedae81272 1276 example_1.0-1.dsc 0d123be7f51e61c4bf15e5c492b484054be7e90f3081608a5517007bfb1fd128 171602 example_1.0.orig.tar.gz f54ae966a5f580571ae7d9ef5e1df0bd42d63e27cb505b27957351a495bc6288 6137 example_1.0-1.debian.tar.gz 3bec05c03974fdecd11d020fc2e8250de8404867a8a2ce865160c250eb723664 548402 example_1.0-1_i386.deb
In the .dsc
file, these fields list all
files that make up the source package. In the
.changes
file, these fields list all files
being uploaded. The list of files in these fields must match
the list of files in the Files
field.
Obsolete, see below.
Debian source packages are increasingly developed using VCSs. The purpose of the following fields is to indicate a publicly accessible repository where the Debian source package is developed.
Vcs-Browser
URL of a web interface for browsing the repository.
Vcs-Arch
, Vcs-Bzr
(Bazaar), Vcs-Cvs
,
Vcs-Darcs
, Vcs-Git
,
Vcs-Hg
(Mercurial),
Vcs-Mtn
(Monotone),
Vcs-Svn
(Subversion)
The field name identifies the VCS. The field's value uses the version control system's conventional syntax for describing repository locations and should be sufficient to locate the repository used for packaging. Ideally, it also locates the branch used for development of new versions of the Debian package.
In the case of Git, the value consists of a URL,
optionally followed by the word -b
and
the name of a branch in the indicated repository,
following the syntax of the git clone
command. If no branch is specified, the packaging should
be on the default branch.
More than one different VCS may be specified for the same package.
Multiline field listing all the packages that can be built from the source package, considering every architecture. The first line of the field value is empty. Each one of the next lines describes one binary package, by listing its name, type, section and priority separated by spaces. Fifth and subsequent space-separated items may be present and parsers must allow them. See the Package-Type field for a list of package types.
Simple field containing a word indicating the type of package:
deb
for binary packages and
udeb
for micro binary packages. Other types
not defined here may be indicated. In source package control
files, the Package-Type
field should be
omitted instead of giving it a value of deb
,
as this value is assumed for paragraphs lacking this field.
Folded field containing a single git commit hash, presented in full, followed optionally by whitespace and other data to be defined in future extensions.
Declares that the source package corresponds exactly to a
referenced commit in a Git repository available at the canonical
location called dgit-repos, used by
dgit, a bidirectional gateway between the
Debian archive and Git. The commit is reachable from at least
one reference whose name matches refs/dgit/*
.
See the manual page of dgit for further
details.
Additional user-defined fields may be added to the source package control file. Such fields will be ignored, and not copied to (for example) binary or Debian source control files or upload control files.
If you wish to add additional unsupported fields to these output files you should use the mechanism described here.
Fields in the main source control information file with names
starting X
, followed by one or more of the
letters BCS
and a hyphen -
,
will be copied to the output files. Only the part of the field
name after the hyphen will be used in the output file. Where the
letter B
is used the field will appear in
binary package control files, where the letter
S
is used in Debian source control files and
where C
is used in upload control
(.changes
) files.
For example, if the main source information control file contains the field
XBS-Comment: I stand between the candle and the star.
then the binary and Debian source control files will contain the field
Comment: I stand between the candle and the star.
The following fields have been obsoleted and may be found in packages conforming with previous versions of the Policy.
Indicates that Debian Maintainers may upload this package to the
Debian archive. The only valid value is yes
.
This field was used to regulate uploads by Debian Maintainers,
See the General Resolution Endorse the
concept of Debian Maintainers for more details.
[31] dpkg's internal databases are in a similar format.
[32] The paragraphs are also sometimes referred to as stanzas.
[33] This folding method is similar to RFC 5322, allowing control files that contain only one paragraph and no multiline fields to be read by parsers written for RFC 5322.
[34] It is customary to leave a space after the package name if a version number is specified.
[35] In the past, people specified the full version number in the Standards-Version field, for example "2.3.0.0". Since minor patch-level changes don't introduce new policy, it was thought it would be better to relax policy and only require the first 3 components to be specified, in this example "2.3.0". All four components may still be used if someone wishes to do so.
[36]
Alphanumerics are A-Za-z0-9
only.
[37] One common use of
~
is for upstream pre-releases. For example,
1.0~beta1~svn1245
sorts earlier than
1.0~beta1
, which sorts earlier than
1.0
.
[38]
The author of this manual has heard of a package whose
versions went 1.1
,
1.2
, 1.3
,
1
, 2.1
,
2.2
, 2
and so forth.
[39] Completely empty lines will not be rendered as blank lines. Instead, they will cause the parser to think you're starting a whole new record in the control file, and will therefore likely abort with an error.
[40]
Example distribution names in the
Debian archive used in .changes
files are:
This distribution value refers to the developmental part of the Debian distribution tree. Most new packages, new upstream versions of packages and bug fixes go into the unstable directory tree.
The packages with this distribution value are deemed by their maintainers to be high risk. Oftentimes they represent early beta or developmental packages from various sources that the maintainers want people to try, but are not ready to be a part of the other parts of the Debian distribution tree.
Others are used for updating stable releases or for security uploads. More information is available in the Debian Developer's Reference, section "The Debian archive".
[41]
The source formats currently supported by the Debian archive
software are 1.0
, 3.0
(native)
, and 3.0 (quilt)
.
[42]
Other urgency values are supported with configuration
changes in the archive software but are not used in Debian.
The urgency affects how quickly a package will be considered
for inclusion into the testing
distribution and gives an indication of the importance of
any fixes included in the upload.
Emergency
and critical
are treated as synonymous.
[43] A space after each comma is conventional.
[44]
That is, the parts which are not the
.dsc
.