dpkg-source

       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 sep-
       arate 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 argu-
              ment 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 con-
              taining 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,  addi-
              tional 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 --for-
              mat    command    line   option,   the   format   indicated   in
              debian/source/format, "1.0".  The fallback to  "1.0"  is  depre-
              cated  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
              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  pack-
              age  (dpkg-buildpackage  calls it last). This command is idempo-
              tent 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.

       --version
              Show the version and exit.

OPTIONS
   Generic build options
       -ccontrol-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.

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

       -Fchangelog-format
              Specifies   the   format   of   the   changelog.  See  dpkg-par-
              sechangelog(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.

       -Vname=value
              Set an output substitution variable.  See deb-substvars(5) for a
              discussion of output substitution.

       -Tsubstvars-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).
              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.

       -zlevel, --compression-level=level
              Compression   level   to  use  (--compression-level  since  dpkg
              1.15.5).  As with -Z it only affects newly created  files.  Sup-
              ported 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 ver-
              sion 3 source package using a VCS, this can be  used  to  ignore
              uncommited 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 con-
              trol 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,  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 direc-
              tories 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, -ICVS will make tar skip over CVS directories when gen-
              erating 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

       documentation.

       The default regex and patterns for both options can be seen in the out-
       put 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).

       --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, one of the ven-
              dor-specific keyrings, or one of the  official  Debian  keyrings
              (/usr/share/keyrings/debian-keyring.gpg                      and
              /usr/share/keyrings/debian-maintainers.gpg).

       --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 neces-
              sary when extracting ancient source packages  with  broken  ver-
              sions, just for backwards compatibility.

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 asso-
       ciated  to  a .diff.gz or a single .tar.gz (in that case the package is
       said to be native).

       Extracting

       Extracting a native package is a simple extraction of the  single  tar-
       ball  in  the target directory. Extracting a non-native package is done
       by first unpacking the .orig.tar.gz and then applying  the  patch  con-
       tained  in  the  .diff.gz  file.  The timestamp of all patched files is
       reset to the extraction time of the source package (this  avoids  time-
       stamp  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).

       Building

       Building  a  native  package is just creating a single tarball with the
       source directory. Building a non-native package involves extracting the

       -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 direc-
              tory  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 gener-
              ate 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 debianisa-
              tion 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 debianisation 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.
       All  the  -sX  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 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
       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).

   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  con-
       tain additional original tarballs (.orig-component.tar.ext).  component
       can only contain alphanumeric characters and hyphens ('-').

       Extracting

       The main original tarball is extracted first, then all additional orig-
       inal 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 tar-
       ball 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/debian.series     or
       debian/patches/series are then applied.  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.  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 expect
       patches that can be applied with the -p1 option of patch. It will  thus
       Similarly  to  quilt's  default behaviour, 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
       whitelisted 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  spe-
       cific  files as well as many temporary files (see default value associ-
       ated to -i option in the --help output). In particular, the .pc  direc-
       tory 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 inte-
              grate. Once integrated, an editor 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

       --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 ver-
              sion of the quilt metadata is stored in .pc/.version.

       --include-removal
              Do not ignore removed files and include them  in  the  automati-
              cally 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 auto-
              matic 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-unap-
              ply-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.

       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 rep-
       resent  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  gener-
       ated  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  pack-
              age.   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
       "master", but it could be anything.)  Any other branches will be avail-
       able 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
              Creates  a  shallow clone with a history truncated to the speci-
              fied number of revisions.

   Format: 3.0 (bzr)
       Supported since dpkg 1.14.17.  This format is experimental.  It  gener-
       ates 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 undocu-
       mented  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.

   cannot 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 some-
       thing  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.

       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 binary files (one per line) 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  pack-
       age is maintained.

   debian/source/local-patch-header and 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/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 spa-
       ces  are  stripped.   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).
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2019 Hurricane Electric. All Rights Reserved.