# dpkg-source

## NAME



           dpkg-source - Debian source package (.dsc) manipulation tool
    


## SYNOPSIS



           **dpkg-source**[_option_...] _command_
    


## DESCRIPTION



           **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.
    


## COMMANDS



           **-x** , **--extract** _filename_.dsc [_output-directory_]
               Extract a source package (**--extract** since dpkg 1.17.14).  One
               non-option argument must be supplied, the name of the Debian
               source control file (**.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 _source_ -_version_ under the current working
               directory.
    
               **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 **.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 **debian/source/format** so that the following builds of the
               source package use the same format by default.
    
           **-b** , **--build** _directory_ [_format-specific-parameters_]
               Build a source package (**--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.
    
               **dpkg-source** will build the source package with the first
               format found in this ordered list: the format indicated with
               the _--format_ command line option, the format indicated in
               **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
               **debian/source/format**.  See section "SOURCE PACKAGE FORMATS"
               for an extensive description of the various source package
               formats.
    
           **--print-format** _directory_
               Print the source format that would be used to build the source
               package if **dpkg-source --build** _directory_ was called (in the
               same conditions and with the same parameters; since dpkg
               1.15.5).
    
           **--before-build** _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 (**dpkg-buildpackage** calls it very early even before
               **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.
    
           **--after-build** _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 (**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 **--before-build** has done.
    
           **--commit**[_directory_] ...
               Record changes in the source tree unpacked in _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.
    
           **-?** , **--help**
               Show the usage message and exit.  The format specific build
               and extract options can be shown by using the **--format** option.
    
           **--version**
               Show the version and exit.
    


## OPTIONS



       **Generic build options**
           **-c** _control-file_
               Specifies the main source control file to read information
               from.  The default is **debian/control**.  If given with relative
               pathname this is interpreted starting at the source tree's top
               level directory.
    
           **-l** _changelog-file_
               Specifies the changelog file to read information from.  The
               default is **debian/changelog**.  If given with relative pathname
               this is interpreted starting at the source tree's top level
               directory.
    
           **-F** _changelog-format_
               Specifies the format of the changelog.  See
               dpkg-parsechangelog(1) for information about alternative
               formats.
    
           **--format=**_value_
               Use the given format for building the source package (since
               dpkg 1.14.17).  It does override any format given in
               **debian/source/format**.
    
           **-V** _name_**=**_value_
               Set an output substitution variable.  See deb-substvars(5) for
               a discussion of output substitution.
    
           **-T** _substvars-file_
               Read substitution variables in _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).
    
           **-D** _field_**=**_value_
               Override or add an output control file field.
    
           **-U** _field_
               Remove an output control file field.
    
           **-Z** _compression_ , **--compression** =_compression_
               Specify the compression to use for created tarballs and diff
               files (**--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: _gzip_ , _bzip2_ ,
               _lzma_ and _xz_.  The default is _xz_ for formats 2.0 and newer, and
               _gzip_ for format 1.0.  _xz_ is only supported since dpkg 1.15.5.
    
           **-z** _level_ , **--compression-level** =_level_
               Compression level to use (**--compression-level** since dpkg
               1.15.5).  As with **-Z** it only affects newly created files.
               Supported values are: _1_ to _9_ , _best_ , and _fast_.  The default is
               _9_ for gzip and bzip2, _6_ for xz and lzma.
    
           **-i**[_regex_], **--diff-ignore**[=_regex_]
               You may specify a perl regular expression to match files you
               want filtered out of the list of files for the diff
               (**--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 **-i** option by itself enables this setting with a default
               regex (preserving any modification to the default regex done
               by a previous use of **--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 **-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.
    
           **--extend-diff-ignore** =_regex_
               The perl regular expression specified will extend the default
               value used by **--diff-ignore** and its current value, if set
               (since dpkg 1.15.6).  It does this by concatenating “**|**_regex_ ”
               to the existing value.  This option is convenient to use in
               **debian/source/options** to exclude some auto-generated files
               from the automatic patch generation.
    
           **-I**[_file-pattern_], **--tar-ignore**[=_file-pattern_]
               If this option is specified, the pattern will be passed to
               tar(1)'s **--exclude** option when it is called to generate a
               .orig.tar or .tar file (**--tar-ignore** since dpkg 1.15.6).  For
               example, **-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.
    
               **-I** by itself adds default **--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.
    
           **Note** : While they have similar purposes, **-i** and **-I** have very
           different syntax and semantics.  **-i** can only be specified once and
           takes a perl compatible regular expression which is matched
           against the full relative path of each file.  **-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
           **--exclude** 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 **--help** command.
    
       **Generic extract options**
           **--no-copy**
               Do not copy original tarballs near the extracted source
               package (since dpkg 1.14.17).
    
           **--no-check**
               Do not check signatures and checksums before unpacking (since
               dpkg 1.14.17).
    
           **--no-overwrite-dir**
               Do not overwrite the extraction directory if it already exists
               (since dpkg 1.18.8).
    
           **--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 _trustedkeys.gpg_ keyring, or one of the
               vendor-specific keyrings, including any parent vendor keyrings
               if relevant.
    
           **--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 **SHA-256**.
    
           **--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.
    
       **Generic general options**
           **--threads-max=**_threads_
               Sets the maximum number of threads allowed for compressors
               that support multi-threaded operations (since dpkg 1.21.14).
    
           **-q** Sets quiet mode to suppress warnings.
    


## 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.
    
       **Format: 1.0**
           A source package in this format consists either of a **.orig.tar.gz**
           associated to a **.diff.gz** or a single **.tar.gz**(in that case the
           package is said to be _native_).  Optionally the original tarball
           might be accompanied by a detached upstream signature
           **.orig.tar.gz.asc** , extraction supported since dpkg 1.18.5.
    
           **Note** : On some vendors, dpkg has been made to permit native sources
           with non-native versions, making this incoherent and adding to the
           confusion of the concept, where in addition this tends to be a
           trap for accidental mistakes.
    
           **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 **.orig.tar.gz** and then applying the
           patch contained in the **.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.
    
           **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 **.diff.gz** by comparing the source package
           _directory_ with the .orig directory.
    
           **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 **dpkg-source** will
           look for the original source tarfile
           _package_**_**_upstream-version_**.orig.tar.gz** or the original source
           directory _directory_**.orig** depending on the **-sX** arguments.
    
           **-sa** , **-sp** , **-sk** , **-su** and **-sr** will not overwrite existing tarfiles or
           directories.  If this is desired then **-sA** , **-sP** , **-sK** , **-sU** and **-sR**
           should be used instead.
    
           **-sk** Specifies to expect the original source as a tarfile, by
               default _package_**_**_upstream-version_**.orig.tar.**_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 _directory_**.orig** for the
               generation of the diff.
    
           **-sp** Like **-sk** but will remove the directory again afterwards.
    
           **-su** Specifies that the original source is expected as a directory,
               by default _package_**-**_upstream-version_**.orig** and **dpkg-source** will
               create a new original source archive from it.
    
           **-sr** Like **-su** but will remove that directory after it has been
               used.
    
           **-ss** Specifies that the original source is available both as a
               directory and as a tarfile.  **dpkg-source** will use the
               directory to create the diff, but the tarfile to create the
               **.dsc**.  This option must be used with care - if the directory
               and tarfile do not match a bad source archive will be
               generated.
    
           **-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.
    
           **-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 **-sn**).
               If a tarfile is found it will unpack it to create the diff and
               remove it afterwards (this is equivalent to **-sp**); if a
               directory is found it will pack it to create the original
               source and remove it afterwards (this is equivalent to **-sr**);
               if neither is found it will assume that the package has no
               debianization diffs, only a straightforward source archive
               (this is equivalent to **-sn**).  If both are found then
               **dpkg-source** will ignore the directory, overwriting it, if **-sA**
               was specified (this is equivalent to **-sP**) or raise an error if
               **-sa** was specified.  **-sa** is the default.
    
           **--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 **debian/source/options** but can be
               used in **debian/source/local-options**.
    
           **Extract options (with --extract):**
    
           In all cases any existing original source tree will be removed.
    
           **-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.  (**This is the default**).
    
           **-su** Unpacks the original source tree.
    
           **-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.
    
           All the **-s** _X_ options are mutually exclusive.  If you specify more
           than one only the last one will be used.
    
           **--skip-debianization**
               Skips application of the debian diff on top of the upstream
               sources (since dpkg 1.15.1).
    
       **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 behavior 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 **debian/patches/** matching the perl regular expression
           **[\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 **zz_debian-diff-auto**.
    
       **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 **-I** option in the **--help** output).
    
           **Note** : On some vendors, dpkg has been made to permit native sources
           with non-native versions, making this incoherent and adding to the
           confusion of the concept, where in addition this tends to be a
           trap for accidental mistakes.
    
       **Format: 3.0 (quilt)**
           Supported since dpkg 1.14.17.  A source package in this format
           contains at least an original tarball (**.orig.tar.**_ext_ where _ext_ can
           be **gz** , **bz2** , **lzma** and **xz**) and a debian tarball (**.debian.tar.**_ext_).
           It can also contain additional original tarballs
           (**.orig-**_component_**.tar.**_ext_).  _component_ can only contain
           alphanumeric (‘a-zA-Z0-9’) characters and hyphens (‘-’).
           Optionally each original tarball can be accompanied by a detached
           upstream signature (**.orig.tar.**_ext_**.asc** and
           **.orig-**_component_**.tar.**_ext_**.asc**), extraction supported since dpkg
           1.17.20, building supported since dpkg 1.18.5.
    
           **Extracting**
    
           The main original tarball is extracted first, then all additional
           original tarballs are extracted in subdirectories named after the
           _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 **debian**
           directory.  Note that the debian tarball must contain a **debian**
           sub-directory but it can also contain binary files outside of that
           directory (see **--include-binaries** option).
    
           All patches listed in **debian/patches/**_vendor_**.series** or
           **debian/patches/series** are then applied, where _vendor_ will be the
           lowercase name of the current vendor, or **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 **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 **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
           **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 **-p1** option of
           **patch**.  It will thus emit a warning when it encounters such
           options, and the build is likely to fail.
    
           Note that **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 «**--profile dpkg** » to
           **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 **quilt** 's default behavior, patches are expected to
           apply without any fuzz.  When that is not the case, you should
           refresh such patches with **quilt** , or **dpkg-source** will error out
           while trying to apply them.
    
           Similarly to **quilt** 's default behavior, the patches can remove
           files too.
    
           The file **.pc/applied-patches** is created if some patches have been
           applied during the extraction.
    
           **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
           (**debian-changes-**_version_ or **debian-changes** , depending on
           **--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 **--single-debian-patch** or
           **--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 **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 **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
           **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 **-i** option in the **--help** output).  In particular, the
           **.pc** directory used by **quilt** is ignored during generation of the
           automatic patch.
    
           **Note** : **dpkg-source --before-build**(and **--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 **series** file but
           not in **.pc/applied-patches**), and if the first patch in that set
           can be applied without errors, it will apply them all.  The option
           **--no-preparation** can be used to disable this behavior.
    
           **Recording changes**
    
           **--commit**[_directory_] [_patch-name_] [_patch-file_]
               Generates a patch corresponding to the local changes that are
               not managed by the **quilt** patch system and integrates it in the
               patch system under the name _patch-name_.  If the name is
               missing, it will be asked interactively.  If _patch-file_ is
               given, it is used as the patch corresponding to the local
               changes to integrate.  Once integrated, an editor (the first
               one found from **sensible-editor** , $VISUAL, $EDITOR, **vi**) is
               launched so that you can edit the meta-information in the
               patch header.
    
               Passing _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 **debian/source/include-binaries**
               so that they end up in the debian tarball (exactly like
               **dpkg-source --include-binaries --build** would do).
    
           **Build options**
    
           **--allow-version-of-quilt-db=**_version_
               Allow **dpkg-source** to build the source package if the version
               of the **quilt** metadata is the one specified, even if
               **dpkg-source** doesn't know about it (since dpkg 1.15.5.4).
               Effectively this says that the given version of the **quilt**
               metadata is compatible with the version 2 that **dpkg-source**
               currently supports.  The version of the **quilt** metadata is
               stored in **.pc/.version**.
    
           **--include-removal**
               Do not ignore removed files and include them in the
               automatically generated patch.
    
           **--include-timestamp**
               Include timestamp in the automatically generated patch.
    
           **--include-binaries**
               Add all modified binaries in the debian tarball.  Also add
               them to **debian/source/include-binaries** : they will be added by
               default in subsequent builds and this option is thus no more
               needed.
    
           **--no-preparation**
               Do not try to prepare the build tree by applying patches which
               are apparently unapplied (since dpkg 1.14.18).
    
           **--single-debian-patch**
               Use **debian/patches/debian-changes** instead of
               **debian/patches/debian-changes-**_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
               **debian/source/local-options** and would be accompanied by a
               **debian/source/local-patch-header** file explaining how the
               Debian changes can be best reviewed, for example in the VCS
               that is used.
    
           **--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.
    
           **--no-unapply-patches, --unapply-patches**
               By default, **dpkg-source** will automatically unapply the patches
               in the **--after-build** hook if it did apply them during
               **--before-build**(**--unapply-patches** since dpkg 1.15.8,
               **--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
               **debian/source/local-options** so that all generated source
               packages have the same behavior by default.
    
           **--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 **quilt** patches
               prior to the source package build.  This option is not allowed
               in **debian/source/options** but can be used in
               **debian/source/local-options**.
    
           **--auto-commit**
               The process doesn't fail if an automatic patch has been
               generated, instead it's immediately recorded in the **quilt**
               series.
    
           **Extract options**
    
           **--skip-debianization**
               Skips extraction of the debian tarball on top of the upstream
               sources (since dpkg 1.15.1).
    
           **--skip-patches**
               Do not apply patches at the end of the extraction (since dpkg
               1.14.18).
    
       **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.
    
           **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.
    
           **--target-format=**_value_
               **Required**.  Defines the real format of the generated source
               package.  The generated .dsc file will contain this value in
               its **Format** field and not “3.0 (custom)”.
    
       **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 **.git** to hold the source of a package.  There may
           also be a **.gitshallow** file listing revisions for a shallow git
           clone.
    
           **Extracting**
    
           The bundle is cloned as a git repository to the target directory.
           If there is a gitshallow file, it is installed as _.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 _remotes/origin/_.
    
           **Building**
    
           Before going any further, some checks are done to ensure that we
           don't have any non-ignored uncommitted changes.
    
           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.
    
           **Build options**
    
           **--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 _ref_ can be the
               name of a branch or tag to include.  It may also be any
               parameter that can be passed to git-rev-list(1).  For example,
               to include only the main branch, use **--git-ref=** main.  To
               include all tags and branches, except for the private branch,
               use **--git-ref=** --all **--git-ref=** ^private
    
           **--git-depth=**_number_
               Creates a shallow clone with a history truncated to the
               specified number of revisions.
    
       **Format: 3.0 (bzr)**
           Supported since dpkg 1.14.17.  This format is experimental.  It
           generates a single tarball containing the bzr repository.
    
           **Extracting**
    
           The tarball is unpacked and then bzr is used to checkout the
           current branch.
    
           **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.
    


## DIAGNOSTICS



       **no source format specified in debian/source/format**
           The file **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 **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 **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
           **debian/source/format**.
    
       **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.
    
       [1mcannot represent change to _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.
    
       **newly created empty file _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.
    
       **executable mode _perms_ of _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.
    
       **special mode _perms_ of _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.
    


## ENVIRONMENT



           **DPKG_COLORS**
               Sets the color mode (since dpkg 1.18.5).  The currently
               accepted values are: **auto**(default), **always** and **never**.
    
           **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: **0** and **1**
               (default).
    
           **SOURCE_DATE_EPOCH**
               If set, it will be used as the timestamp (as seconds since the
               epoch) to clamp the mtime in the **tar**(5) file entries.
    
               Since dpkg 1.18.11.
    
           **VISUAL**
           **EDITOR**
               Used by the “2.0” and “3.0 (quilt)” source format modules.
    
           **GIT_DIR**
           **GIT_INDEX_FILE**
           **GIT_OBJECT_DIRECTORY**
           **GIT_ALTERNATE_OBJECT_DIRECTORIES**
           **GIT_WORK_TREE**
               Used by the “3.0 (git)” source format modules.
    


## FILES



       **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.
    
       **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 ‘**#** ’ are comments and are skipped.
           Empty lines are ignored.
    
       **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
           **dpkg-source --build** or **dpkg-source --print-format** call.  Options
           like **--compression** and **--compression-level** are well suited for
           this file.
    
           Each option should be put on a separate line.  Empty lines and
           lines starting with ‘**#** ’ are ignored.  The leading ‘**--** ’ should be
           stripped and short options are not allowed.  Optional spaces are
           allowed around the ‘**=** ’ 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)$"
    
           **Note** : **format** options are not accepted in this file, you should use
           **debian/source/format** instead.
    
       **debian/source/local-options**
           Exactly like **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.
    
       **debian/source/local-patch-header**
       **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)”.  **local-patch-header** is not
           included in the generated source package while **patch-header** is.
    
       **debian/patches/_vendor_.series**
       **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 _vendor_ will be the lowercase
           name of the current vendor, or **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 ‘**#** ’ are
           comments and are skipped.  Empty lines are ignored.  Remaining
           lines start with a patch filename (relative to the **debian/patches/**
           directory) up to the first space character or the end of line.
           Optional **quilt** options can follow up to the end of line or the
           first ‘**#** ’ preceded by one or more spaces (which marks the start of
           a comment up to the end of line).
    


## SECURITY



           Examining untrusted source packages or extracting them into
           staging directories should be considered a security boundary, and
           any breakage of that boundary stemming from these operations
           should be considered a security vulnerability.  But handling
           untrusted source packages should not be done lightly, as the
           surface area includes any compression command supported, commands
           to handle specific data formats (such as tar(1) or patch(1)) in
           addition to the source package formats and control files
           themselves.  Performing these operations over untrusted data as
           root is strongly discouraged.
    
           Building source packages should only be performed over trusted
           data.
    


## BUGS



           The point at which field overriding occurs compared to certain
           standard output field settings is rather confused.
    


* * *