1dpkg-source(1) dpkg suite dpkg-source(1)
2
3
4
6 dpkg-source - Debian source package (.dsc) manipulation tool
7
9 dpkg-source [option...] command
10
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
19 -x, --extract filename.dsc [output-directory]
20 Extract a source package (--extract since dpkg 1.17.14). One
21 non-option argument must be supplied, the name of the Debian
22 source control file (.dsc). An optional second non-option
23 argument may be supplied to specify the directory to extract the
24 source package to, this must not exist. If no output directory
25 is specified, the source package is extracted into a directory
26 named source-version under the current working directory.
27
28 dpkg-source will read the names of the other file(s) making up
29 the source package from the control file; they are assumed to be
30 in the same directory as the .dsc.
31
32 The files in the extracted package will have their permissions
33 and ownerships set to those which would have been expected if
34 the files and directories had simply been created - directories
35 and executable files will be 0777 and plain files will be 0666,
36 both modified by the extractors' umask; if the parent directory
37 is setgid then the extracted directories will be too, and all
38 the 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
46 -b, --build directory [format-specific-parameters]
47 Build a source package (--build since dpkg 1.17.14). The first
48 non-option argument is taken as the name of the directory
49 containing the debianized source tree (i.e. with a debian sub-
50 directory and maybe changes to the original files). Depending
51 on the source package format used to build the package,
52 additional parameters might be accepted.
53
54 dpkg-source will build the source package with the first format
55 found in this ordered list: the format indicated with the
56 --format command line option, the format indicated in
57 debian/source/format, “1.0”. The fallback to “1.0” is
58 deprecated and will be removed at some point in the future, you
59 should always document the desired source format in
60 debian/source/format. See section SOURCE PACKAGE FORMATS for an
61 extensive description of the various source package formats.
62
63
64 --print-format directory
65 Print the source format that would be used to build the source
66 package if dpkg-source --build directory was called (in the same
67 conditions and with the same parameters; since dpkg 1.15.5).
68
69
70 --before-build directory
71 Run the corresponding hook of the source package format (since
72 dpkg 1.15.8). This hook is called before any build of the
73 package (dpkg-buildpackage calls it very early even before
74 debian/rules clean). This command is idempotent and can be
75 called multiple times. Not all source formats implement
76 something in this hook, and those that do usually prepare the
77 source tree for the build for example by ensuring that the
78 Debian patches are applied.
79
80
81 --after-build directory
82 Run the corresponding hook of the source package format (since
83 dpkg 1.15.8). This hook is called after any build of the
84 package (dpkg-buildpackage calls it last). This command is
85 idempotent and can be called multiple times. Not all source
86 formats implement something in this hook, and those that do
87 usually use it to undo what --before-build has done.
88
89
90 --commit [directory] ...
91 Record changes in the source tree unpacked in directory (since
92 dpkg 1.16.1). This command can take supplementary parameters
93 depending on the source format. It will error out for formats
94 where this operation doesn't mean anything.
95
96
97 -?, --help
98 Show the usage message and exit. The format specific build and
99 extract options can be shown by using the --format option.
100
101 --version
102 Show the version and exit.
103
105 Generic build options
106 -ccontrol-file
107 Specifies the main source control file to read information from.
108 The default is debian/control. If given with relative pathname
109 this is interpreted starting at the source tree's top level
110 directory.
111
112 -lchangelog-file
113 Specifies the changelog file to read information from. The
114 default is debian/changelog. If given with relative pathname
115 this is interpreted starting at the source tree's top level
116 directory.
117
118 -Fchangelog-format
119 Specifies the format of the changelog. See
120 dpkg-parsechangelog(1) for information about alternative
121 formats.
122
123 --format=value
124 Use the given format for building the source package (since dpkg
125 1.14.17). It does override any format given in
126 debian/source/format.
127
128 -Vname=value
129 Set an output substitution variable. See deb-substvars(5) for a
130 discussion of output substitution.
131
132 -Tsubstvars-file
133 Read substitution variables in substvars-file; the default is to
134 not read any file. This option can be used multiple times to
135 read substitution variables from multiple files (since dpkg
136 1.15.6).
137
138 -Dfield=value
139 Override or add an output control file field.
140
141 -Ufield
142 Remove an output control file field.
143
144 -Zcompression, --compression=compression
145 Specify the compression to use for created tarballs and diff
146 files (--compression since dpkg 1.15.5). Note that this option
147 will not cause existing tarballs to be recompressed, it only
148 affects new files. Supported values are: gzip, bzip2, lzma and
149 xz. The default is xz for formats 2.0 and newer, and gzip for
150 format 1.0. xz is only supported since dpkg 1.15.5.
151
152 -zlevel, --compression-level=level
153 Compression level to use (--compression-level since dpkg
154 1.15.5). As with -Z it only affects newly created files.
155 Supported values are: 1 to 9, best, and fast. The default is 9
156 for gzip and bzip2, 6 for xz and lzma.
157
158 -i[regex], --diff-ignore[=regex]
159 You may specify a perl regular expression to match files you
160 want filtered out of the list of files for the diff
161 (--diff-ignore since dpkg 1.15.6). (This list is generated by a
162 find command.) (If the source package is being built as a
163 version 3 source package using a VCS, this can be used to ignore
164 uncommitted changes on specific files. Using -i.* will ignore
165 all of them.)
166
167 The -i option by itself enables this setting with a default
168 regex (preserving any modification to the default regex done by
169 a previous use of --extend-diff-ignore) that will filter out
170 control files and directories of the most common revision
171 control systems, backup and swap files and Libtool build output
172 directories. There can only be one active regex, of multiple -i
173 options only the last one will take effect.
174
175 This is very helpful in cutting out extraneous files that get
176 included in the diff, e.g. if you maintain your source in a
177 revision control system and want to use a checkout to build a
178 source package without including the additional files and
179 directories that it will usually contain (e.g. CVS/, .cvsignore,
180 .svn/). The default regex is already very exhaustive, but if you
181 need to replace it, please note that by default it can match any
182 part of a path, so if you want to match the begin of a filename
183 or only full filenames, you will need to provide the necessary
184 anchors (e.g. ‘(^|/)’, ‘($|/)’) yourself.
185
186 --extend-diff-ignore=regex
187 The perl regular expression specified will extend the default
188 value used by --diff-ignore and its current value, if set (since
189 dpkg 1.15.6). It does this by concatenating “|regex” to the
190 existing value. This option is convenient to use in
191 debian/source/options to exclude some auto-generated files from
192 the automatic patch generation.
193
194 -I[file-pattern], --tar-ignore[=file-pattern]
195 If this option is specified, the pattern will be passed to
196 tar(1)'s --exclude option when it is called to generate a
197 .orig.tar or .tar file (--tar-ignore since dpkg 1.15.6). For
198 example, -ICVS will make tar skip over CVS directories when
199 generating a .tar.gz file. The option may be repeated multiple
200 times to list multiple patterns to exclude.
201
202 -I by itself adds default --exclude options that will filter out
203 control files and directories of the most common revision
204 control systems, backup and swap files and Libtool build output
205 directories.
206
207 Note: While they have similar purposes, -i and -I have very different
208 syntax and semantics. -i can only be specified once and takes a perl
209 compatible regular expression which is matched against the full
210 relative path of each file. -I can specified multiple times and takes a
211 filename pattern with shell wildcards. The pattern is applied to the
212 full relative path but also to each part of the path individually. The
213 exact semantic of tar's --exclude option is somewhat complicated, see
214 https://www.gnu.org/software/tar/manual/tar.html#wildcards for a full
215 documentation.
216
217 The default regex and patterns for both options can be seen in the
218 output of the --help command.
219
220 Generic extract options
221 --no-copy
222 Do not copy original tarballs near the extracted source package
223 (since dpkg 1.14.17).
224
225 --no-check
226 Do not check signatures and checksums before unpacking (since
227 dpkg 1.14.17).
228
229 --no-overwrite-dir
230 Do not overwrite the extraction directory if it already exists
231 (since dpkg 1.18.8).
232
233 --require-valid-signature
234 Refuse to unpack the source package if it doesn't contain an
235 OpenPGP signature that can be verified (since dpkg 1.15.0)
236 either with the user's trustedkeys.gpg keyring, one of the
237 vendor-specific keyrings, or one of the official Debian keyrings
238 (/usr/share/keyrings/debian-keyring.gpg and
239 /usr/share/keyrings/debian-maintainers.gpg).
240
241 --require-strong-checksums
242 Refuse to unpack the source package if it does not contain any
243 strong checksums (since dpkg 1.18.7). Currently the only known
244 checksum considered strong is SHA-256.
245
246 --ignore-bad-version
247 Turns the bad source package version check into a non-fatal
248 warning (since dpkg 1.17.7). This option should only be
249 necessary when extracting ancient source packages with broken
250 versions, just for backwards compatibility.
251
252
254 If you don't know what source format to use, you should probably pick
255 either “3.0 (quilt)” or “3.0 (native)”. See
256 https://wiki.debian.org/Projects/DebSrc3.0 for information on the
257 deployment of those formats within Debian.
258
259
260 Format: 1.0
261 A source package in this format consists either of a .orig.tar.gz
262 associated to a .diff.gz or a single .tar.gz (in that case the package
263 is said to be native). Optionally the original tarball might be
264 accompanied by a detached upstream signature .orig.tar.gz.asc,
265 extraction supported since dpkg 1.18.5.
266
267 Extracting
268
269 Extracting a native package is a simple extraction of the single
270 tarball in the target directory. Extracting a non-native package is
271 done by first unpacking the .orig.tar.gz and then applying the patch
272 contained in the .diff.gz file. The timestamp of all patched files is
273 reset to the extraction time of the source package (this avoids
274 timestamp skews leading to problems when autogenerated files are
275 patched). The diff can create new files (the whole debian directory is
276 created that way) but can't remove files (empty files will be left
277 over).
278
279 Building
280
281 Building a native package is just creating a single tarball with the
282 source directory. Building a non-native package involves extracting the
283 original tarball in a separate “.orig” directory and regenerating the
284 .diff.gz by comparing the source package directory with the .orig
285 directory.
286
287 Build options (with --build):
288
289 If a second non-option argument is supplied it should be the name of
290 the original source directory or tarfile or the empty string if the
291 package is a Debian-specific one and so has no debianization diffs. If
292 no second argument is supplied then dpkg-source will look for the
293 original source tarfile package_upstream-version.orig.tar.gz or the
294 original source directory directory.orig depending on the -sX
295 arguments.
296
297 -sa, -sp, -sk, -su and -sr will not overwrite existing tarfiles or
298 directories. If this is desired then -sA, -sP, -sK, -sU and -sR should
299 be used instead.
300
301 -sk Specifies to expect the original source as a tarfile, by default
302 package_upstream-version.orig.tar.extension. It will leave this
303 original source in place as a tarfile, or copy it to the current
304 directory if it isn't already there. The tarball will be
305 unpacked into directory.orig for the generation of the diff.
306
307 -sp Like -sk but will remove the directory again afterwards.
308
309 -su Specifies that the original source is expected as a directory,
310 by default package-upstream-version.orig and dpkg-source will
311 create a new original source archive from it.
312
313 -sr Like -su but will remove that directory after it has been used.
314
315 -ss Specifies that the original source is available both as a
316 directory and as a tarfile. dpkg-source will use the directory
317 to create the diff, but the tarfile to create the .dsc. This
318 option must be used with care - if the directory and tarfile do
319 not match a bad source archive will be generated.
320
321 -sn Specifies to not look for any original source, and to not
322 generate a diff. The second argument, if supplied, must be the
323 empty string. This is used for Debian-specific packages which do
324 not have a separate upstream source and therefore have no
325 debianization diffs.
326
327 -sa or -sA
328 Specifies to look for the original source archive as a tarfile
329 or as a directory - the second argument, if any, may be either,
330 or the empty string (this is equivalent to using -sn). If a
331 tarfile is found it will unpack it to create the diff and remove
332 it afterwards (this is equivalent to -sp); if a directory is
333 found it will pack it to create the original source and remove
334 it afterwards (this is equivalent to -sr); if neither is found
335 it will assume that the package has no debianization diffs, only
336 a straightforward source archive (this is equivalent to -sn).
337 If both are found then dpkg-source will ignore the directory,
338 overwriting it, if -sA was specified (this is equivalent to -sP)
339 or raise an error if -sa was specified. -sa is the default.
340
341 --abort-on-upstream-changes
342 The process fails if the generated diff contains changes to
343 files outside of the debian sub-directory (since dpkg 1.15.8).
344 This option is not allowed in debian/source/options but can be
345 used in debian/source/local-options.
346
347 Extract options (with --extract):
348
349 In all cases any existing original source tree will be removed.
350
351 -sp Used when extracting then the original source (if any) will be
352 left as a tarfile. If it is not already located in the current
353 directory or if an existing but different file is there it will
354 be copied there. (This is the default).
355
356 -su Unpacks the original source tree.
357
358 -sn Ensures that the original source is neither copied to the
359 current directory nor unpacked. Any original source tree that
360 was in the current directory is still removed.
361
362 All the -sX options are mutually exclusive. If you specify more than
363 one only the last one will be used.
364
365 --skip-debianization
366 Skips application of the debian diff on top of the upstream
367 sources (since dpkg 1.15.1).
368
369 Format: 2.0
370 Extraction supported since dpkg 1.13.9, building supported since dpkg
371 1.14.8. Also known as wig&pen. This format is not recommended for
372 wide-spread usage, the format “3.0 (quilt)” replaces it. Wig&pen was
373 the first specification of a new-generation source package format.
374
375 The behaviour of this format is the same as the “3.0 (quilt)” format
376 except that it doesn't use an explicit list of patches. All files in
377 debian/patches/ matching the perl regular expression [\w-]+ must be
378 valid patches: they are applied at extraction time.
379
380 When building a new source package, any change to the upstream source
381 is stored in a patch named zz_debian-diff-auto.
382
383 Format: 3.0 (native)
384 Supported since dpkg 1.14.17. This format is an extension of the
385 native package format as defined in the 1.0 format. It supports all
386 compression methods and will ignore by default any VCS specific files
387 and directories as well as many temporary files (see default value
388 associated to -I option in the --help output).
389
390 Format: 3.0 (quilt)
391 Supported since dpkg 1.14.17. A source package in this format contains
392 at least an original tarball (.orig.tar.ext where ext can be gz, bz2,
393 lzma and xz) and a debian tarball (.debian.tar.ext). It can also
394 contain additional original tarballs (.orig-component.tar.ext).
395 component can only contain alphanumeric (‘a-zA-Z0-9’) characters and
396 hyphens (‘-’). Optionally each original tarball can be accompanied by
397 a detached upstream signature (.orig.tar.ext.asc and
398 .orig-component.tar.ext.asc), extraction supported since dpkg 1.17.20,
399 building supported since dpkg 1.18.5.
400
401
402 Extracting
403
404 The main original tarball is extracted first, then all additional
405 original tarballs are extracted in subdirectories named after the
406 component part of their filename (any pre-existing directory is
407 replaced). The debian tarball is extracted on top of the source
408 directory after prior removal of any pre-existing debian directory.
409 Note that the debian tarball must contain a debian sub-directory but it
410 can also contain binary files outside of that directory (see
411 --include-binaries option).
412
413 All patches listed in debian/patches/vendor.series or
414 debian/patches/series are then applied, where vendor will be the
415 lowercase name of the current vendor, or debian if there is no vendor
416 defined. If the former file is used and the latter one doesn't exist
417 (or is a symlink), then the latter is replaced with a symlink to the
418 former. This is meant to simplify usage of quilt to manage the set of
419 patches. Vendor-specific series files are intended to make it possible
420 to serialize multiple development branches based on the vendor, in a
421 declarative way, in preference to open-coding this handling in
422 debian/rules. This is particularly useful when the source would need
423 to be patched conditionally because the affected files do not have
424 built-in conditional occlusion support. Note however that while
425 dpkg-source parses correctly series files with explicit options used
426 for patch application (stored on each line after the patch filename and
427 one or more spaces), it does ignore those options and always expect
428 patches that can be applied with the -p1 option of patch. It will thus
429 emit a warning when it encounters such options, and the build is likely
430 to fail.
431
432 Note that lintian(1) will emit unconditional warnings when using vendor
433 series due to a controversial Debian specific ruling, which should not
434 affect any external usage; to silence these, the dpkg lintian profile
435 can be used by passing «--profile dpkg» to lintian(1).
436
437 The timestamp of all patched files is reset to the extraction time of
438 the source package (this avoids timestamp skews leading to problems
439 when autogenerated files are patched).
440
441 Contrary to quilt's default behaviour, patches are expected to apply
442 without any fuzz. When that is not the case, you should refresh such
443 patches with quilt, or dpkg-source will error out while trying to apply
444 them.
445
446 Similarly to quilt's default behaviour, the patches can remove files
447 too.
448
449 The file .pc/applied-patches is created if some patches have been
450 applied during the extraction.
451
452 Building
453
454 All original tarballs found in the current directory are extracted in a
455 temporary directory by following the same logic as for the unpack, the
456 debian directory is copied over in the temporary directory, and all
457 patches except the automatic patch (debian-changes-version or
458 debian-changes, depending on --single-debian-patch) are applied. The
459 temporary directory is compared to the source package directory. When
460 the diff is non-empty, the build fails unless --single-debian-patch or
461 --auto-commit has been used, in which case the diff is stored in the
462 automatic patch. If the automatic patch is created/deleted, it's
463 added/removed from the series file and from the quilt metadata.
464
465 Any change on a binary file is not representable in a diff and will
466 thus lead to a failure unless the maintainer deliberately decided to
467 include that modified binary file in the debian tarball (by listing it
468 in debian/source/include-binaries). The build will also fail if it
469 finds binary files in the debian sub-directory unless they have been
470 whitelisted through debian/source/include-binaries.
471
472 The updated debian directory and the list of modified binaries is then
473 used to generate the debian tarball.
474
475 The automatically generated diff doesn't include changes on VCS
476 specific files as well as many temporary files (see default value
477 associated to -i option in the --help output). In particular, the .pc
478 directory used by quilt is ignored during generation of the automatic
479 patch.
480
481 Note: dpkg-source --before-build (and --build) will ensure that all
482 patches listed in the series file are applied so that a package build
483 always has all patches applied. It does this by finding unapplied
484 patches (they are listed in the series file but not in
485 .pc/applied-patches), and if the first patch in that set can be applied
486 without errors, it will apply them all. The option --no-preparation can
487 be used to disable this behavior.
488
489
490 Recording changes
491
492 --commit [directory] [patch-name] [patch-file]
493 Generates a patch corresponding to the local changes that are
494 not managed by the quilt patch system and integrates it in the
495 patch system under the name patch-name. If the name is missing,
496 it will be asked interactively. If patch-file is given, it is
497 used as the patch corresponding to the local changes to
498 integrate. Once integrated, an editor is launched so that you
499 can edit the meta-information in the patch header.
500
501 Passing patch-file is mainly useful after a build failure that
502 pre-generated this file, and on this ground the given file is
503 removed after integration. Note also that the changes contained
504 in the patch file must already be applied on the tree and that
505 the files modified by the patch must not have supplementary
506 unrecorded changes.
507
508 If the patch generation detects modified binary files, they will
509 be automatically added to debian/source/include-binaries so that
510 they end up in the debian tarball (exactly like dpkg-source
511 --include-binaries --build would do).
512
513 Build options
514
515 --allow-version-of-quilt-db=version
516 Allow dpkg-source to build the source package if the version of
517 the quilt metadata is the one specified, even if dpkg-source
518 doesn't know about it (since dpkg 1.15.5.4). Effectively this
519 says that the given version of the quilt metadata is compatible
520 with the version 2 that dpkg-source currently supports. The
521 version of the quilt metadata is stored in .pc/.version.
522
523 --include-removal
524 Do not ignore removed files and include them in the
525 automatically generated patch.
526
527 --include-timestamp
528 Include timestamp in the automatically generated patch.
529
530 --include-binaries
531 Add all modified binaries in the debian tarball. Also add them
532 to debian/source/include-binaries: they will be added by default
533 in subsequent builds and this option is thus no more needed.
534
535 --no-preparation
536 Do not try to prepare the build tree by applying patches which
537 are apparently unapplied (since dpkg 1.14.18).
538
539 --single-debian-patch
540 Use debian/patches/debian-changes instead of
541 debian/patches/debian-changes-version for the name of the
542 automatic patch generated during build (since dpkg 1.15.5.4).
543 This option is particularly useful when the package is
544 maintained in a VCS and a patch set can't reliably be generated.
545 Instead the current diff with upstream should be stored in a
546 single patch. The option would be put in
547 debian/source/local-options and would be accompanied by a
548 debian/source/local-patch-header file explaining how the Debian
549 changes can be best reviewed, for example in the VCS that is
550 used.
551
552 --create-empty-orig
553 Automatically create the main original tarball as empty if it's
554 missing and if there are supplementary original tarballs (since
555 dpkg 1.15.6). This option is meant to be used when the source
556 package is just a bundle of multiple upstream software and where
557 there's no “main” software.
558
559 --no-unapply-patches, --unapply-patches
560 By default, dpkg-source will automatically unapply the patches
561 in the --after-build hook if it did apply them during
562 --before-build (--unapply-patches since dpkg 1.15.8,
563 --no-unapply-patches since dpkg 1.16.5). Those options allow
564 you to forcefully disable or enable the patch unapplication
565 process. Those options are only allowed in
566 debian/source/local-options so that all generated source
567 packages have the same behavior by default.
568
569 --abort-on-upstream-changes
570 The process fails if an automatic patch has been generated
571 (since dpkg 1.15.8). This option can be used to ensure that all
572 changes were properly recorded in separate quilt patches prior
573 to the source package build. This option is not allowed in
574 debian/source/options but can be used in
575 debian/source/local-options.
576
577 --auto-commit
578 The process doesn't fail if an automatic patch has been
579 generated, instead it's immediately recorded in the quilt
580 series.
581
582
583 Extract options
584
585 --skip-debianization
586 Skips extraction of the debian tarball on top of the upstream
587 sources (since dpkg 1.15.1).
588
589 --skip-patches
590 Do not apply patches at the end of the extraction (since dpkg
591 1.14.18).
592
593 Format: 3.0 (custom)
594 Supported since dpkg 1.14.17. This format is special. It doesn't
595 represent a real source package format but can be used to create source
596 packages with arbitrary files.
597
598 Build options
599
600 All non-option arguments are taken as files to integrate in the
601 generated source package. They must exist and are preferably in the
602 current directory. At least one file must be given.
603
604 --target-format=value
605 Required. Defines the real format of the generated source
606 package. The generated .dsc file will contain this value in its
607 Format field and not “3.0 (custom)”.
608
609 Format: 3.0 (git)
610 Supported since dpkg 1.14.17. This format is experimental.
611
612 A source package in this format consists of a single bundle of a git
613 repository .git to hold the source of a package. There may also be a
614 .gitshallow file listing revisions for a shallow git clone.
615
616 Extracting
617
618 The bundle is cloned as a git repository to the target directory. If
619 there is a gitshallow file, it is installed as .git/shallow inside the
620 cloned git repository.
621
622 Note that by default the new repository will have the same branch
623 checked out that was checked out in the original source. (Typically
624 “master”, but it could be anything.) Any other branches will be
625 available under remotes/origin/.
626
627 Building
628
629 Before going any further, some checks are done to ensure that we don't
630 have any non-ignored uncommitted changes.
631
632 git-bundle(1) is used to generate a bundle of the git repository. By
633 default, all branches and tags in the repository are included in the
634 bundle.
635
636 Build options
637
638 --git-ref=ref
639 Allows specifying a git ref to include in the git bundle. Use
640 disables the default behavior of including all branches and
641 tags. May be specified multiple times. The ref can be the name
642 of a branch or tag to include. It may also be any parameter that
643 can be passed to git-rev-list(1). For example, to include only
644 the master branch, use --git-ref=master. To include all tags and
645 branches, except for the private branch, use --git-ref=--all
646 --git-ref=^private
647
648 --git-depth=number
649 Creates a shallow clone with a history truncated to the
650 specified number of revisions.
651
652 Format: 3.0 (bzr)
653 Supported since dpkg 1.14.17. This format is experimental. It
654 generates a single tarball containing the bzr repository.
655
656 Extracting
657
658 The tarball is unpacked and then bzr is used to checkout the current
659 branch.
660
661 Building
662
663 Before going any further, some checks are done to ensure that we don't
664 have any non-ignored uncommitted changes.
665
666 Then the VCS specific part of the source directory is copied over to a
667 temporary directory. Before this temporary directory is packed in a
668 tarball, various cleanup are done to save space.
669
671 no source format specified in debian/source/format
672 The file debian/source/format should always exist and indicate the
673 desired source format. For backwards compatibility, format “1.0” is
674 assumed when the file doesn't exist but you should not rely on this: at
675 some point in the future dpkg-source will be modified to fail when that
676 file doesn't exist.
677
678 The rationale is that format “1.0” is no longer the recommended format,
679 you should usually pick one of the newer formats (“3.0 (quilt)”, “3.0
680 (native)”) but dpkg-source will not do this automatically for you. If
681 you want to continue using the old format, you should be explicit about
682 it and put “1.0” in debian/source/format.
683
684 the diff modifies the following upstream files
685 When using source format “1.0” it is usually a bad idea to modify
686 upstream files directly as the changes end up hidden and mostly
687 undocumented in the .diff.gz file. Instead you should store your
688 changes as patches in the debian directory and apply them at build-
689 time. To avoid this complexity you can also use the format “3.0
690 (quilt)” that offers this natively.
691
692 cannot represent change to file
693 Changes to upstream sources are usually stored with patch files, but
694 not all changes can be represented with patches: they can only alter
695 the content of plain text files. If you try replacing a file with
696 something of a different type (for example replacing a plain file with
697 a symlink or a directory), you will get this error message.
698
699 newly created empty file file will not be represented in diff
700 Empty files can't be created with patch files. Thus this change is not
701 recorded in the source package and you are warned about it.
702
703 executable mode perms of file will not be represented in diff
704 Patch files do not record permissions of files and thus executable
705 permissions are not stored in the source package. This warning reminds
706 you of that fact.
707
708 special mode perms of file will not be represented in diff
709 Patch files do not record permissions of files and thus modified
710 permissions are not stored in the source package. This warning reminds
711 you of that fact.
712
714 DPKG_COLORS
715 Sets the color mode (since dpkg 1.18.5). The currently accepted
716 values are: auto (default), always and never.
717
718 DPKG_NLS
719 If set, it will be used to decide whether to activate Native
720 Language Support, also known as internationalization (or i18n)
721 support (since dpkg 1.19.0). The accepted values are: 0 and 1
722 (default).
723
724 SOURCE_DATE_EPOCH
725 If set, it will be used as the timestamp (as seconds since the
726 epoch) to clamp the mtime in the tar(5) file entries.
727
728 VISUAL
729 EDITOR Used by the “2.0” and “3.0 (quilt)” source format modules.
730
731 GIT_DIR
732 GIT_INDEX_FILE
733 GIT_OBJECT_DIRECTORY
734 GIT_ALTERNATE_OBJECT_DIRECTORIES
735 GIT_WORK_TREE
736 Used by the “3.0 (git)” source format modules.
737
739 debian/source/format
740 This file contains on a single line the format that should be used to
741 build the source package (possible formats are described above). No
742 leading or trailing spaces are allowed.
743
744 debian/source/include-binaries
745 This file contains a list of binary files (one per line) that should be
746 included in the debian tarball. Leading and trailing spaces are
747 stripped. Lines starting with ‘#’ are comments and are skipped. Empty
748 lines are ignored.
749
750 debian/source/options
751 This file contains a list of long options that should be automatically
752 prepended to the set of command line options of a dpkg-source --build
753 or dpkg-source --print-format call. Options like --compression and
754 --compression-level are well suited for this file.
755
756 Each option should be put on a separate line. Empty lines and lines
757 starting with ‘#’ are ignored. The leading ‘--’ should be stripped and
758 short options are not allowed. Optional spaces are allowed around the
759 ‘=’ symbol and optional quotes are allowed around the value. Here's an
760 example of such a file:
761
762 # let dpkg-source create a debian.tar.bz2 with maximal compression
763 compression = "bzip2"
764 compression-level = 9
765 # use debian/patches/debian-changes as automatic patch
766 single-debian-patch
767 # ignore changes on config.{sub,guess}
768 extend-diff-ignore = "(^|/)(config.sub|config.guess)$"
769
770 Note: format options are not accepted in this file, you should use
771 debian/source/format instead.
772
773 debian/source/local-options
774 Exactly like debian/source/options except that the file is not included
775 in the generated source package. It can be useful to store a preference
776 tied to the maintainer or to the VCS repository where the source
777 package is maintained.
778
779 debian/source/local-patch-header and debian/source/patch-header
780 Free form text that is put on top of the automatic patch generated in
781 formats “2.0” or “3.0 (quilt)”. local-patch-header is not included in
782 the generated source package while patch-header is.
783
784 debian/patches/vendor.series
785 debian/patches/series
786 This file lists all patches that have to be applied (in the given
787 order) on top of the upstream source package. Leading and trailing
788 spaces are stripped. The vendor will be the lowercase name of the
789 current vendor, or debian if there is no vendor defined. If the
790 vendor-specific series file does not exist, the vendor-less series file
791 will be used. Lines starting with ‘#’ are comments and are skipped.
792 Empty lines are ignored. Remaining lines start with a patch filename
793 (relative to the debian/patches/ directory) up to the first space
794 character or the end of line. Optional quilt options can follow up to
795 the end of line or the first ‘#’ preceded by one or more spaces (which
796 marks the start of a comment up to the end of line).
797
799 The point at which field overriding occurs compared to certain standard
800 output field settings is rather confused.
801
803 deb-src-control(5), deb-changelog(5), dsc(5).
804
805
806
8071.19.7 2019-06-03 dpkg-source(1)