1dpkg-source(1)                    dpkg suite                    dpkg-source(1)
2
3
4

NAME

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

SYNOPSIS

9       dpkg-source [option...] command
10

DESCRIPTION

12       dpkg-source packs and unpacks Debian source archives.
13
14       None of these commands allow multiple options to be combined into one,
15       and they do not allow the value for an option to be specified in a
16       separate argument.
17

COMMANDS

19       -x, --extract filename.dsc [output-directory]
20           Extract a source package (--extract since dpkg 1.17.14).  One non-
21           option argument must be supplied, the name of the Debian source
22           control file (.dsc).  An optional second non-option argument may be
23           supplied to specify the directory to extract the source package to,
24           this must not exist. If no output directory is specified, the
25           source package is extracted into a directory named source-version
26           under the current working directory.
27
28           dpkg-source will read the names of the other file(s) making up the
29           source package from the control file; they are assumed to be in the
30           same directory as the .dsc.
31
32           The files in the extracted package will have their permissions and
33           ownerships set to those which would have been expected if the files
34           and directories had simply been created - directories and
35           executable files will be 0777 and plain files will be 0666, both
36           modified by the extractors' umask; if the parent directory is
37           setgid then the extracted directories will be too, and all the
38           files and directories will inherit its group ownership.
39
40           If the source package uses a non-standard format (currently this
41           means all formats except “1.0”), its name will be stored in
42           debian/source/format so that the following builds of the source
43           package use the same format by default.
44
45       -b, --build directory [format-specific-parameters]
46           Build a source package (--build since dpkg 1.17.14).  The first
47           non-option argument is taken as the name of the directory
48           containing the debianized source tree (i.e. with a debian sub-
49           directory and maybe changes to the original files).  Depending on
50           the source package format used to build the package, additional
51           parameters might be accepted.
52
53           dpkg-source will build the source package with the first format
54           found in this ordered list: the format indicated with the --format
55           command line option, the format indicated in debian/source/format,
56           “1.0”.  The fallback to “1.0” is deprecated and will be removed at
57           some point in the future, you should always document the desired
58           source format in debian/source/format. See section SOURCE PACKAGE
59           FORMATS for an extensive description of the various source package
60           formats.
61
62       --print-format directory
63           Print the source format that would be used to build the source
64           package if dpkg-source --build directory was called (in the same
65           conditions and with the same parameters; since dpkg 1.15.5).
66
67       --before-build directory
68           Run the corresponding hook of the source package format (since dpkg
69           1.15.8).  This hook is called before any build of the package
70           (dpkg-buildpackage calls it very early even before debian/rules
71           clean). This command is idempotent and can be called multiple
72           times. Not all source formats implement something in this hook, and
73           those that do usually prepare the source tree for the build for
74           example by ensuring that the Debian patches are applied.
75
76       --after-build directory
77           Run the corresponding hook of the source package format (since dpkg
78           1.15.8).  This hook is called after any build of the package (dpkg-
79           buildpackage calls it last). This command is idempotent and can be
80           called multiple times. Not all source formats implement something
81           in this hook, and those that do usually use it to undo what
82           --before-build has done.
83
84       --commit [directory] ...
85           Record changes in the source tree unpacked in directory (since dpkg
86           1.16.1).  This command can take supplementary parameters depending
87           on the source format.  It will error out for formats where this
88           operation doesn't mean anything.
89
90       -?, --help
91           Show the usage message and exit.  The format specific build and
92           extract options can be shown by using the --format option.
93
94       --version
95           Show the version and exit.
96

OPTIONS

98   Generic build options
99       -ccontrol-file
100           Specifies the main source control file to read information from.
101           The default is debian/control.  If given with relative pathname
102           this is interpreted starting at the source tree's top level
103           directory.
104
105       -lchangelog-file
106           Specifies the changelog file to read information from. The default
107           is debian/changelog.  If given with relative pathname this is
108           interpreted starting at the source tree's top level directory.
109
110       -Fchangelog-format
111           Specifies the format of the changelog. See dpkg-parsechangelog(1)
112           for information about alternative formats.
113
114       --format=value
115           Use the given format for building the source package (since dpkg
116           1.14.17).  It does override any format given in
117           debian/source/format.
118
119       -Vname=value
120           Set an output substitution variable.  See deb-substvars(5) for a
121           discussion of output substitution.
122
123       -Tsubstvars-file
124           Read substitution variables in substvars-file; the default is to
125           not read any file. This option can be used multiple times to read
126           substitution variables from multiple files (since dpkg 1.15.6).
127
128       -Dfield=value
129           Override or add an output control file field.
130
131       -Ufield
132           Remove an output control file field.
133
134       -Zcompression, --compression=compression
135           Specify the compression to use for created tarballs and diff files
136           (--compression since dpkg 1.15.5).  Note that this option will not
137           cause existing tarballs to be recompressed, it only affects new
138           files. Supported values are: gzip, bzip2, lzma and xz.  The default
139           is xz for formats 2.0 and newer, and gzip for format 1.0. xz is
140           only supported since dpkg 1.15.5.
141
142       -zlevel, --compression-level=level
143           Compression level to use (--compression-level since dpkg 1.15.5).
144           As with -Z it only affects newly created files. Supported values
145           are: 1 to 9, best, and fast.  The default is 9 for gzip and bzip2,
146           6 for xz and lzma.
147
148       -i[regex], --diff-ignore[=regex]
149           You may specify a perl regular expression to match files you want
150           filtered out of the list of files for the diff (--diff-ignore since
151           dpkg 1.15.6).  (This list is generated by a find command.) (If the
152           source package is being built as a version 3 source package using a
153           VCS, this can be used to ignore uncommitted changes on specific
154           files. Using -i.* will ignore all of them.)
155
156           The -i option by itself enables this setting with a default regex
157           (preserving any modification to the default regex done by a
158           previous use of --extend-diff-ignore) that will filter out control
159           files and directories of the most common revision control systems,
160           backup and swap files and Libtool build output directories. There
161           can only be one active regex, of multiple -i options only the last
162           one will take effect.
163
164           This is very helpful in cutting out extraneous files that get
165           included in the diff, e.g. if you maintain your source in a
166           revision control system and want to use a checkout to build a
167           source package without including the additional files and
168           directories that it will usually contain (e.g. CVS/, .cvsignore,
169           .svn/). The default regex is already very exhaustive, but if you
170           need to replace it, please note that by default it can match any
171           part of a path, so if you want to match the begin of a filename or
172           only full filenames, you will need to provide the necessary anchors
173           (e.g. ‘(^|/)’, ‘($|/)’) yourself.
174
175       --extend-diff-ignore=regex
176           The perl regular expression specified will extend the default value
177           used by --diff-ignore and its current value, if set (since dpkg
178           1.15.6).  It does this by concatenating “|regex” to the existing
179           value.  This option is convenient to use in debian/source/options
180           to exclude some auto-generated files from the automatic patch
181           generation.
182
183       -I[file-pattern], --tar-ignore[=file-pattern]
184           If this option is specified, the pattern will be passed to tar(1)'s
185           --exclude option when it is called to generate a .orig.tar or .tar
186           file (--tar-ignore since dpkg 1.15.6).  For example, -ICVS will
187           make tar skip over CVS directories when generating a .tar.gz file.
188           The option may be repeated multiple times to list multiple patterns
189           to exclude.
190
191           -I by itself adds default --exclude options that will filter out
192           control files and directories of the most common revision control
193           systems, backup and swap files and Libtool build output
194           directories.
195
196       Note: While they have similar purposes, -i and -I have very different
197       syntax and semantics. -i can only be specified once and takes a perl
198       compatible regular expression which is matched against the full
199       relative path of each file. -I can specified multiple times and takes a
200       filename pattern with shell wildcards.  The pattern is applied to the
201       full relative path but also to each part of the path individually. The
202       exact semantic of tar's --exclude option is somewhat complicated, see
203       <https://www.gnu.org/software/tar/manual/tar.html#wildcards> for a full
204       documentation.
205
206       The default regex and patterns for both options can be seen in the
207       output of the --help command.
208
209   Generic extract options
210       --no-copy
211           Do not copy original tarballs near the extracted source package
212           (since dpkg 1.14.17).
213
214       --no-check
215           Do not check signatures and checksums before unpacking (since dpkg
216           1.14.17).
217
218       --no-overwrite-dir
219           Do not overwrite the extraction directory if it already exists
220           (since dpkg 1.18.8).
221
222       --require-valid-signature
223           Refuse to unpack the source package if it doesn't contain an
224           OpenPGP signature that can be verified (since dpkg 1.15.0) either
225           with the user's trustedkeys.gpg keyring, one of the vendor-specific
226           keyrings, or one of the official Debian keyrings
227           (/usr/share/keyrings/debian-keyring.gpg,
228           /usr/share/keyrings/debian-nonupload.gpg and
229           /usr/share/keyrings/debian-maintainers.gpg).
230
231       --require-strong-checksums
232           Refuse to unpack the source package if it does not contain any
233           strong checksums (since dpkg 1.18.7).  Currently the only known
234           checksum considered strong is SHA-256.
235
236       --ignore-bad-version
237           Turns the bad source package version check into a non-fatal warning
238           (since dpkg 1.17.7).  This option should only be necessary when
239           extracting ancient source packages with broken versions, just for
240           backwards compatibility.
241

SOURCE PACKAGE FORMATS

243       If you don't know what source format to use, you should probably pick
244       either “3.0 (quilt)” or “3.0 (native)”.  See
245       <https://wiki.debian.org/Projects/DebSrc3.0> for information on the
246       deployment of those formats within Debian.
247
248   Format: 1.0
249       A source package in this format consists either of a .orig.tar.gz
250       associated to a .diff.gz or a single .tar.gz (in that case the package
251       is said to be native).  Optionally the original tarball might be
252       accompanied by a detached upstream signature .orig.tar.gz.asc,
253       extraction supported since dpkg 1.18.5.
254
255       Extracting
256
257       Extracting a native package is a simple extraction of the single
258       tarball in the target directory. Extracting a non-native package is
259       done by first unpacking the .orig.tar.gz and then applying the patch
260       contained in the .diff.gz file. The timestamp of all patched files is
261       reset to the extraction time of the source package (this avoids
262       timestamp skews leading to problems when autogenerated files are
263       patched). The diff can create new files (the whole debian directory is
264       created that way) but cannot remove files (empty files will be left
265       over) and cannot create or change symlinks.
266
267       Building
268
269       Building a native package is just creating a single tarball with the
270       source directory. Building a non-native package involves extracting the
271       original tarball in a separate “.orig” directory and regenerating the
272       .diff.gz by comparing the source package directory with the .orig
273       directory.
274
275       Build options (with --build):
276
277       If a second non-option argument is supplied it should be the name of
278       the original source directory or tarfile or the empty string if the
279       package is a Debian-specific one and so has no debianization diffs. If
280       no second argument is supplied then dpkg-source will look for the
281       original source tarfile package_upstream-version.orig.tar.gz or the
282       original source directory directory.orig depending on the -sX
283       arguments.
284
285       -sa, -sp, -sk, -su and -sr will not overwrite existing tarfiles or
286       directories. If this is desired then -sA, -sP, -sK, -sU and -sR should
287       be used instead.
288
289       -sk Specifies to expect the original source as a tarfile, by default
290           package_upstream-version.orig.tar.extension.  It will leave this
291           original source in place as a tarfile, or copy it to the current
292           directory if it isn't already there. The tarball will be unpacked
293           into directory.orig for the generation of the diff.
294
295       -sp Like -sk but will remove the directory again afterwards.
296
297       -su Specifies that the original source is expected as a directory, by
298           default package-upstream-version.orig and dpkg-source will create a
299           new original source archive from it.
300
301       -sr Like -su but will remove that directory after it has been used.
302
303       -ss Specifies that the original source is available both as a directory
304           and as a tarfile. dpkg-source will use the directory to create the
305           diff, but the tarfile to create the .dsc.  This option must be used
306           with care - if the directory and tarfile do not match a bad source
307           archive will be generated.
308
309       -sn Specifies to not look for any original source, and to not generate
310           a diff.  The second argument, if supplied, must be the empty
311           string. This is used for Debian-specific packages which do not have
312           a separate upstream source and therefore have no debianization
313           diffs.
314
315       -sa or -sA
316           Specifies to look for the original source archive as a tarfile or
317           as a directory - the second argument, if any, may be either, or the
318           empty string (this is equivalent to using -sn).  If a tarfile is
319           found it will unpack it to create the diff and remove it afterwards
320           (this is equivalent to -sp); if a directory is found it will pack
321           it to create the original source and remove it afterwards (this is
322           equivalent to -sr); if neither is found it will assume that the
323           package has no debianization diffs, only a straightforward source
324           archive (this is equivalent to -sn).  If both are found then dpkg-
325           source will ignore the directory, overwriting it, if -sA was
326           specified (this is equivalent to -sP) or raise an error if -sa was
327           specified.  -sa is the default.
328
329       --abort-on-upstream-changes
330           The process fails if the generated diff contains changes to files
331           outside of the debian sub-directory (since dpkg 1.15.8).  This
332           option is not allowed in debian/source/options but can be used in
333           debian/source/local-options.
334
335       Extract options (with --extract):
336
337       In all cases any existing original source tree will be removed.
338
339       -sp Used when extracting then the original source (if any) will be left
340           as a tarfile. If it is not already located in the current directory
341           or if an existing but different file is there it will be copied
342           there.  (This is the default).
343
344       -su Unpacks the original source tree.
345
346       -sn Ensures that the original source is neither copied to the current
347           directory nor unpacked. Any original source tree that was in the
348           current directory is still removed.
349
350       All the -sX options are mutually exclusive. If you specify more than
351       one only the last one will be used.
352
353       --skip-debianization
354           Skips application of the debian diff on top of the upstream sources
355           (since dpkg 1.15.1).
356
357   Format: 2.0
358       Extraction supported since dpkg 1.13.9, building supported since dpkg
359       1.14.8.  Also known as wig&pen. This format is not recommended for
360       wide-spread usage, the format “3.0 (quilt)” replaces it.  Wig&pen was
361       the first specification of a new-generation source package format.
362
363       The behaviour of this format is the same as the “3.0 (quilt)” format
364       except that it doesn't use an explicit list of patches. All files in
365       debian/patches/ matching the perl regular expression [\w-]+ must be
366       valid patches: they are applied at extraction time.
367
368       When building a new source package, any change to the upstream source
369       is stored in a patch named zz_debian-diff-auto.
370
371   Format: 3.0 (native)
372       Supported since dpkg 1.14.17.  This format is an extension of the
373       native package format as defined in the 1.0 format. It supports all
374       compression methods and will ignore by default any VCS specific files
375       and directories as well as many temporary files (see default value
376       associated to -I option in the --help output).
377
378   Format: 3.0 (quilt)
379       Supported since dpkg 1.14.17.  A source package in this format contains
380       at least an original tarball (.orig.tar.ext where ext can be gz, bz2,
381       lzma and xz) and a debian tarball (.debian.tar.ext). It can also
382       contain additional original tarballs (.orig-component.tar.ext).
383       component can only contain alphanumeric (‘a-zA-Z0-9’) characters and
384       hyphens (‘-’).  Optionally each original tarball can be accompanied by
385       a detached upstream signature (.orig.tar.ext.asc and
386       .orig-component.tar.ext.asc), extraction supported since dpkg 1.17.20,
387       building supported since dpkg 1.18.5.
388
389       Extracting
390
391       The main original tarball is extracted first, then all additional
392       original tarballs are extracted in subdirectories named after the
393       component part of their filename (any pre-existing directory is
394       replaced). The debian tarball is extracted on top of the source
395       directory after prior removal of any pre-existing debian directory.
396       Note that the debian tarball must contain a debian sub-directory but it
397       can also contain binary files outside of that directory (see
398       --include-binaries option).
399
400       All patches listed in debian/patches/vendor.series or
401       debian/patches/series are then applied, where vendor will be the
402       lowercase name of the current vendor, or debian if there is no vendor
403       defined.  If the former file is used and the latter one doesn't exist
404       (or is a symlink), then the latter is replaced with a symlink to the
405       former.  This is meant to simplify usage of quilt to manage the set of
406       patches.  Vendor-specific series files are intended to make it possible
407       to serialize multiple development branches based on the vendor, in a
408       declarative way, in preference to open-coding this handling in
409       debian/rules.  This is particularly useful when the source would need
410       to be patched conditionally because the affected files do not have
411       built-in conditional occlusion support.  Note however that while dpkg-
412       source parses correctly series files with explicit options used for
413       patch application (stored on each line after the patch filename and one
414       or more spaces), it does ignore those options and always expects
415       patches that can be applied with the -p1 option of patch. It will thus
416       emit a warning when it encounters such options, and the build is likely
417       to fail.
418
419       Note that lintian(1) will emit unconditional warnings when using vendor
420       series due to a controversial Debian specific ruling, which should not
421       affect any external usage; to silence these, the dpkg lintian profile
422       can be used by passing «--profile dpkg» to lintian(1).
423
424       The timestamp of all patched files is reset to the extraction time of
425       the source package (this avoids timestamp skews leading to problems
426       when autogenerated files are patched).
427
428       Contrary to quilt's default behaviour, patches are expected to apply
429       without any fuzz. When that is not the case, you should refresh such
430       patches with quilt, or dpkg-source will error out while trying to apply
431       them.
432
433       Similarly to quilt's default behaviour, the patches can remove files
434       too.
435
436       The file .pc/applied-patches is created if some patches have been
437       applied during the extraction.
438
439       Building
440
441       All original tarballs found in the current directory are extracted in a
442       temporary directory by following the same logic as for the unpack, the
443       debian directory is copied over in the temporary directory, and all
444       patches except the automatic patch (debian-changes-version or debian-
445       changes, depending on --single-debian-patch) are applied. The temporary
446       directory is compared to the source package directory. When the diff is
447       non-empty, the build fails unless --single-debian-patch or
448       --auto-commit has been used, in which case the diff is stored in the
449       automatic patch.  If the automatic patch is created/deleted, it's
450       added/removed from the series file and from the quilt metadata.
451
452       Any change on a binary file is not representable in a diff and will
453       thus lead to a failure unless the maintainer deliberately decided to
454       include that modified binary file in the debian tarball (by listing it
455       in debian/source/include-binaries). The build will also fail if it
456       finds binary files in the debian sub-directory unless they have been
457       allowed through debian/source/include-binaries.
458
459       The updated debian directory and the list of modified binaries is then
460       used to generate the debian tarball.
461
462       The automatically generated diff doesn't include changes on VCS
463       specific files as well as many temporary files (see default value
464       associated to -i option in the --help output). In particular, the .pc
465       directory used by quilt is ignored during generation of the automatic
466       patch.
467
468       Note: dpkg-source --before-build (and --build) will ensure that all
469       patches listed in the series file are applied so that a package build
470       always has all patches applied. It does this by finding unapplied
471       patches (they are listed in the series file but not in
472       .pc/applied-patches), and if the first patch in that set can be applied
473       without errors, it will apply them all. The option --no-preparation can
474       be used to disable this behavior.
475
476       Recording changes
477
478       --commit [directory] [patch-name] [patch-file]
479           Generates a patch corresponding to the local changes that are not
480           managed by the quilt patch system and integrates it in the patch
481           system under the name patch-name. If the name is missing, it will
482           be asked interactively. If patch-file is given, it is used as the
483           patch corresponding to the local changes to integrate. Once
484           integrated, an editor is launched so that you can edit the meta-
485           information in the patch header.
486
487           Passing patch-file is mainly useful after a build failure that pre-
488           generated this file, and on this ground the given file is removed
489           after integration. Note also that the changes contained in the
490           patch file must already be applied on the tree and that the files
491           modified by the patch must not have supplementary unrecorded
492           changes.
493
494           If the patch generation detects modified binary files, they will be
495           automatically added to debian/source/include-binaries so that they
496           end up in the debian tarball (exactly like dpkg-source
497           --include-binaries --build would do).
498
499       Build options
500
501       --allow-version-of-quilt-db=version
502           Allow dpkg-source to build the source package if the version of the
503           quilt metadata is the one specified, even if dpkg-source doesn't
504           know about it (since dpkg 1.15.5.4).  Effectively this says that
505           the given version of the quilt metadata is compatible with the
506           version 2 that dpkg-source currently supports. The version of the
507           quilt metadata is stored in .pc/.version.
508
509       --include-removal
510           Do not ignore removed files and include them in the automatically
511           generated patch.
512
513       --include-timestamp
514           Include timestamp in the automatically generated patch.
515
516       --include-binaries
517           Add all modified binaries in the debian tarball. Also add them to
518           debian/source/include-binaries: they will be added by default in
519           subsequent builds and this option is thus no more needed.
520
521       --no-preparation
522           Do not try to prepare the build tree by applying patches which are
523           apparently unapplied (since dpkg 1.14.18).
524
525       --single-debian-patch
526           Use debian/patches/debian-changes instead of
527           debian/patches/debian-changes-version for the name of the automatic
528           patch generated during build (since dpkg 1.15.5.4).  This option is
529           particularly useful when the package is maintained in a VCS and a
530           patch set can't reliably be generated. Instead the current diff
531           with upstream should be stored in a single patch. The option would
532           be put in debian/source/local-options and would be accompanied by a
533           debian/source/local-patch-header file explaining how the Debian
534           changes can be best reviewed, for example in the VCS that is used.
535
536       --create-empty-orig
537           Automatically create the main original tarball as empty if it's
538           missing and if there are supplementary original tarballs (since
539           dpkg 1.15.6).  This option is meant to be used when the source
540           package is just a bundle of multiple upstream software and where
541           there's no “main” software.
542
543       --no-unapply-patches, --unapply-patches
544           By default, dpkg-source will automatically unapply the patches in
545           the --after-build hook if it did apply them during --before-build
546           (--unapply-patches since dpkg 1.15.8, --no-unapply-patches since
547           dpkg 1.16.5).  Those options allow you to forcefully disable or
548           enable the patch unapplication process. Those options are only
549           allowed in debian/source/local-options so that all generated source
550           packages have the same behavior by default.
551
552       --abort-on-upstream-changes
553           The process fails if an automatic patch has been generated (since
554           dpkg 1.15.8).  This option can be used to ensure that all changes
555           were properly recorded in separate quilt patches prior to the
556           source package build. This option is not allowed in
557           debian/source/options but can be used in
558           debian/source/local-options.
559
560       --auto-commit
561           The process doesn't fail if an automatic patch has been generated,
562           instead it's immediately recorded in the quilt series.
563
564       Extract options
565
566       --skip-debianization
567           Skips extraction of the debian tarball on top of the upstream
568           sources (since dpkg 1.15.1).
569
570       --skip-patches
571           Do not apply patches at the end of the extraction (since dpkg
572           1.14.18).
573
574   Format: 3.0 (custom)
575       Supported since dpkg 1.14.17.  This format is special.  It doesn't
576       represent a real source package format but can be used to create source
577       packages with arbitrary files.
578
579       Build options
580
581       All non-option arguments are taken as files to integrate in the
582       generated source package. They must exist and are preferably in the
583       current directory. At least one file must be given.
584
585       --target-format=value
586           Required. Defines the real format of the generated source package.
587           The generated .dsc file will contain this value in its Format field
588           and not “3.0 (custom)”.
589
590   Format: 3.0 (git)
591       Supported since dpkg 1.14.17.  This format is experimental.
592
593       A source package in this format consists of a single bundle of a git
594       repository .git to hold the source of a package.  There may also be a
595       .gitshallow file listing revisions for a shallow git clone.
596
597       Extracting
598
599       The bundle is cloned as a git repository to the target directory.  If
600       there is a gitshallow file, it is installed as .git/shallow inside the
601       cloned git repository.
602
603       Note that by default the new repository will have the same branch
604       checked out that was checked out in the original source.  (Typically
605       “main”, but it could be anything.)  Any other branches will be
606       available under remotes/origin/.
607
608       Building
609
610       Before going any further, some checks are done to ensure that we don't
611       have any non-ignored uncommitted changes.
612
613       git-bundle(1) is used to generate a bundle of the git repository.  By
614       default, all branches and tags in the repository are included in the
615       bundle.
616
617       Build options
618
619       --git-ref=ref
620           Allows specifying a git ref to include in the git bundle. Use
621           disables the default behavior of including all branches and tags.
622           May be specified multiple times. The ref can be the name of a
623           branch or tag to include. It may also be any parameter that can be
624           passed to git-rev-list(1). For example, to include only the main
625           branch, use --git-ref=main. To include all tags and branches,
626           except for the private branch, use --git-ref=--all
627           --git-ref=^private
628
629       --git-depth=number
630           Creates a shallow clone with a history truncated to the specified
631           number of revisions.
632
633   Format: 3.0 (bzr)
634       Supported since dpkg 1.14.17.  This format is experimental.  It
635       generates a single tarball containing the bzr repository.
636
637       Extracting
638
639       The tarball is unpacked and then bzr is used to checkout the current
640       branch.
641
642       Building
643
644       Before going any further, some checks are done to ensure that we don't
645       have any non-ignored uncommitted changes.
646
647       Then the VCS specific part of the source directory is copied over to a
648       temporary directory. Before this temporary directory is packed in a
649       tarball, various cleanup are done to save space.
650

DIAGNOSTICS

652   no source format specified in debian/source/format
653       The file debian/source/format should always exist and indicate the
654       desired source format. For backwards compatibility, format “1.0” is
655       assumed when the file doesn't exist but you should not rely on this: at
656       some point in the future dpkg-source will be modified to fail when that
657       file doesn't exist.
658
659       The rationale is that format “1.0” is no longer the recommended format,
660       you should usually pick one of the newer formats (“3.0 (quilt)”, “3.0
661       (native)”) but dpkg-source will not do this automatically for you.  If
662       you want to continue using the old format, you should be explicit about
663       it and put “1.0” in debian/source/format.
664
665   the diff modifies the following upstream files
666       When using source format “1.0” it is usually a bad idea to modify
667       upstream files directly as the changes end up hidden and mostly
668       undocumented in the .diff.gz file. Instead you should store your
669       changes as patches in the debian directory and apply them at build-
670       time. To avoid this complexity you can also use the format “3.0
671       (quilt)” that offers this natively.
672
673   cannot represent change to file
674       Changes to upstream sources are usually stored with patch files, but
675       not all changes can be represented with patches: they can only alter
676       the content of plain text files. If you try replacing a file with
677       something of a different type (for example replacing a plain file with
678       a symlink or a directory), you will get this error message.
679
680   newly created empty file file will not be represented in diff
681       Empty files can't be created with patch files. Thus this change is not
682       recorded in the source package and you are warned about it.
683
684   executable mode perms of file will not be represented in diff
685       Patch files do not record permissions of files and thus executable
686       permissions are not stored in the source package. This warning reminds
687       you of that fact.
688
689   special mode perms of file will not be represented in diff
690       Patch files do not record permissions of files and thus modified
691       permissions are not stored in the source package. This warning reminds
692       you of that fact.
693

ENVIRONMENT

695       DPKG_COLORS
696           Sets the color mode (since dpkg 1.18.5).  The currently accepted
697           values are: auto (default), always and never.
698
699       DPKG_NLS
700           If set, it will be used to decide whether to activate Native
701           Language Support, also known as internationalization (or i18n)
702           support (since dpkg 1.19.0).  The accepted values are: 0 and 1
703           (default).
704
705       SOURCE_DATE_EPOCH
706           If set, it will be used as the timestamp (as seconds since the
707           epoch) to clamp the mtime in the tar(5) file entries.
708
709       VISUAL
710       EDITOR
711           Used by the “2.0” and “3.0 (quilt)” source format modules.
712
713       GIT_DIR
714       GIT_INDEX_FILE
715       GIT_OBJECT_DIRECTORY
716       GIT_ALTERNATE_OBJECT_DIRECTORIES
717       GIT_WORK_TREE
718           Used by the “3.0 (git)” source format modules.
719

FILES

721   debian/source/format
722       This file contains on a single line the format that should be used to
723       build the source package (possible formats are described above). No
724       leading or trailing spaces are allowed.
725
726   debian/source/include-binaries
727       This file contains a list of pathnames of binary files (one per line)
728       relative to the source root directory that should be included in the
729       debian tarball.  Leading and trailing spaces are stripped.  Lines
730       starting with ‘#’ are comments and are skipped.  Empty lines are
731       ignored.
732
733   debian/source/options
734       This file contains a list of long options that should be automatically
735       prepended to the set of command line options of a dpkg-source --build
736       or dpkg-source --print-format call. Options like --compression and
737       --compression-level are well suited for this file.
738
739       Each option should be put on a separate line. Empty lines and lines
740       starting with ‘#’ are ignored.  The leading ‘--’ should be stripped and
741       short options are not allowed.  Optional spaces are allowed around the
742=’ symbol and optional quotes are allowed around the value.  Here's an
743       example of such a file:
744
745        # let dpkg-source create a debian.tar.bz2 with maximal compression
746        compression = "bzip2"
747        compression-level = 9
748        # use debian/patches/debian-changes as automatic patch
749        single-debian-patch
750        # ignore changes on config.{sub,guess}
751        extend-diff-ignore = "(^|/)(config.sub|config.guess)$"
752
753       Note: format options are not accepted in this file, you should use
754       debian/source/format instead.
755
756   debian/source/local-options
757       Exactly like debian/source/options except that the file is not included
758       in the generated source package. It can be useful to store a preference
759       tied to the maintainer or to the VCS repository where the source
760       package is maintained.
761
762   debian/source/local-patch-header
763   debian/source/patch-header
764       Free form text that is put on top of the automatic patch generated in
765       formats “2.0” or “3.0 (quilt)”. local-patch-header is not included in
766       the generated source package while patch-header is.
767
768   debian/patches/vendor.series
769   debian/patches/series
770       This file lists all patches that have to be applied (in the given
771       order) on top of the upstream source package. Leading and trailing
772       spaces are stripped.  The vendor will be the lowercase name of the
773       current vendor, or debian if there is no vendor defined.  If the
774       vendor-specific series file does not exist, the vendor-less series file
775       will be used.  Lines starting with ‘#’ are comments and are skipped.
776       Empty lines are ignored.  Remaining lines start with a patch filename
777       (relative to the debian/patches/ directory) up to the first space
778       character or the end of line. Optional quilt options can follow up to
779       the end of line or the first ‘#’ preceded by one or more spaces (which
780       marks the start of a comment up to the end of line).
781

BUGS

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

SEE ALSO

787       deb-src-control(5), deb-changelog(5), deb-substvars(5), dsc(5).
788
789
790
7911.21.9                            2022-07-01                    dpkg-source(1)
Impressum