Adding upstream version 1.21.22.upstream/1.21.22upstream

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

1 files changed, 1047 insertions, 0 deletions

diff --git a/man/dpkg-source.pod b/man/dpkg-source.pod
new file mode 100644
index 0000000..be5e204
--- /dev/null
+++ b/man/dpkg-source.pod
@@ -0,0 +1,1047 @@
+# 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/>.
+
+=encoding utf8
+
+=head1 NAME
+
+dpkg-source - Debian source package (.dsc) manipulation tool
+
+=head1 SYNOPSIS
+
+B<dpkg-source>
+[I<option>...] I<command>
+
+=head1 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.
+
+=head1 COMMANDS
+
+=over
+
+=item B<-x>, B<--extract> I<filename>.dsc [I<output-directory>]
+
+Extract a source package (B<--extract> since dpkg 1.17.14).
+One non-option argument must be supplied,
+the name of the Debian source control file
+(B<.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 I<source>-I<version> 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
+B<.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
+B<debian/source/format> so that the following builds of the source
+package use the same format by default.
+
+=item B<-b>, B<--build> I<directory> [I<format-specific-parameters>]
+
+Build a source package (B<--build> 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.
+
+B<dpkg-source> will build the source package with the first format
+found in this ordered list:
+the format indicated with the I<--format> command line option,
+the format indicated in B<debian/source/format>,
+“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 B<debian/source/format>. See section B<SOURCE PACKAGE FORMATS>
+for an extensive description of the various source package formats.
+
+=item B<--print-format> I<directory>
+
+Print the source format that would be used to build the source package if
+B<dpkg-source --build> I<directory> was called (in the same conditions
+and with the same parameters; since dpkg 1.15.5).
+
+=item B<--before-build> I<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 (B<dpkg-buildpackage> calls it
+very early even before B<debian/rules clean>). 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.
+
+=item B<--after-build> I<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 (B<dpkg-buildpackage> 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 B<--before-build> has done.
+
+=item B<--commit> [I<directory>] ...
+
+Record changes in the source tree unpacked in I<directory>
+(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.
+
+=item B<-?>, B<--help>
+
+Show the usage message and exit.
+The format specific build and extract options can be shown by using the
+B<--format> option.
+
+=item B<--version>
+
+Show the version and exit.
+
+=back
+
+=head1 OPTIONS
+
+=head2 Generic build options
+
+=over
+
+=item B<-c>I<control-file>
+
+Specifies the main source control file to read information from. The
+default is
+B<debian/control>.
+If given with relative pathname this is interpreted starting at
+the source tree's top level directory.
+
+=item B<-l>I<changelog-file>
+
+Specifies the changelog file to read information from. The
+default is
+B<debian/changelog>.
+If given with relative pathname this is interpreted starting at
+the source tree's top level directory.
+
+=item B<-F>I<changelog-format>
+
+Specifies the format of the changelog. See B<dpkg-parsechangelog>(1)
+for information about alternative formats.
+
+=item B<--format=>I<value>
+
+Use the given format for building the source package (since dpkg 1.14.17).
+It does override any format given in B<debian/source/format>.
+
+=item B<-V>I<name>B<=>I<value>
+
+Set an output substitution variable.
+See B<deb-substvars>(5) for a discussion of output substitution.
+
+=item B<-T>I<substvars-file>
+
+Read substitution variables in
+I<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).
+
+=item B<-D>I<field>B<=>I<value>
+
+Override or add an output control file field.
+
+=item B<-U>I<field>
+
+Remove an output control file field.
+
+=item B<-Z>I<compression>, B<--compression>=I<compression>
+
+Specify the compression to use for created tarballs and diff files
+(B<--compression> 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:
+I<gzip>, I<bzip2>, I<lzma> and I<xz>.
+The default is I<xz> for formats 2.0 and newer, and I<gzip> for
+format 1.0. I<xz> is only supported since dpkg 1.15.5.
+
+=item B<-z>I<level>, B<--compression-level>=I<level>
+
+Compression level to use (B<--compression-level> since dpkg 1.15.5).
+As with B<-Z> it only affects newly created
+files. Supported values are:
+I<1> to I<9>, I<best>, and I<fast>.
+The default is I<9> for gzip and bzip2, I<6> for xz and lzma.
+
+=item B<-i>[I<regex>], B<--diff-ignore>[=I<regex>]
+
+You may specify a perl regular expression to match files you want
+filtered out of the list of files for the diff (B<--diff-ignore>
+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 B<-i> option by itself enables this setting with a default regex
+(preserving any modification to the default regex done by a previous use
+of B<--extend-diff-ignore>) 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 B<-i> options only the last one will take effect.
+
+This is very helpful in cutting out extraneous files that get included
+in the diff, for example 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.
+
+=item B<--extend-diff-ignore>=I<regex>
+
+The perl regular expression specified will extend the default value used by
+B<--diff-ignore> and its current value, if set (since dpkg 1.15.6).
+It does this by concatenating “B<|>I<regex>” to the existing value.
+This option is convenient to use in B<debian/source/options> to exclude
+some auto-generated files from the automatic patch generation.
+
+=item B<-I>[I<file-pattern>], B<--tar-ignore>[=I<file-pattern>]
+
+If this option is specified, the pattern will be passed to
+B<tar>(1)'s
+B<--exclude>
+option when it is called to generate a .orig.tar or .tar file
+(B<--tar-ignore> since dpkg 1.15.6).
+For
+example, B<-I>CVS 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.
+
+B<-I> by itself adds default B<--exclude> 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.
+
+=back
+
+B<Note:>
+While they have similar purposes, B<-i> and B<-I> have very
+different syntax and semantics. B<-i> can only be specified once and
+takes a perl compatible regular expression which is matched against
+the full relative path of each file. B<-I> 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
+B<--exclude> option is somewhat complicated, see
+L<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 B<--help> command.
+
+=head2 Generic extract options
+
+=over
+
+=item B<--no-copy>
+
+Do not copy original tarballs near the extracted source package
+(since dpkg 1.14.17).
+
+=item B<--no-check>
+
+Do not check signatures and checksums before unpacking (since dpkg 1.14.17).
+
+=item B<--no-overwrite-dir>
+
+Do not overwrite the extraction directory if it already exists
+(since dpkg 1.18.8).
+
+=item B<--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
+I<trustedkeys.gpg> keyring, one of the vendor-specific keyrings, or one
+of the official Debian keyrings
+(I</usr/share/keyrings/debian-keyring.gpg>,
+I</usr/share/keyrings/debian-nonupload.gpg> and
+I</usr/share/keyrings/debian-maintainers.gpg>).
+
+=item B<--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 B<SHA-256>.
+
+=item 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.
+
+=back
+
+=head2 Generic general options
+
+=over
+
+=item B<--threads-max=>I<threads>
+
+Sets the maximum number of threads allowed for compressors that support
+multi-threaded operations (since dpkg 1.21.14).
+
+=item B<-q>
+
+Sets quiet mode to suppress warnings.
+
+=back
+
+=head1 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 L<https://wiki.debian.org/Projects/DebSrc3.0> for information on the
+deployment of those formats within Debian.
+
+=head2 Format: 1.0
+
+A source package in this format consists either of a B<.orig.tar.gz>
+associated to a B<.diff.gz> or a single B<.tar.gz> (in that case
+the package is said to be I<native>).
+Optionally the original tarball might be accompanied by a detached
+upstream signature B<.orig.tar.gz.asc>, 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 B<.orig.tar.gz> and then applying
+the patch contained in the B<.diff.gz> 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 cannot remove files (empty files
+will be left over) and cannot create or change symlinks.
+
+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 B<.diff.gz> by comparing the source package
+I<directory> 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
+I<package>B<_>I<upstream-version>B<.orig.tar.gz>
+or the original source directory
+I<directory>B<.orig>
+depending on the B<-sX> arguments.
+
+B<-sa>, B<-sp>, B<-sk>, B<-su> and B<-sr>
+will not overwrite existing tarfiles or directories. If this is
+desired then
+B<-sA>, B<-sP>, B<-sK>, B<-sU> and B<-sR>
+should be used instead.
+
+=over
+
+=item B<-sk>
+
+Specifies to expect the original source as a tarfile, by default
+I<package>B<_>I<upstream-version>B<.orig.tar.>I<extension>.
+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
+I<directory>B<.orig>
+for the generation of the diff.
+
+=item B<-sp>
+
+Like
+B<-sk>
+but will remove the directory again afterwards.
+
+=item B<-su>
+
+Specifies that the original source is expected as a directory, by
+default
+I<package>B<->I<upstream-version>B<.orig>
+and
+B<dpkg-source>
+will create a new original source archive from it.
+
+=item B<-sr>
+
+Like
+B<-su>
+but will remove that directory after it has been used.
+
+=item B<-ss>
+
+Specifies that the original source is available both as a directory
+and as a tarfile. B<dpkg-source> will use the directory to create
+the diff, but the tarfile to create the
+B<.dsc>.
+This option must be used with care - if the directory and tarfile do
+not match a bad source archive will be generated.
+
+=item 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.
+
+=item B<-sa> or B<-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
+B<-sn>).
+If a tarfile is found it will unpack it to create the diff and remove
+it afterwards (this is equivalent to
+B<-sp>);
+if a directory is found it will pack it to create the original source
+and remove it afterwards (this is equivalent to
+B<-sr>);
+if neither is found it will assume that the package has no
+debianization diffs, only a straightforward source archive (this is
+equivalent to
+B<-sn>).
+If both are found then B<dpkg-source> will ignore the directory,
+overwriting it, if
+B<-sA>
+was specified (this is equivalent to
+B<-sP>)
+or raise an error if
+B<-sa>
+was specified.
+B<-sa>
+is the default.
+
+=item 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
+B<debian/source/options> but can be used in
+B<debian/source/local-options>.
+
+=back
+
+B<Extract options (with --extract):>
+
+In all cases any existing original source tree will be removed.
+
+=over
+
+=item 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.
+(B<This is the default>).
+
+=item B<-su>
+
+Unpacks the original source tree.
+
+=item 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.
+
+=back
+
+All the
+B<-s>I<X>
+options are mutually exclusive. If you specify more than one only the
+last one will be used.
+
+=over
+
+=item B<--skip-debianization>
+
+Skips application of the debian diff on top of the upstream sources
+(since dpkg 1.15.1).
+
+=back
+
+=head2 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
+B<debian/patches/> matching the perl regular expression B<[\w-]+>
+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 B<zz_debian-diff-auto>.
+
+=head2 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
+B<-I> option in the B<--help> output).
+
+=head2 Format: 3.0 (quilt)
+
+Supported since dpkg 1.14.17.
+A source package in this format contains at least
+an original tarball (B<.orig.tar.>I<ext> where I<ext> can be
+B<gz>, B<bz2>, B<lzma> and B<xz>) and a debian tarball
+(B<.debian.tar.>I<ext>). It can also contain additional original
+tarballs (B<.orig->I<component>B<.tar.>I<ext>).
+I<component> can only contain alphanumeric (‘a-zA-Z0-9’) characters
+and hyphens (‘-’).
+Optionally each original tarball can be accompanied by a detached
+upstream signature (B<.orig.tar.>I<ext>B<.asc> and
+B<.orig->I<component>B<.tar.>I<ext>B<.asc>), extraction
+supported since dpkg 1.17.20, building supported since dpkg 1.18.5.
+
+B<Extracting>
+
+The main original tarball is extracted first, then all additional original
+tarballs are extracted in subdirectories named after the I<component>
+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 B<debian> directory. Note that the
+debian tarball must contain a B<debian> sub-directory but it
+can also contain binary files outside of that directory (see
+B<--include-binaries> option).
+
+All patches listed in B<debian/patches/>I<vendor>B<.series> or
+B<debian/patches/series> are then applied, where I<vendor> will be
+the lowercase name of the current vendor, or B<debian> 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 B<quilt> 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 B<debian/rules>.
+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 B<dpkg-source> 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 expects patches that can be applied with the B<-p1>
+option of B<patch>. It will thus emit a warning when it encounters
+such options, and the build is likely to fail.
+
+Note that B<lintian>(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 «B<--profile dpkg>» to B<lintian>(1).
+
+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).
+
+Contrary to B<quilt>'s default behaviour, patches are expected to apply
+without any fuzz. When that is not the case, you should refresh such
+patches with B<quilt>, or B<dpkg-source> will error out while
+trying to apply them.
+
+Similarly to B<quilt>'s default behaviour, the patches can remove
+files too.
+
+The file B<.pc/applied-patches> is created if some
+patches have been applied during the extraction.
+
+B<Building>
+
+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 (B<debian-changes->I<version>
+or B<debian-changes>, depending on B<--single-debian-patch>) are
+applied. The temporary directory is compared to the source package
+directory. When the diff is non-empty, the build fails unless
+B<--single-debian-patch> or B<--auto-commit>
+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 B<quilt> 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
+B<debian/source/include-binaries>). The build will also fail if it
+finds binary files in the debian sub-directory unless they have been
+allowed through B<debian/source/include-binaries>.
+
+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
+B<-i> option in the B<--help> output). In particular, the
+B<.pc> directory used by B<quilt> is ignored during generation of the
+automatic patch.
+
+B<Note:> B<dpkg-source> B<--before-build> (and B<--build>) 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 B<series> file but not in
+B<.pc/applied-patches>), and if the first patch in that set can be
+applied without errors, it will apply them all. The option
+B<--no-preparation> can be used to disable this
+behavior.
+
+B<Recording changes>
+
+=over
+
+=item B<--commit> [I<directory>] [I<patch-name>] [I<patch-file>]
+
+Generates a patch corresponding to the local changes that are not managed
+by the B<quilt> patch system and integrates it in the patch system under
+the name I<patch-name>. If the name is missing, it will be asked
+interactively. If I<patch-file> 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 I<patch-file> 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 B<debian/source/include-binaries> so that
+they end up in the debian tarball (exactly like B<dpkg-source
+--include-binaries --build> would do).
+
+=back
+
+B<Build options>
+
+=over
+
+=item B<--allow-version-of-quilt-db=>I<version>
+
+Allow B<dpkg-source> to build the source package if the version of
+the B<quilt> metadata is the one specified, even if B<dpkg-source>
+doesn't know about it (since dpkg 1.15.5.4).
+Effectively this says that the given version of the
+B<quilt> metadata is compatible with the version 2 that B<dpkg-source>
+currently supports. The version of the B<quilt> metadata is stored in
+B<.pc/.version>.
+
+=item B<--include-removal>
+
+Do not ignore removed files and include them in the automatically
+generated patch.
+
+=item B<--include-timestamp>
+
+Include timestamp in the automatically generated patch.
+
+=item B<--include-binaries>
+
+Add all modified binaries in the debian tarball. Also add them to
+B<debian/source/include-binaries>: they will be added by default
+in subsequent builds and this option is thus no more needed.
+
+=item B<--no-preparation>
+
+Do not try to prepare the build tree by applying patches which are
+apparently unapplied (since dpkg 1.14.18).
+
+=item B<--single-debian-patch>
+
+Use B<debian/patches/debian-changes> instead of
+B<debian/patches/debian-changes->I<version> 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 B<debian/source/local-options>
+and would be accompanied by a B<debian/source/local-patch-header> file
+explaining how the Debian changes can be best reviewed, for example in the
+VCS that is used.
+
+=item 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.
+
+=item B<--no-unapply-patches, --unapply-patches>
+
+By default, B<dpkg-source> will automatically unapply the patches in the
+B<--after-build> hook if it did apply them during
+B<--before-build> (B<--unapply-patches> since dpkg 1.15.8,
+B<--no-unapply-patches> since dpkg 1.16.5).
+Those options allow you to forcefully disable
+or enable the patch unapplication process. Those options are only allowed
+in B<debian/source/local-options> so that all generated source
+packages have the same behavior by default.
+
+=item 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
+B<quilt> patches prior to the source package build. This option is not
+allowed in B<debian/source/options> but can be used in
+B<debian/source/local-options>.
+
+=item B<--auto-commit>
+
+The process doesn't fail if an automatic patch has been generated, instead
+it's immediately recorded in the B<quilt> series.
+
+=back
+
+B<Extract options>
+
+=over
+
+=item B<--skip-debianization>
+
+Skips extraction of the debian tarball on top of the upstream sources
+(since dpkg 1.15.1).
+
+=item B<--skip-patches>
+
+Do not apply patches at the end of the extraction (since dpkg 1.14.18).
+
+=back
+
+=head2 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.
+
+B<Build options>
+
+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.
+
+=over
+
+=item B<--target-format=>I<value>
+
+B<Required>. Defines the real format of the generated source package.
+The generated .dsc file will contain this value in its B<Format> field
+and not “3.0 (custom)”.
+
+=back
+
+=head2 Format: 3.0 (git)
+
+Supported since dpkg 1.14.17.
+This format is experimental.
+
+A source package in this format consists of a
+single bundle of a git repository B<.git> to hold the source of a package.
+There may also be a B<.gitshallow> file listing revisions for a shallow
+git clone.
+
+B<Extracting>
+
+The bundle is cloned as a git repository to the target directory.
+If there is a gitshallow file, it is installed as I<.git/shallow> inside
+the cloned git repository.
+
+Note that by default the new repository will have the same branch checked
+out that was checked out in the original source.
+(Typically “main”, but it could be anything.)
+Any other branches will be available under I<remotes/origin/>.
+
+B<Building>
+
+Before going any further, some checks are done to ensure that we
+don't have any non-ignored uncommitted changes.
+
+B<git-bundle>(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.
+
+B<Build options>
+
+=over
+
+=item B<--git-ref=>I<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 I<ref> can be the name of a branch or tag to
+include. It may also be any parameter that can be passed to
+B<git-rev-list>(1). For example, to include only
+the main branch, use B<--git-ref=>main. To include all tags and
+branches, except for the private branch, use B<--git-ref=>--all
+B<--git-ref=>^private
+
+=item B<--git-depth=>I<number>
+
+Creates a shallow clone with a history truncated to the specified number of
+revisions.
+
+=back
+
+=head2 Format: 3.0 (bzr)
+
+Supported since dpkg 1.14.17.
+This format is experimental.
+It generates a single tarball containing the bzr repository.
+
+B<Extracting>
+
+The tarball is unpacked and then bzr is used to checkout the current
+branch.
+
+B<Building>
+
+Before going any further, some checks are done to ensure that we
+don't have any non-ignored uncommitted changes.
+
+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.
+
+=head1 DIAGNOSTICS
+
+=head2 no source format specified in debian/source/format
+
+The file B<debian/source/format> 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 B<dpkg-source> 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 B<dpkg-source> 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 B<debian/source/format>.
+
+=head2 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.
+
+=head2 cannot represent change to I<file>
+
+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.
+
+=head2 newly created empty file I<file> 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.
+
+=head2 executable mode I<perms> of I<file> 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.
+
+=head2 special mode I<perms> of I<file> 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.
+
+=head1 ENVIRONMENT
+
+=over
+
+=item B<DPKG_COLORS>
+
+Sets the color mode (since dpkg 1.18.5).
+The currently accepted values are: B<auto> (default), B<always> and
+B<never>.
+
+=item 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: B<0> and B<1> (default).
+
+=item B<SOURCE_DATE_EPOCH>
+
+If set, it will be used as the timestamp (as seconds since the epoch) to
+clamp the mtime in the B<tar>(5) file entries.
+
+=item B<VISUAL>
+
+=item B<EDITOR>
+
+Used by the “2.0” and “3.0 (quilt)” source format modules.
+
+=item B<GIT_DIR>
+
+=item B<GIT_INDEX_FILE>
+
+=item B<GIT_OBJECT_DIRECTORY>
+
+=item B<GIT_ALTERNATE_OBJECT_DIRECTORIES>
+
+=item B<GIT_WORK_TREE>
+
+Used by the “3.0 (git)” source format modules.
+
+=back
+
+=head1 FILES
+
+=head2 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.
+
+=head2 debian/source/include-binaries
+
+This file contains a list of pathnames of binary files (one per line) relative
+to the source root directory that should be included in the debian tarball.
+Leading and trailing spaces are stripped.
+Lines starting with ‘B<#>’ are comments and are skipped.
+Empty lines are ignored.
+
+=head2 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 B<dpkg-source --build>
+or B<dpkg-source --print-format> call. Options like
+B<--compression> and B<--compression-level> are well suited for
+this file.
+
+Each option should be put on a separate line. Empty lines and lines
+starting with ‘B<#>’ are ignored.
+The leading ‘B<-->’ should be stripped and short options are
+not allowed.
+Optional spaces are allowed around the ‘B<=>’ symbol and optional
+quotes are allowed around the value.
+Here's an example of such a file:
+
+ # 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)$"
+
+B<Note:> B<format> options are not accepted in this file, you should
+use B<debian/source/format> instead.
+
+=head2 debian/source/local-options
+
+Exactly like B<debian/source/options> 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.
+
+=head2 debian/source/local-patch-header
+
+=head2 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)”. B<local-patch-header> is not
+included in the generated source package while B<patch-header> is.
+
+=head2 debian/patches/I<vendor>.series
+
+=head2 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 I<vendor> will be the lowercase name of the current vendor, or
+B<debian> 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 ‘B<#>’ are comments and are skipped.
+Empty lines are ignored.
+Remaining lines start with a patch filename (relative
+to the B<debian/patches/> directory) up to the first space character or
+the end of line. Optional B<quilt> options can follow up to the end of line
+or the first ‘B<#>’ preceded by one or more spaces (which marks the
+start of a comment up to the end of line).
+
+=head1 BUGS
+
+The point at which field overriding occurs compared to certain
+standard output field settings is rather confused.
+
+=head1 SEE ALSO
+
+B<deb-src-control>(5),
+B<deb-changelog>(5),
+B<deb-substvars>(5),
+B<dsc>(5).