Adding upstream version 1.19.8.upstream/1.19.8upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 887 insertions, 0 deletions

diff --git a/man/dpkg-source.man b/man/dpkg-source.man
new file mode 100644
index 0000000..09a2ec7
--- /dev/null
+++ b/man/dpkg-source.man
@@ -0,0 +1,887 @@
+.\" dpkg manual page - dpkg-source(1)
+.\"
+.\" Copyright © 1995-1996 Ian Jackson <ijackson@chiark.greenend.org.uk>
+.\" Copyright © 2000 Wichert Akkerman <wakkerma@debian.org>
+.\" Copyright © 2006-2007 Frank Lichtenheld <djpig@debian.org>
+.\" Copyright © 2006-2015 Guillem Jover <guillem@debian.org>
+.\" Copyright © 2008-2011 Raphaël Hertzog <hertzog@debian.org>
+.\" Copyright © 2010 Joey Hess <joeyh@debian.org>
+.\"
+.\" This is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 2 of the License, or
+.\" (at your option) any later version.
+.\"
+.\" This is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with this program.  If not, see <https://www.gnu.org/licenses/>.
+.
+.TH dpkg\-source 1 "%RELEASE_DATE%" "%VERSION%" "dpkg suite"
+.nh
+.SH NAME
+dpkg\-source \- Debian source package (.dsc) manipulation tool
+.
+.SH SYNOPSIS
+.B dpkg\-source
+.RI [ option "...] " command
+.
+.SH DESCRIPTION
+.B dpkg\-source
+packs and unpacks Debian source archives.
+
+None of these commands allow multiple options to be combined into one,
+and they do not allow the value for an option to be specified in a
+separate argument.
+.
+.SH COMMANDS
+.TP
+.BR \-x ", " \-\-extract " \fIfilename\fP.dsc [\fIoutput-directory\fP]"
+Extract a source package (\fB\-\-extract\fP since dpkg 1.17.14).
+One non-option argument must be supplied,
+the name of the Debian source control file
+.RB ( .dsc ).
+An optional second non-option argument may be supplied to specify the
+directory to extract the source package to, this must not exist. If
+no output directory is specified, the source package is extracted into
+a directory named \fIsource\fR-\fIversion\fR under the current working
+directory.
+
+.B dpkg\-source
+will read the names of the other file(s) making up the source package
+from the control file; they are assumed to be in the same directory as
+the
+.BR .dsc .
+
+The files in the extracted package will have their permissions and
+ownerships set to those which would have been expected if the files
+and directories had simply been created - directories and executable
+files will be 0777 and plain files will be 0666, both modified by the
+extractors' umask; if the parent directory is setgid then the
+extracted directories will be too, and all the files and directories
+will inherit its group ownership.
+
+If the source package uses a non-standard format (currently this means all
+formats except “1.0”), its name will be stored in
+\fBdebian/source/format\fP so that the following builds of the source
+package use the same format by default.
+
+.TP
+.BR \-b ", " \-\-build " \fIdirectory\fP [\fIformat-specific-parameters\fP]"
+Build a source package (\fB\-\-build\fP since dpkg 1.17.14).
+The first non-option argument is taken as the
+name of the directory containing the debianized source tree (i.e. with a
+debian sub-directory and maybe changes to the original files).
+Depending on the source package format used to build the package,
+additional parameters might be accepted.
+
+\fBdpkg\-source\fP will build the source package with the first format
+found in this ordered list:
+the format indicated with the \fI\-\-format\fP command line option,
+the format indicated in \fBdebian/source/format\fP,
+“1.0”.
+The fallback to “1.0” is deprecated and will be removed at some
+point in the future, you should always document the desired source format
+in \fBdebian/source/format\fP. See section \fBSOURCE PACKAGE FORMATS\fP
+for an extensive description of the various source package formats.
+
+.TP
+.RI "\fB\-\-print\-format\fP " directory
+Print the source format that would be used to build the source package if
+\fBdpkg\-source \-\-build \fIdirectory\fR was called (in the same conditions
+and with the same parameters; since dpkg 1.15.5).
+
+.TP
+.RI "\fB\-\-before\-build\fP " directory
+Run the corresponding hook of the source package format (since dpkg 1.15.8).
+This hook is
+called before any build of the package (\fBdpkg\-buildpackage\fP calls it
+very early even before \fBdebian/rules clean\fP). This command is
+idempotent and can be called multiple times. Not all source formats
+implement something in this hook, and those that do usually prepare the
+source tree for the build for example by ensuring that the Debian patches
+are applied.
+
+.TP
+.RI "\fB\-\-after\-build\fP " directory
+Run the corresponding hook of the source package format (since dpkg 1.15.8).
+This hook is
+called after any build of the package (\fBdpkg\-buildpackage\fP calls it
+last). This command is idempotent and can be called multiple times. Not
+all source formats implement something in this hook, and those that do
+usually use it to undo what \fB\-\-before\-build\fP has done.
+
+.TP
+.RI "\fB\-\-commit\fP [" directory "] ..."
+Record changes in the source tree unpacked in \fIdirectory\fP
+(since dpkg 1.16.1).
+This command can take supplementary parameters depending on the source format.
+It will error out for formats where this operation doesn't mean anything.
+
+.TP
+.BR \-? ", " \-\-help
+Show the usage message and exit.
+The format specific build and extract options can be shown by using the
+\fB\-\-format\fP option.
+.TP
+.BR \-\-version
+Show the version and exit.
+.
+.SH OPTIONS
+.SS Generic build options
+.TP
+.BI \-c control-file
+Specifies the main source control file to read information from. The
+default is
+.BR debian/control .
+If given with relative pathname this is interpreted starting at
+the source tree's top level directory.
+.TP
+.BI \-l changelog-file
+Specifies the changelog file to read information from. The
+default is
+.BR debian/changelog .
+If given with relative pathname this is interpreted starting at
+the source tree's top level directory.
+.TP
+.BI \-F changelog-format
+Specifies the format of the changelog. See \fBdpkg\-parsechangelog\fP(1)
+for information about alternative formats.
+.TP
+.BI \-\-format= value
+Use the given format for building the source package (since dpkg 1.14.17).
+It does override any format given in \fBdebian/source/format\fP.
+.TP
+.BI \-V name = value
+Set an output substitution variable.
+See \fBdeb\-substvars\fP(5) for a discussion of output substitution.
+.TP
+.BI \-T substvars-file
+Read substitution variables in
+.IR substvars-file ;
+the default is to not read any file. This option can be used multiple
+times to read substitution variables from multiple files (since dpkg 1.15.6).
+.TP
+.BI \-D field = value
+Override or add an output control file field.
+.TP
+.BI \-U field
+Remove an output control file field.
+.TP
+.BR \-Z "\fIcompression\fP, " \-\-compression =\fIcompression\fP
+Specify the compression to use for created tarballs and diff files
+(\fB\-\-compression\fP since dpkg 1.15.5).
+Note that this option will not cause existing tarballs to be recompressed,
+it only affects new files. Supported values are:
+.IR gzip ", " bzip2 ", " lzma " and " xz .
+The default is \fIxz\fP for formats 2.0 and newer, and \fIgzip\fP for
+format 1.0. \fIxz\fP is only supported since dpkg 1.15.5.
+.TP
+.BR \-z "\fIlevel\fP, " \-\-compression\-level =\fIlevel\fP
+Compression level to use (\fB\-\-compression\-level\fP since dpkg 1.15.5).
+As with \fB\-Z\fP it only affects newly created
+files. Supported values are:
+.IR 1 " to " 9 ", " best ", and " fast .
+The default is \fI9\fP for gzip and bzip2, \fI6\fP for xz and lzma.
+.TP
+.BR \-i "[\fIregex\fP], " \-\-diff\-ignore [=\fIregex\fP]
+You may specify a perl regular expression to match files you want
+filtered out of the list of files for the diff (\fB\-\-diff\-ignore\fP
+since dpkg 1.15.6).
+(This list is
+generated by a find command.) (If the source package is being built as a
+version 3 source package using a VCS, this can be used to ignore
+uncommitted changes on specific files. Using \-i.* will ignore all of them.)
+
+The \fB\-i\fP option by itself enables this setting with a default regex
+(preserving any modification to the default regex done by a previous use
+of \fB\-\-extend\-diff\-ignore\fP) that will filter out control files and
+directories of the most common revision control systems, backup and swap
+files and Libtool build output directories. There can only be one active
+regex, of multiple \fB\-i\fP options only the last one will take effect.
+
+This is very helpful in cutting out extraneous files that get included
+in the diff, e.g. if you maintain your source in a revision control
+system and want to use a checkout to build a source package without
+including the additional files and directories that it will usually
+contain (e.g. CVS/, .cvsignore, .svn/). The default regex is already
+very exhaustive, but if you need to replace it, please note that by
+default it can match any part of a path, so if you want to match the
+begin of a filename or only full filenames, you will need to provide
+the necessary anchors (e.g. ‘(^|/)’, ‘($|/)’) yourself.
+.TP
+.BR \-\-extend\-diff\-ignore =\fIregex\fP
+The perl regular expression specified will extend the default value used by
+\fB\-\-diff\-ignore\fP and its current value, if set (since dpkg 1.15.6).
+It does this by concatenating “\fB|\fP\fIregex\fP” to the existing value.
+This option is convenient to use in \fBdebian/source/options\fP to exclude
+some auto-generated files from the automatic patch generation.
+.TP
+.BR \-I "[\fIfile-pattern\fP], " \-\-tar\-ignore [=\fIfile-pattern\fP]
+If this option is specified, the pattern will be passed to
+.BR tar (1)'s
+.B \-\-exclude
+option when it is called to generate a .orig.tar or .tar file
+(\fB\-\-tar\-ignore\fP since dpkg 1.15.6).
+For
+example, \fB\-I\fPCVS will make tar skip over CVS directories when generating
+a .tar.gz file. The option may be repeated multiple times to list multiple
+patterns to exclude.
+
+\fB\-I\fP by itself adds default \fB\-\-exclude\fP options that will
+filter out control files and directories of the most common revision
+control systems, backup and swap files and Libtool build output
+directories.
+.PP
+.B Note:
+While they have similar purposes, \fB\-i\fP and \fB\-I\fP have very
+different syntax and semantics. \fB\-i\fP can only be specified once and
+takes a perl compatible regular expression which is matched against
+the full relative path of each file. \fB\-I\fP can specified
+multiple times and takes a filename pattern with shell wildcards.
+The pattern is applied to the full relative path but also
+to each part of the path individually. The exact semantic of tar's
+\fB\-\-exclude\fP option is somewhat complicated, see
+https://www.gnu.org/software/tar/manual/tar.html#wildcards for a full
+documentation.
+
+The default regex and patterns for both options can be seen
+in the output of the \fB\-\-help\fP command.
+.SS Generic extract options
+.TP
+.BI \-\-no\-copy
+Do not copy original tarballs near the extracted source package
+(since dpkg 1.14.17).
+.TP
+.BI \-\-no\-check
+Do not check signatures and checksums before unpacking (since dpkg 1.14.17).
+.TP
+.B \-\-no\-overwrite\-dir
+Do not overwrite the extraction directory if it already exists
+(since dpkg 1.18.8).
+.TP
+.BI \-\-require\-valid\-signature
+Refuse to unpack the source package if it doesn't contain an OpenPGP
+signature that can be verified (since dpkg 1.15.0) either with the user's
+\fItrustedkeys.gpg\fP keyring, one of the vendor-specific keyrings, or one
+of the official Debian keyrings
+(\fI/usr/share/keyrings/debian\-keyring.gpg\fP
+and \fI/usr/share/keyrings/debian\-maintainers.gpg\fP).
+.TP
+.BI \-\-require\-strong\-checksums
+Refuse to unpack the source package if it does not contain any strong
+checksums (since dpkg 1.18.7).
+Currently the only known checksum considered strong is \fBSHA-256\fP.
+.TP
+.B \-\-ignore\-bad\-version
+Turns the bad source package version check into a non-fatal warning
+(since dpkg 1.17.7).
+This option should only be necessary when extracting ancient source
+packages with broken versions, just for backwards compatibility.
+
+.SH SOURCE PACKAGE FORMATS
+If you don't know what source format to use, you should probably pick
+either “3.0 (quilt)” or “3.0 (native)”.
+See https://wiki.debian.org/Projects/DebSrc3.0 for information on the
+deployment of those formats within Debian.
+
+.SS Format: 1.0
+A source package in this format consists either of a \fB.orig.tar.gz\fP
+associated to a \fB.diff.gz\fP or a single \fB.tar.gz\fP (in that case
+the package is said to be \fInative\fP).
+Optionally the original tarball might be accompanied by a detached
+upstream signature \fB.orig.tar.gz.asc\fP, extraction
+supported since dpkg 1.18.5.
+
+.B Extracting
+
+Extracting a native package is a simple extraction of the single
+tarball in the target directory. Extracting a non-native package
+is done by first unpacking the \fB.orig.tar.gz\fP and then applying
+the patch contained in the \fB.diff.gz\fP file. The timestamp of
+all patched files is reset to the extraction time of the source
+package (this avoids timestamp skews leading to problems when
+autogenerated files are patched). The diff can create new files (the whole
+debian directory is created that way) but can't remove files (empty files
+will be left over).
+
+.B Building
+
+Building a native package is just creating a single tarball with
+the source directory. Building a non-native package involves
+extracting the original tarball in a separate “.orig” directory and
+regenerating the \fB.diff.gz\fP by comparing the source package
+\fIdirectory\fP with the .orig directory.
+
+.B Build options (with \-\-build):
+
+If a second non-option argument is supplied it should be the name of the
+original source directory or tarfile or the empty string if the package is
+a Debian-specific one and so has no debianization diffs. If no second
+argument is supplied then
+.B dpkg\-source
+will look for the original source tarfile
+.IB package _ upstream-version .orig.tar.gz
+or the original source directory
+.IB directory .orig
+depending on the \fB\-sX\fP arguments.
+
+.BR \-sa ", " \-sp ", " \-sk ", " \-su " and " \-sr
+will not overwrite existing tarfiles or directories. If this is
+desired then
+.BR \-sA ", " \-sP ", " \-sK ", " \-sU " and " \-sR
+should be used instead.
+.PP
+.TP
+.BR \-sk
+Specifies to expect the original source as a tarfile, by default
+.IB package _ upstream-version .orig.tar. extension \fR.
+It will leave this original source in place as a tarfile, or copy it
+to the current directory if it isn't already there. The
+tarball will be unpacked into
+.IB directory .orig
+for the generation of the diff.
+.TP
+.B \-sp
+Like
+.B \-sk
+but will remove the directory again afterwards.
+.TP
+.B \-su
+Specifies that the original source is expected as a directory, by
+default
+.IB package - upstream-version .orig
+and
+.B dpkg\-source
+will create a new original source archive from it.
+.TP
+.B \-sr
+Like
+.B \-su
+but will remove that directory after it has been used.
+.TP
+.B \-ss
+Specifies that the original source is available both as a directory
+and as a tarfile. \fBdpkg\-source\fP will use the directory to create
+the diff, but the tarfile to create the
+.BR .dsc .
+This option must be used with care - if the directory and tarfile do
+not match a bad source archive will be generated.
+.TP
+.B \-sn
+Specifies to not look for any original source, and to not generate a diff.
+The second argument, if supplied, must be the empty string. This is
+used for Debian-specific packages which do not have a separate
+upstream source and therefore have no debianization diffs.
+.TP
+.BR \-sa " or " \-sA
+Specifies to look for the original source archive as a tarfile or as a
+directory - the second argument, if any, may be either, or the empty
+string (this is equivalent to using
+.BR \-sn ).
+If a tarfile is found it will unpack it to create the diff and remove
+it afterwards (this is equivalent to
+.BR \-sp );
+if a directory is found it will pack it to create the original source
+and remove it afterwards (this is equivalent to
+.BR \-sr );
+if neither is found it will assume that the package has no
+debianization diffs, only a straightforward source archive (this is
+equivalent to
+.BR \-sn ).
+If both are found then \fBdpkg\-source\fP will ignore the directory,
+overwriting it, if
+.B \-sA
+was specified (this is equivalent to
+.BR \-sP )
+or raise an error if
+.B \-sa
+was specified.
+.B \-sa
+is the default.
+.TP
+.B \-\-abort\-on\-upstream\-changes
+The process fails if the generated diff contains changes to files
+outside of the debian sub-directory (since dpkg 1.15.8).
+This option is not allowed in
+\fBdebian/source/options\fP but can be used in
+\fBdebian/source/local\-options\fP.
+.PP
+
+.B Extract options (with \-\-extract):
+
+In all cases any existing original source tree will be removed.
+.TP
+.B \-sp
+Used when extracting then the original source (if any) will be left
+as a tarfile. If it is not already located in the current directory
+or if an existing but different file is there it will be copied there.
+(\fBThis is the default\fP).
+.TP
+.B \-su
+Unpacks the original source tree.
+.TP
+.B \-sn
+Ensures that the original source is neither copied to the current
+directory nor unpacked. Any original source tree that was in the
+current directory is still removed.
+.PP
+All the
+.BI \-s X
+options are mutually exclusive. If you specify more than one only the
+last one will be used.
+.TP
+.B \-\-skip\-debianization
+Skips application of the debian diff on top of the upstream sources
+(since dpkg 1.15.1).
+.
+.SS Format: 2.0
+Extraction supported since dpkg 1.13.9, building supported since dpkg 1.14.8.
+Also known as wig&pen. This format is not recommended for wide-spread
+usage, the format “3.0 (quilt)” replaces it.
+Wig&pen was the first specification of a new-generation source package format.
+
+The behaviour of this format is the same as the “3.0 (quilt)” format
+except that it doesn't use an explicit list of patches. All files in
+\fBdebian/patches/\fP matching the perl regular expression \fB[\\w\-]+\fP
+must be valid patches: they are applied at extraction time.
+
+When building a new source package, any change to the upstream source
+is stored in a patch named \fBzz_debian\-diff\-auto\fP.
+.
+.SS Format: 3.0 (native)
+Supported since dpkg 1.14.17.
+This format is an extension of the native package format as defined
+in the 1.0 format. It supports all compression methods and
+will ignore by default any VCS specific files and directories
+as well as many temporary files (see default value associated to
+\fB\-I\fP option in the \fB\-\-help\fP output).
+.
+.SS Format: 3.0 (quilt)
+Supported since dpkg 1.14.17.
+A source package in this format contains at least
+an original tarball (\fB.orig.tar.\fP\fIext\fP where \fIext\fP can be
+\fBgz\fP, \fBbz2\fP, \fBlzma\fP and \fBxz\fP) and a debian tarball
+(\fB.debian.tar.\fP\fIext\fP). It can also contain additional original
+tarballs (\fB.orig\-\fP\fIcomponent\fP\fB.tar.\fP\fIext\fP).
+\fIcomponent\fP can only contain alphanumeric (‘a-zA-Z0-9’) characters
+and hyphens (‘\-’).
+Optionally each original tarball can be accompanied by a detached
+upstream signature (\fB.orig.tar.\fP\fIext\fP\fB.asc\fP and
+\fB.orig\-\fP\fIcomponent\fP\fB.tar.\fP\fIext\fP\fB.asc\fP), extraction
+supported since dpkg 1.17.20, building supported since dpkg 1.18.5.
+
+.PP
+.B Extracting
+.PP
+The main original tarball is extracted first, then all additional original
+tarballs are extracted in subdirectories named after the \fIcomponent\fP
+part of their filename (any pre-existing directory is replaced). The
+debian tarball is extracted on top of the source directory after prior
+removal of any pre-existing \fBdebian\fP directory. Note that the
+debian tarball must contain a \fBdebian\fP sub-directory but it
+can also contain binary files outside of that directory (see
+\fB\-\-include\-binaries\fP option).
+.PP
+All patches listed in \fBdebian/patches/\fP\fIvendor\fP\fB.series\fP or
+\fBdebian/patches/series\fP are then applied, where \fIvendor\fP will be
+the lowercase name of the current vendor, or \fBdebian\fP if there is
+no vendor defined.
+If the former file is used and the latter one doesn't exist (or is a
+symlink), then the latter is replaced with a symlink to the former.
+This is meant to simplify usage of \fBquilt\fP to manage the set of patches.
+Vendor-specific series files are intended to make it possible to serialize
+multiple development branches based on the vendor, in a declarative way,
+in preference to open-coding this handling in \fBdebian/rules\fP.
+This is particularly useful when the source would need to be patched
+conditionally because the affected files do not have built-in conditional
+occlusion support.
+Note however that while \fBdpkg\-source\fP parses correctly series files
+with explicit options used for patch application (stored on each line
+after the patch filename and one or more spaces), it does ignore those
+options and always expect patches that can be applied with the \fB\-p1\fP
+option of \fBpatch\fP. It will thus emit a warning when it encounters
+such options, and the build is likely to fail.
+.PP
+Note that \fBlintian\fP(1) will emit unconditional warnings when using
+vendor series due to a controversial Debian specific ruling, which should
+not affect any external usage; to silence these, the dpkg lintian profile
+can be used by passing «\fB--profile dpkg\fP» to \fBlintian\fP(1).
+.PP
+The timestamp of all patched files is reset to the extraction time of
+the source package (this avoids timestamp skews leading to problems
+when autogenerated files are patched).
+.PP
+Contrary to \fBquilt\fP's default behaviour, patches are expected to apply
+without any fuzz. When that is not the case, you should refresh such
+patches with \fBquilt\fP, or \fBdpkg\-source\fP will error out while
+trying to apply them.
+.PP
+Similarly to \fBquilt\fP's default behaviour, the patches can remove
+files too.
+.PP
+The file \fB.pc/applied\-patches\fP is created if some
+patches have been applied during the extraction.
+.PP
+.B Building
+.PP
+All original tarballs found in the current directory are extracted in a
+temporary directory by following the same logic as for the unpack, the
+debian directory is copied over in the temporary directory, and all
+patches except the automatic patch (\fBdebian\-changes\-\fP\fIversion\fP
+or \fBdebian\-changes\fP, depending on \fB\-\-single\-debian\-patch\fP) are
+applied. The temporary directory is compared to the source package
+directory. When the diff is non-empty, the build fails unless
+\fB\-\-single\-debian\-patch\fP or \fB\-\-auto\-commit\fP
+has been used, in which case the diff is stored in the automatic patch.
+If the automatic patch is created/deleted, it's added/removed from the
+series file and from the \fBquilt\fP metadata.
+
+Any change
+on a binary file is not representable in a diff and will thus lead to a
+failure unless the maintainer deliberately decided to include that
+modified binary file in the debian tarball (by listing it in
+\fBdebian/source/include\-binaries\fP). The build will also fail if it
+finds binary files in the debian sub-directory unless they have been
+whitelisted through \fBdebian/source/include\-binaries\fP.
+
+The updated debian directory and the list of modified binaries is then
+used to generate the debian tarball.
+
+The automatically generated diff doesn't include changes on VCS specific
+files as well as many temporary files (see default value associated to
+\fB\-i\fP option in the \fB\-\-help\fP output). In particular, the
+\fB.pc\fP directory used by \fBquilt\fP is ignored during generation of the
+automatic patch.
+
+Note: \fBdpkg\-source\fP \fB\-\-before\-build\fP (and \fB\-\-build\fP) will
+ensure that all patches listed in the series file are applied so that a
+package build always has all patches applied. It does this by finding
+unapplied patches (they are listed in the \fBseries\fP file but not in
+\fB.pc/applied\-patches\fP), and if the first patch in that set can be
+applied without errors, it will apply them all. The option
+\fB\-\-no\-preparation\fP can be used to disable this
+behavior.
+
+.PP
+.B Recording changes
+.TP
+.RI "\fB\-\-commit\fP [" directory "] [" patch-name "] [" patch-file ]
+Generates a patch corresponding to the local changes that are not managed
+by the \fBquilt\fP patch system and integrates it in the patch system under
+the name \fIpatch-name\fP. If the name is missing, it will be asked
+interactively. If \fIpatch-file\fP is given, it is used as the patch
+corresponding to the local changes to integrate. Once integrated, an
+editor is launched so that you can edit the meta-information in the patch
+header.
+
+Passing \fIpatch-file\fP is mainly useful after a build failure that
+pre-generated this file, and on this ground the given file is removed
+after integration. Note also that the changes contained in the patch file
+must already be applied on the tree and that the files modified by the
+patch must not have supplementary unrecorded changes.
+
+If the patch generation detects modified binary files, they will be
+automatically added to \fBdebian/source/include\-binaries\fP so that
+they end up in the debian tarball (exactly like \fBdpkg-source
+\-\-include\-binaries \-\-build\fP would do).
+.PP
+.B Build options
+.TP
+.BI \-\-allow\-version\-of\-quilt\-db= version
+Allow \fBdpkg\-source\fP to build the source package if the version of
+the \fBquilt\fP metadata is the one specified, even if \fBdpkg\-source\fP
+doesn't know about it (since dpkg 1.15.5.4).
+Effectively this says that the given version of the
+\fBquilt\fP metadata is compatible with the version 2 that \fBdpkg\-source\fP
+currently supports. The version of the \fBquilt\fP metadata is stored in
+\fB.pc/.version\fP.
+.TP
+.B \-\-include\-removal
+Do not ignore removed files and include them in the automatically
+generated patch.
+.TP
+.B \-\-include\-timestamp
+Include timestamp in the automatically generated patch.
+.TP
+.B \-\-include\-binaries
+Add all modified binaries in the debian tarball. Also add them to
+\fBdebian/source/include\-binaries\fP: they will be added by default
+in subsequent builds and this option is thus no more needed.
+.TP
+.B \-\-no\-preparation
+Do not try to prepare the build tree by applying patches which are
+apparently unapplied (since dpkg 1.14.18).
+.TP
+.B \-\-single\-debian\-patch
+Use \fBdebian/patches/debian\-changes\fP instead of
+\fBdebian/patches/debian\-changes\-\fP\fIversion\fP for the name of the
+automatic patch generated during build (since dpkg 1.15.5.4).
+This option is particularly
+useful when the package is maintained in a VCS and a patch set can't reliably
+be generated. Instead the current diff with upstream should be stored in a
+single patch. The option would be put in \fBdebian/source/local\-options\fP
+and would be accompanied by a \fBdebian/source/local\-patch\-header\fP file
+explaining how the Debian changes can be best reviewed, for example in the
+VCS that is used.
+.TP
+.B \-\-create\-empty\-orig
+Automatically create the main original tarball as empty if it's missing
+and if there are supplementary original tarballs (since dpkg 1.15.6).
+This option is meant to
+be used when the source package is just a bundle of multiple upstream
+software and where there's no “main” software.
+.TP
+.B \-\-no\-unapply\-patches, \-\-unapply\-patches
+By default, \fBdpkg\-source\fP will automatically unapply the patches in the
+\fB\-\-after\-build\fP hook if it did apply them during
+\fB\-\-before\-build\fP (\fB\-\-unapply\-patches\fP since dpkg 1.15.8,
+\fB\-\-no\-unapply\-patches\fP since dpkg 1.16.5).
+Those options allow you to forcefully disable
+or enable the patch unapplication process. Those options are only allowed
+in \fBdebian/source/local\-options\fP so that all generated source
+packages have the same behavior by default.
+.TP
+.B \-\-abort\-on\-upstream\-changes
+The process fails if an automatic patch has been generated
+(since dpkg 1.15.8).
+This option
+can be used to ensure that all changes were properly recorded in separate
+\fBquilt\fP patches prior to the source package build. This option is not
+allowed in \fBdebian/source/options\fP but can be used in
+\fBdebian/source/local\-options\fP.
+.TP
+.B \-\-auto\-commit
+The process doesn't fail if an automatic patch has been generated, instead
+it's immediately recorded in the \fBquilt\fP series.
+
+.PP
+.B Extract options
+.TP
+.B \-\-skip\-debianization
+Skips extraction of the debian tarball on top of the upstream sources
+(since dpkg 1.15.1).
+.TP
+.B \-\-skip\-patches
+Do not apply patches at the end of the extraction (since dpkg 1.14.18).
+.
+.SS Format: 3.0 (custom)
+Supported since dpkg 1.14.17.
+This format is special.
+It doesn't represent a real source package
+format but can be used to create source packages with arbitrary files.
+.PP
+.B Build options
+.PP
+All non-option arguments are taken as files to integrate in the
+generated source package. They must exist and are preferably
+in the current directory. At least one file must be given.
+.TP
+.BI \-\-target\-format= value
+\fBRequired\fP. Defines the real format of the generated source package.
+The generated .dsc file will contain this value in its \fBFormat\fP field
+and not “3.0 (custom)”.
+.
+.SS Format: 3.0 (git)
+Supported since dpkg 1.14.17.
+This format is experimental.
+.PP
+A source package in this format consists of a
+single bundle of a git repository \fB.git\fP to hold the source of a package.
+There may also be a \fB.gitshallow\fP file listing revisions for a shallow
+git clone.
+.PP
+.B Extracting
+.PP
+The bundle is cloned as a git repository to the target directory.
+If there is a gitshallow file, it is installed as \fI.git/shallow\fP inside
+the cloned git repository.
+.PP
+Note that by default the new repository will have the same branch checked
+out that was checked out in the original source.
+(Typically “master”, but it could be anything.)
+Any other branches will be available under \fIremotes/origin/\fP.
+.PP
+.B Building
+.PP
+Before going any further, some checks are done to ensure that we
+don't have any non-ignored uncommitted changes.
+.PP
+\fBgit\-bundle\fP(1) is used to generate a bundle of the git repository.
+By default, all branches and tags in the repository are included in the
+bundle.
+.PP
+.B Build options
+.TP
+.BI \-\-git\-ref= ref
+Allows specifying a git ref to include in the git bundle. Use disables
+the default behavior of including all branches and tags. May be specified
+multiple times. The \fIref\fP can be the name of a branch or tag to
+include. It may also be any parameter that can be passed to
+\fBgit\-rev\-list\fP(1). For example, to include only
+the master branch, use \fB\-\-git\-ref=\fPmaster. To include all tags and
+branches, except for the private branch, use \fB\-\-git\-ref=\fP\-\-all
+\fB\-\-git\-ref=\fP^private
+.TP
+.BI \-\-git\-depth= number
+Creates a shallow clone with a history truncated to the specified number of
+revisions.
+.SS Format: 3.0 (bzr)
+Supported since dpkg 1.14.17.
+This format is experimental.
+It generates a single tarball containing the bzr repository.
+.PP
+.B Extracting
+.PP
+The tarball is unpacked and then bzr is used to checkout the current
+branch.
+.PP
+.B Building
+.PP
+Before going any further, some checks are done to ensure that we
+don't have any non-ignored uncommitted changes.
+.PP
+Then the VCS specific part of the source directory is copied over to a
+temporary directory. Before this temporary directory is packed in a tarball,
+various cleanup are done to save space.
+.SH DIAGNOSTICS
+.SS no source format specified in debian/source/format
+The file \fBdebian/source/format\fP should always exist and indicate the
+desired source format. For backwards compatibility, format “1.0” is
+assumed when the file doesn't exist but you should not rely on this:
+at some point in the future \fBdpkg\-source\fP will be modified to fail
+when that file doesn't exist.
+
+The rationale is that format “1.0” is no longer the recommended format,
+you should usually pick one of the newer formats (“3.0 (quilt)”, “3.0
+(native)”) but \fBdpkg\-source\fP will not do this automatically for you.
+If you want to continue using the old format, you should be explicit about
+it and put “1.0” in \fBdebian/source/format\fP.
+.SS the diff modifies the following upstream files
+When using source format “1.0” it is usually a bad idea to modify
+upstream files directly as the changes end up hidden and mostly
+undocumented in the .diff.gz file. Instead you should store your changes
+as patches in the debian directory and apply them at build-time. To avoid
+this complexity you can also use the format “3.0 (quilt)” that offers
+this natively.
+.SS cannot represent change to \fIfile\fP
+Changes to upstream sources are usually stored with patch files, but not
+all changes can be represented with patches: they can only alter the
+content of plain text files. If you try replacing a file with something of
+a different type (for example replacing a plain file with a symlink or a
+directory), you will get this error message.
+.SS newly created empty file \fIfile\fB will not be represented in diff
+Empty files can't be created with patch files. Thus this change is not
+recorded in the source package and you are warned about it.
+.SS executable mode \fIperms\fB of \fIfile\fB will not be represented in diff
+Patch files do not record permissions of files and thus executable
+permissions are not stored in the source package. This warning reminds you
+of that fact.
+.SS special mode \fIperms\fB of \fIfile\fB will not be represented in diff
+Patch files do not record permissions of files and thus modified
+permissions are not stored in the source package. This warning reminds you
+of that fact.
+.
+.SH ENVIRONMENT
+.TP
+.B DPKG_COLORS
+Sets the color mode (since dpkg 1.18.5).
+The currently accepted values are: \fBauto\fP (default), \fBalways\fP and
+\fBnever\fP.
+.TP
+.B DPKG_NLS
+If set, it will be used to decide whether to activate Native Language Support,
+also known as internationalization (or i18n) support (since dpkg 1.19.0).
+The accepted values are: \fB0\fP and \fB1\fP (default).
+.TP
+.B SOURCE_DATE_EPOCH
+If set, it will be used as the timestamp (as seconds since the epoch) to
+clamp the mtime in the \fBtar\fP(5) file entries.
+.TP
+.B VISUAL
+.TQ
+.B EDITOR
+Used by the “2.0” and “3.0 (quilt)” source format modules.
+.TP
+.B GIT_DIR
+.TQ
+.B GIT_INDEX_FILE
+.TQ
+.B GIT_OBJECT_DIRECTORY
+.TQ
+.B GIT_ALTERNATE_OBJECT_DIRECTORIES
+.TQ
+.B GIT_WORK_TREE
+Used by the “3.0 (git)” source format modules.
+.
+.SH FILES
+.SS debian/source/format
+This file contains on a single line the format that should be used to
+build the source package (possible formats are described above). No leading
+or trailing spaces are allowed.
+.SS debian/source/include\-binaries
+This file contains a list of binary files (one per line) that should be
+included in the debian tarball. Leading and trailing spaces are stripped.
+Lines starting with ‘\fB#\fP’ are comments and are skipped.
+Empty lines are ignored.
+.SS debian/source/options
+This file contains a list of long options that should be automatically
+prepended to the set of command line options of a \fBdpkg\-source \-\-build\fR
+or \fBdpkg\-source \-\-print\-format\fR call. Options like
+\fB\-\-compression\fR and \fB\-\-compression\-level\fR are well suited for
+this file.
+.P
+Each option should be put on a separate line. Empty lines and lines
+starting with ‘\fB#\fP’ are ignored.
+The leading ‘\fB\-\-\fP’ should be stripped and short options are
+not allowed.
+Optional spaces are allowed around the ‘\fB=\fP’ symbol and optional
+quotes are allowed around the value.
+Here's an example of such a file:
+.P
+  # let dpkg\-source create a debian.tar.bz2 with maximal compression
+  compression = "bzip2"
+  compression\-level = 9
+  # use debian/patches/debian\-changes as automatic patch
+  single\-debian\-patch
+  # ignore changes on config.{sub,guess}
+  extend-diff-ignore = "(^|/)(config\.sub|config\.guess)$"
+.P
+Note: \fBformat\fR options are not accepted in this file, you should
+use \fBdebian/source/format\fR instead.
+.SS debian/source/local\-options
+Exactly like \fBdebian/source/options\fP except that the file is not
+included in the generated source package. It can be useful to store
+a preference tied to the maintainer or to the VCS repository where
+the source package is maintained.
+.SS debian/source/local\-patch\-header \fRand\fP debian/source/patch\-header
+Free form text that is put on top of the automatic patch generated
+in formats “2.0” or “3.0 (quilt)”. \fBlocal\-patch\-header\fP is not
+included in the generated source package while \fBpatch\-header\fP is.
+.SS debian/patches/\fIvendor\fP.series
+.SS debian/patches/series
+This file lists all patches that have to be applied (in the given order)
+on top of the upstream source package. Leading and trailing spaces are
+stripped.
+The \fIvendor\fP will be the lowercase name of the current vendor, or
+\fBdebian\fP if there is no vendor defined.
+If the vendor-specific series file does not exist, the vendor-less series
+file will be used.
+Lines starting with ‘\fB#\fP’ are comments and are skipped.
+Empty lines are ignored.
+Remaining lines start with a patch filename (relative
+to the \fBdebian/patches/\fP directory) up to the first space character or
+the end of line. Optional \fBquilt\fP options can follow up to the end of line
+or the first ‘\fB#\fP’ preceded by one or more spaces (which marks the
+start of a comment up to the end of line).
+.SH BUGS
+The point at which field overriding occurs compared to certain
+standard output field settings is rather confused.
+.SH SEE ALSO
+.ad l
+.BR deb\-src\-control (5),
+.BR deb\-changelog (5),
+.BR dsc (5).