1USCAN(1) USCAN(1)
2
6 uscan - scan/watch upstream sources for new releases of software
7
9 uscan [options] [path]
10
12 For basic usage, uscan is executed without any arguments from the root
13 of the Debianized source tree where you see the debian/ directory, or a
14 directory containing multiple source trees.
15 Unless --watchfile is given, uscan looks recursively for valid source
17 trees starting from the current directory (see the below section
18 "Directory name checking" for details).
19 For each valid source tree found, typically the following happens:
21 • uscan reads the first entry in debian/changelog to determine the
23 source package name <spkg> and the last upstream version.
24 • uscan process the watch lines debian/watch from the top to the
26 bottom in a single pass.
27 • uscan downloads a web page from the specified URL in
29 debian/watch.
30 • uscan extracts hrefs pointing to the upstream tarball(s) from
32 the web page using the specified matching-pattern in
33 debian/watch.
34 • uscan downloads the upstream tarball with the highest version
36 newer than the last upstream version.
37 • uscan saves the downloaded tarball to the parent ../ directory:
39 ../<upkg>-<uversion>.tar.gz
40 • uscan invokes mk-origtargz to create the source tarball:
42 ../<spkg>_<oversion>.orig.tar.gz
43 • For a multiple upstream tarball (MUT) package, the
45 secondary upstream tarball will instead be named
46 ../<spkg>_<oversion>.orig-<component>.tar.gz.
47 • Repeat until all lines in debian/watch are processed.
49 • uscan invokes uupdate to create the Debianized source tree:
51 ../<spkg>-<oversion>/*
52 Please note the following.
54 • For simplicity, the compression method used in examples is gzip
56 with .gz suffix. Other methods such as xz, bzip2, and lzma with
57 corresponding xz, bz2 and lzma suffixes may also be used.
58 • The new version=4 enables handling of multiple upstream tarball
60 (MUT) packages but this is a rare case for Debian packaging. For a
61 single upstream tarball package, there is only one watch line and
62 no ../<spkg>_<oversion>.orig-<component>.tar.gz .
63 • uscan with the --verbose option produces a human readable report of
65 uscan's execution.
66 • uscan with the --debug option produces a human readable report of
68 uscan's execution including internal variable states.
69 • uscan with the --extra-debug option produces a human readable
71 report of uscan's execution including internal variable states and
72 remote content during "search" step.
73 • uscan with the --dehs option produces an upstream package status
75 report in XML format for other programs such as the Debian External
76 Health System.
77 • The primary objective of uscan is to help identify if the latest
79 version upstream tarball is used or not; and to download the latest
80 upstream tarball. The ordering of versions is decided by dpkg
81 --compare-versions.
82 • uscan with the --safe option limits the functionality of uscan to
84 its primary objective. Both the repacking of downloaded files and
85 updating of the source tree are skipped to avoid running unsafe
86 scripts. This also changes the default to --no-download and
87 --skip-signature.
88
90 The current version 4 format of debian/watch can be summarized as
91 follows:
92 • Leading spaces and tabs are dropped.
94 • Empty lines are dropped.
96 • A line started by # (hash) is a comment line and dropped.
98 • A single \ (back slash) at the end of a line is dropped and the
100 next line is concatenated after removing leading spaces and tabs.
101 The concatenated line is parsed as a single line. (The existence or
102 non-existence of the space before the tailing single \ is
103 significant.)
104 • The first non-comment line is:
106 version=4
108 This is a required line and the recommended version number.
110 If you use "version=3" instead here, some features may not work as
112 documented here. See "HISTORY AND UPGRADING".
113 • The following non-comment lines (watch lines) specify the rules for
115 the selection of the candidate upstream tarball URLs and are in one
116 of the following three formats:
117 • opts=" ... " http://URL matching-pattern [version [script]]
119 • http://URL matching-pattern [version [script]]
121 • opts=" ... "
123 Here,
125 • opts=" ... " specifies the behavior of uscan. See "WATCH FILE
127 OPTIONS".
128 • http://URL specifies the web page where upstream publishes the
130 link to the latest source archive.
131 • https://URL may also be used, as may
133 • ftp://URL
135 • Some parts of URL may be in the regex match pattern
137 surrounded between ( and ) such as /foo/bar-([\.\d]+)/.
138 (If multiple directories match, the highest version is
139 picked.) Otherwise, the URL is taken as verbatim.
140 • matching-pattern specifies the full string matching pattern for
142 hrefs in the web page. See "WATCH FILE EXAMPLES".
143 • All matching parts in ( and ) are concatenated with .
145 (period) to form the upstream version.
146 • If the hrefs do not contain directories, you can combine
148 this with the previous entry. I.e., http://URL/matching-
149 pattern .
150 • version restricts the upstream tarball which may be downloaded.
152 The newest available version is chosen in each case.
153 • debian (default) requires the downloading upstream tarball
155 to be newer than the version obtained from
156 debian/changelog.
157 • version-number such as 12.5 requires the upstream tarball
159 to be newer than the version-number.
160 • same requires the downloaded version of the secondary
162 tarballs to be exactly the same as the one for the first
163 upstream tarball downloaded. (Useful only for MUT)
164 • previous restricts the version of the signature file. (Used
166 with pgpmode=previous)
167 • ignore does not restrict the version of the secondary
169 tarballs. (Maybe useful for MUT)
170 • group requires the downloading upstream tarball to be newer
172 than the version obtained from debian/changelog. Package
173 version is the concatenation of all "group" upstream
174 version.
175 • checksum requires the downloading upstream tarball to be
177 newer than the version obtained from debian/changelog.
178 Package version is the concatenation of the version of the
179 main tarball, followed by a checksum of all the tarballs
180 using the "checksum" version system. At least the main
181 upstream source has to be declared as "group".
182 • script is executed at the end of uscan execution with
184 appropriate arguments provided by uscan (default: no action).
185 • The typical Debian package is a non-native package made
187 from one upstream tarball. Only a single line of the watch
188 line in one of the first two formats is usually used with
189 its version set to debian and script set to uupdate.
190 • A native package should not specify script.
192 • A multiple upstream tarball (MUT) package should specify
194 uupdate as script in the last watch line and should skip
195 specifying script in the rest of the watch lines.
196 • The last format of the watch line is useful to set the
198 persistent parameters: user-agent, compression. If this format
199 is used, this must be followed by the URL defining watch
200 line(s).
201 • [ and ] in the above format are there to mark the optional
203 parts and should not be typed.
204 There are a few special strings which are substituted by uscan to make
206 it easy to write the watch file.
207 @PACKAGE@
209 This is substituted with the source package name found in the first
210 line of the debian/changelog file.
211 @ANY_VERSION@
213 This is substituted by the legal upstream version regex
214 (capturing).
215 [-_]?(\d[\-+\.:\~\da-zA-Z]*)
217 @ARCHIVE_EXT@
219 This is substituted by the typical archive file extension regex
220 (non-capturing).
221 (?i)(?:\.(?:tar\.xz|tar\.bz2|tar\.gz|tar\.zstd?|zip|tgz|tbz|txz))
223 @SIGNATURE_EXT@
225 This is substituted by the typical signature file extension regex
226 (non-capturing).
227 (?i)(?:\.(?:tar\.xz|tar\.bz2|tar\.gz|tar\.zstd?|zip|tgz|tbz|txz))'(?:\.(?:asc|pgp|gpg|sig|sign))'
229 @DEB_EXT@
231 This is substituted by the typical Debian extension regexp
232 (capturing).
233 [\+~](debian|dfsg|ds|deb)(\.)?(\d+)?$
235 Some file extensions are not included in the above intentionally to
237 avoid false positives. You can still set such file extension patterns
238 manually.
239
241 uscan reads the watch options specified in opts=" ... " to customize
242 its behavior. Multiple options option1, option2, option3, ... can be
243 set as opts="option1, option2, option3, ... " . The double quotes
244 are necessary if options contain any spaces.
245 Unless otherwise noted as persistent, most options are valid only
247 within their containing watch line.
248 The available watch options are:
250 component=component
252 Set the name of the secondary source tarball as
253 <spkg>_<oversion>.orig-<component>.tar.gz for a MUT package.
254 ctype=component-type
256 Set the type of component (only "nodejs" and "perl" are available
257 for now). This will help uscan to find current version if
258 component version is ignored.
259 When using ctype=nodejs, uscan tries to find a version in
261 "package.json", when using ctype=perl, uscan tries to find a
262 version in "META.json". If a version is found, it is used as
263 current version for this component, regardless version found in
264 Debian version string. This permits a better change detection when
265 using ignore or checksum as Debian version.
266 compression=method
268 Set the compression method when the tarball is repacked
269 (persistent).
270 Available method values are what mk-origtargz supports, so xz, gzip
272 (alias gz), bzip2 (alias bz2), lzma, default. The default method is
273 currently xz. When uscan is launched in a debian source repository
274 which format is "1.0" or undefined, the method switches to gzip.
275 Please note the repacking of the upstream tarballs by mk-origtargz
277 happens only if one of the following conditions is satisfied:
278 • USCAN_REPACK is set in the devscript configuration. See
280 "DEVSCRIPT CONFIGURATION VARIABLES".
281 • --repack is set on the commandline. See <COMMANDLINE OPTIONS>.
283 • repack is set in the watch line as opts="repack,...".
285 • The upstream archive is of zip type including jar, xpi, ...
287 • The upstream archive is of zstd (Zstandard) type.
289 • Files-Excluded or Files-Excluded-component stanzas are set in
291 debian/copyright to make mk-origtargz invoked from uscan remove
292 files from the upstream tarball and repack it. See "COPYRIGHT
293 FILE EXAMPLES" and mk-origtargz(1).
294 repack
296 Force repacking of the upstream tarball using the compression
297 method.
298 repacksuffix=suffix
300 Add suffix to the Debian package upstream version only when the
301 source tarball is repackaged. This rule should be used only for a
302 single upstream tarball package.
303 mode=mode
305 Set the archive download mode.
306 LWP This mode is the default one which downloads the specified
308 tarball from the archive URL on the web. Automatically
309 internal mode value is updated to either http or ftp by URL.
310 git This mode accesses the upstream git archive directly with the
312 git command and packs the source tree with the specified tag
313 via matching-pattern into spkg-version.tar.xz.
314 If the upstream publishes the released tarball via its web
316 interface, please use it instead of using this mode. This mode
317 is the last resort method.
318 For git mode, matching-pattern specifies the full string
320 matching pattern for tags instead of hrefs. If matching-pattern
321 is set to refs/tags/tag-matching-pattern, uscan downloads
322 source from the refs/tags/matched-tag of the git repository.
323 The upstream version is extracted from concatenating the
324 matched parts in ( ... ) with . . See "WATCH FILE EXAMPLES".
325 If matching-pattern is set to HEAD, uscan downloads source from
327 the HEAD of the git repository and the pertinent version is
328 automatically generated with the date and hash of the HEAD of
329 the git repository.
330 If matching-pattern is set to refs/heads/branch, uscan
332 downloads source from the named branch of the git repository.
333 The local repository is temporarily created as a bare git
335 repository directory under the destination directory where the
336 downloaded archive is generated. This is normally erased after
337 the uscan execution. This local repository is kept if --debug
338 option is used.
339 If the current directory is a git repository and the searched
341 repository is listed among the registered "remotes", then uscan
342 will use it instead of cloning separately. The only local
343 change is that uscan will run a "fetch" command to refresh the
344 repository.
345 svn This mode accesses the upstream Subversion archive directly
347 with the svn command and packs the source tree.
348 For svn mode, matching-pattern specifies the full string
350 matching pattern for directories under Subversion repository
351 directory, specified via URL. The upstream version is
352 extracted from concatenating the matched parts in ( ... ) with
353 . .
354 If matching-pattern is set to HEAD, uscan downloads the latest
356 source tree of the URL. The upstream version is then
357 constructed by appending the last revision of the URL to
358 0.0~svn.
359 As commit signing is not possible with Subversion, the default
361 pgpmode is set to none when mode=svn. Settings of pgpmode other
362 than default and none are reported as errors.
363 pretty=rule
365 Set the upstream version string to an arbitrary format as an
366 optional opts argument when the matching-pattern is HEAD or
367 heads/branch for git mode. For the exact syntax, see the git-log
368 manpage under tformat. The default is pretty=0.0~git%cd.%h. No
369 uversionmangle rules is applicable for this case.
370 When pretty=describe is used, the upstream version string is the
372 output of the "git describe --tags | sed s/-/./g" command instead.
373 For example, if the commit is the 5-th after the last tag v2.17.12
374 and its short hash is ged992511, then the string is
375 v2.17.12.5.ged992511 . For this case, it is good idea to add
376 uversionmangle=s/^/0.0~/ or uversionmangle=s/^v// to make the
377 upstream version string compatible with Debian.
378 uversionmangle=s/^v// may work as well. Please note that in order
379 for pretty=describe to function well, upstream need to avoid
380 tagging with random alphabetic tags.
381 The pretty=describe forces to set gitmode=full to make a full local
383 clone of the repository automatically.
384 date=rule
386 Set the date string used by the pretty option to an arbitrary
387 format as an optional opts argument when the matching-pattern is
388 HEAD or heads/branch for git mode. For the exact syntax, see the
389 strftime manpage. The default is date=%Y%m%d.
390 gitexport=mode
392 Set the git archive export operation mode. The default is
393 gitexport=default. Set this to gitexport=all to include all files
394 in the .orig.tar archive, ignoring any export-ignore git attributes
395 defined by the upstream.
396 This option is valid only in git mode.
398 gitmode=mode
400 Set the git clone operation mode. The default is gitmode=shallow.
401 For some dumb git server, you may need to manually set gitmode=full
402 to force full clone operation.
403 If the current directory is a git repository and the searched
405 repository is listed among the registered "remotes", then uscan
406 will use it instead of cloning separately.
407 pgpmode=mode
409 Set the PGP/GPG signature verification mode.
410 auto
412 uscan checks possible URLs for the signature file and
413 autogenerates a pgpsigurlmangle rule to use it.
414 default
416 Use pgpsigurlmangle=rules to generate the candidate upstream
417 signature file URL string from the upstream tarball URL.
418 (default)
419 If the specified pgpsigurlmangle is missing, uscan checks
421 possible URLs for the signature file and suggests adding a
422 pgpsigurlmangle rule.
423 mangle
425 Use pgpsigurlmangle=rules to generate the candidate upstream
426 signature file URL string from the upstream tarball URL.
427 next
429 Verify this downloaded tarball file with the signature file
430 specified in the next watch line. The next watch line must be
431 pgpmode=previous. Otherwise, no verification occurs.
432 previous
434 Verify the downloaded tarball file specified in the previous
435 watch line with this signature file. The previous watch line
436 must be pgpmode=next.
437 self
439 Verify the downloaded file foo.ext with its self signature and
440 extract its content tarball file as foo.
441 gittag
443 Verify tag signature if mode=git.
444 none
446 No signature available. (No warning.)
447 searchmode=mode
449 Set the parsing search mode.
450 html (default): search pattern in "href" parameter of <a> HTML tags
452 plain: search pattern in the full page
453 This is useful if page content is not HTML but JSON. Example
454 with npmjs.com:
455 version=4
457 opts="searchmode=plain" \
458 https://registry.npmjs.org/aes-js \
459 https://registry.npmjs.org/aes-js/-/aes-js-(\d[\d\.]*)@ARCHIVE_EXT@
460 decompress
462 Decompress compressed archive before the pgp/gpg signature
463 verification.
464 bare
466 Disable all site specific special case code such as URL redirector
467 uses and page content alterations. (persistent)
468 user-agent=user-agent-string
470 Set the user-agent string used to contact the HTTP(S) server as
471 user-agent-string. (persistent)
472 user-agent option should be specified by itself in the watch line
474 without URL, to allow using semicolons and commas in it.
475 pasv, passive
477 Use PASV mode for the FTP connection.
478 If PASV mode is required due to the client side network
480 environment, set uscan to use PASV mode via "COMMANDLINE OPTIONS"
481 or "DEVSCRIPT CONFIGURATION VARIABLES" instead.
482 active, nopasv
484 Don't use PASV mode for the FTP connection.
485 unzipopt=options
487 Add the extra options to use with the unzip command, such as -a,
488 -aa, and -b, when executed by mk-origtargz.
489 dversionmangle=rules
491 Normalize the last upstream version string found in
492 debian/changelog to compare it to the available upstream tarball
493 version. Removal of the Debian specific suffix such as
494 s/@DEB_EXT@// is usually done here.
495 You can also use dversionmangle=auto, this is exactly the same than
497 dversionmangle=s/@DEB_EXT@//
498 dirversionmangle=rules
500 Normalize the directory path string matching the regex in a set of
501 parentheses of http://URL as the sortable version index string.
502 This is used as the directory path sorting index only.
503 Substitution such as s/PRE/~pre/; s/RC/~rc/ may help.
505 pagemangle=rules
507 Normalize the downloaded web page string. (Don't use this unless
508 this is absolutely needed. Generally, g flag is required for these
509 rules.)
510 This is handy if you wish to access Amazon AWS or Subversion
512 repositories in which <a href="..."> is not used.
513 uversionmangle=rules
515 Normalize the candidate upstream version strings extracted from
516 hrefs in the source of the web page. This is used as the version
517 sorting index when selecting the latest upstream version.
518 Substitution such as s/PRE/~pre/; s/RC/~rc/ may help.
520 versionmangle=rules
522 Syntactic shorthand for uversionmangle=rules, dversionmangle=rules
523 hrefdecode=percent-encoding
525 Convert the selected upstream tarball href string from the percent-
526 encoded hexadecimal string to the decoded normal URL string for
527 obfuscated web sites. Only percent-encoding is available and it is
528 decoded with s/%([A-Fa-f\d]{2})/chr hex $1/eg.
529 downloadurlmangle=rules
531 Convert the selected upstream tarball href string into the
532 accessible URL for obfuscated web sites. This is run after
533 hrefdecode.
534 filenamemangle=rules
536 Generate the upstream tarball filename from the selected href
537 string if matching-pattern can extract the latest upstream version
538 <uversion> from the selected href string. Otherwise, generate the
539 upstream tarball filename from its full URL string and set the
540 missing <uversion> from the generated upstream tarball filename.
541 Without this option, the default upstream tarball filename is
543 generated by taking the last component of the URL and removing
544 everything after any '?' or '#'.
545 pgpsigurlmangle=rules
547 Generate the candidate upstream signature file URL string from the
548 upstream tarball URL.
549 oversionmangle=rules
551 Generate the version string <oversion> of the source tarball
552 <spkg>_<oversion>.orig.tar.gz from <uversion>. This should be used
553 to add a suffix such as +dfsg1 to a MUT package.
554 Here, the mangling rules apply the rules to the pertinent string.
556 Multiple rules can be specified in a mangling rule string by making a
557 concatenated string of each mangling rule separated by ; (semicolon).
558 Each mangling rule cannot contain ; (semicolon), , (comma), or "
560 (double quote).
561 Each mangling rule behaves as if a Perl command "$string =~ rule" is
563 executed. There are some notable details.
564 • rule may only use the s, tr, and y operations.
566 s/regex/replacement/options
568 Regex pattern match and replace the target string. Only the g,
569 i and x flags are available. Use the $1 syntax for back
570 references (No \1 syntax). Code execution is not allowed (i.e.
571 no (?{}) or (??{}) constructs).
572 y/source/dest/ or tr/source/dest/
574 Transliterate the characters in the target string.
575
577 uscan reads the first entry in debian/changelog to determine the source
578 package name and the last upstream version.
579 For example, if the first entry of debian/changelog is:
581 • bar (3:2.03+dfsg1-4) unstable; urgency=low
583 then, the source package name is bar and the last Debian package
585 version is 3:2.03+dfsg1-4.
586 The last upstream version is normalized to 2.03+dfsg1 by removing the
588 epoch and the Debian revision.
589 If the dversionmangle rule exists, the last upstream version is further
591 normalized by applying this rule to it. For example, if the last
592 upstream version is 2.03+dfsg1 indicating the source tarball is
593 repackaged, the suffix +dfsg1 is removed by the string substitution
594 s/\+dfsg\d*$// to make the (dversionmangled) last upstream version 2.03
595 and it is compared to the candidate upstream tarball versions such as
596 2.03, 2.04, ... found in the remote site. Thus, set this rule as:
597 • opts="dversionmangle=s/\+dfsg\d*$//"
599 uscan downloads a web page from http://URL specified in debian/watch.
601 • If the directory name part of URL has no parentheses, ( and ), it
603 is taken as verbatim.
604 • If the directory name part of URL has parentheses, ( and ), then
606 uscan recursively searches all possible directories to find a page
607 for the newest version. If the dirversionmangle rule exists, the
608 generated sorting index is used to find the newest version. If a
609 specific version is specified for the download, the matching
610 version string has priority over the newest version.
611 For example, this http://URL may be specified as:
613 • http://www.example.org/@ANY_VERSION@/
615 Please note the trailing / in the above to make @ANY_VERSION@ as the
617 directory.
618 If the pagemangle rule exists, the whole downloaded web page as a
620 string is normalized by applying this rule to it. This is very
621 powerful tool and needs to be used with caution. If other mangling
622 rules can be used to address your objective, do not use this rule.
623 The downloaded web page is scanned for hrefs defined in the <a href="
625 ... "> tag to locate the candidate upstream tarball hrefs. These
626 candidate upstream tarball hrefs are matched by the Perl regex pattern
627 matching-pattern such as DL-(?:[\d\.]+?)/foo-(.+)\.tar\.gz to narrow
628 down the candidates. This pattern match needs to be anchored at the
629 beginning and the end. For example, candidate hrefs may be:
630 • DL-2.02/foo-2.02.tar.gz
632 • DL-2.03/foo-2.03.tar.gz
634 • DL-2.04/foo-2.04.tar.gz
636 Here the matching string of (.+) in matching-pattern is considered as
638 the candidate upstream version. If there are multiple matching strings
639 of capturing patterns in matching-pattern, they are all concatenated
640 with . (period) to form the candidate upstream version. Make sure to
641 use the non-capturing regex such as (?:[\d\.]+?) instead for the
642 variable text matching part unrelated to the version.
643 Then, the candidate upstream versions are:
645 • 2.02
647 • 2.03
649 • 2.04
651 The downloaded tarball filename is basically set to the same as the
653 filename in the remote URL of the selected href.
654 If the uversionmangle rule exists, the candidate upstream versions are
656 normalized by applying this rule to them. (This rule may be useful if
657 the upstream version scheme doesn't sort correctly to identify the
658 newest version.)
659 The upstream tarball href corresponding to the newest (uversionmangled)
661 candidate upstream version newer than the (dversionmangled) last
662 upstream version is selected.
663 If multiple upstream tarball hrefs corresponding to a single version
665 with different extensions exist, the highest compression one is chosen.
666 (Priority: tar.xz > tar.lzma > tar.bz2 > tar.gz.)
667 If the selected upstream tarball href is the relative URL, it is
669 converted to the absolute URL using the base URL of the web page. If
670 the <base href=" ... "> tag exists in the web page, the selected
671 upstream tarball href is converted to the absolute URL using the
672 specified base URL in the base tag, instead.
673 If the downloadurlmangle rule exists, the selected upstream tarball
675 href is normalized by applying this rule to it. (This is useful for
676 some sites with the obfuscated download URL.)
677 If the filenamemangle rule exists, the downloaded tarball filename is
679 generated by applying this rule to the selected href if matching-
680 pattern can extract the latest upstream version <uversion> from the
681 selected href string. Otherwise, generate the upstream tarball filename
682 from its full URL string and set the missing <uversion> from the
683 generated upstream tarball filename.
684 Without the filenamemangle rule, the default upstream tarball filename
686 is generated by taking the last component of the URL and removing
687 everything after any '?' or '#'.
688 uscan downloads the selected upstream tarball to the parent ../
690 directory. For example, the downloaded file may be:
691 • ../foo-2.04.tar.gz
693 Let's call this downloaded version 2.04 in the above example
695 generically as <uversion> in the following.
696 If the pgpsigurlmangle rule exists, the upstream signature file URL is
698 generated by applying this rule to the (downloadurlmangled) selected
699 upstream tarball href and the signature file is tried to be downloaded
700 from it.
701 If the pgpsigurlmangle rule doesn't exist, uscan warns user if the
703 matching upstream signature file is available from the same URL with
704 their filename being suffixed by the 5 common suffix asc, gpg, pgp, sig
705 and sign. (You can avoid this warning by setting pgpmode=none.)
706 If the signature file is downloaded, the downloaded upstream tarball is
708 checked for its authenticity against the downloaded signature file
709 using the armored keyring debian/upstream/signing-key.asc (see
710 "KEYRING FILE EXAMPLES"). If its signature is not valid, or not made
711 by one of the listed keys, uscan will report an error.
712 If the oversionmangle rule exists, the source tarball version oversion
714 is generated from the downloaded upstream version uversion by applying
715 this rule. This rule is useful to add suffix such as +dfsg1 to the
716 version of all the source packages of the MUT package for which the
717 repacksuffix mechanism doesn't work.
718 uscan invokes mk-origtargz to create the source tarball properly named
720 for the source package with .orig. (or .orig-<component>. for the
721 secondary tarballs) in its filename.
722 case A: packaging of the upstream tarball as is
724 mk-origtargz creates a symlink ../bar_<oversion>.orig.tar.gz linked
725 to the downloaded local upstream tarball. Here, bar is the source
726 package name found in debian/changelog. The generated symlink may
727 be:
728 • ../bar_2.04.orig.tar.gz -> foo-2.04.tar.gz (as is)
730 Usually, there is no need to set up opts="dversionmangle= ... " for
732 this case.
733 case B: packaging of the upstream tarball after removing non-DFSG files
735 mk-origtargz checks the filename glob of the Files-Excluded stanza
736 in the first section of debian/copyright, removes matching files to
737 create a repacked upstream tarball. Normally, the repacked
738 upstream tarball is renamed with suffix to
739 ../bar_<oversion><suffix>.orig.tar.gz using the repacksuffix option
740 for the single upstream package. Here <oversion> is updated to
741 be <oversion><suffix>.
742 The removal of files is required if files are not DFSG-compliant.
744 For such case, +dfsg1 is used as suffix.
745 So the combined options are set as
747 opts="dversionmangle=s/\+dfsg\d*$// ,repacksuffix=+dfsg1", instead.
748 For example, the repacked upstream tarball may be:
750 • ../bar_2.04+dfsg1.orig.tar.gz (repackaged)
752 uscan normally invokes "uupdate --find --upstream-version oversion "
754 for the version=4 watch file.
755 Please note that --find option is used here since mk-origtargz has been
757 invoked to make *.orig.tar.gz file already. uscan picks bar from
758 debian/changelog.
759 It creates the new upstream source tree under the ../bar-<oversion>
761 directory and Debianize it leveraging the last package contents.
762
764 When writing the watch file, you should rely on the latest upstream
765 source announcement web page. You should not try to second guess the
766 upstream archive structure if possible. Here are the typical
767 debian/watch files.
768 Please note that executing uscan with -v or -vv reveals what exactly
770 happens internally.
771 The existence and non-existence of a space the before tailing \ (back
773 slash) are significant.
774 Some undocumented shorter configuration strings are used in the below
776 EXAMPLES to help you with typing. These are intentional ones. uscan
777 is written to accept such common sense abbreviations but don't push the
778 limit.
779 HTTP site (basic)
781 Here is an example for the basic single upstream tarball.
782 version=4
784 http://example.com/~user/release/@PACKAGE@.html \
785 files/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@
786 Or without using the substitution strings (not recommended):
788 http://example.com/~user/release/foo.html \
789 files/foo-([\d\.]+)\.tar\.gz
790 version=4
792 For the upstream source package foo-2.0.tar.gz, this watch file
794 downloads and creates the Debian orig.tar file foo_2.0.orig.tar.gz.
795 HTTP site (pgpsigurlmangle)
797 Here is an example for the basic single upstream tarball with the
798 matching signature file in the same file path.
799 version=4
801 opts="pgpsigurlmangle=s%$%.asc%" http://example.com/release/@PACKAGE@.html \
802 files/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@
803 For the upstream source package foo-2.0.tar.gz and the upstream
805 signature file foo-2.0.tar.gz.asc, this watch file downloads these
806 files, verifies the authenticity using the keyring
807 debian/upstream/signing-key.asc and creates the Debian orig.tar file
808 foo_2.0.orig.tar.gz.
809 Here is another example for the basic single upstream tarball with the
811 matching signature file on decompressed tarball in the same file path.
812 version=4
814 opts="pgpsigurlmangle=s%@ARCHIVE_EXT@$%.asc%,decompress" \
815 http://example.com/release/@PACKAGE@.html \
816 files/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@
817 For the upstream source package foo-2.0.tar.gz and the upstream
819 signature file foo-2.0.tar.asc, this watch file downloads these files,
820 verifies the authenticity using the keyring
821 debian/upstream/signing-key.asc and creates the Debian orig.tar file
822 foo_2.0.orig.tar.gz.
823 HTTP site (pgpmode=next/previous)
825 Here is an example for the basic single upstream tarball with the
826 matching signature file in the unrelated file path.
827 version=4
829 opts="pgpmode=next" http://example.com/release/@PACKAGE@.html \
830 files/(?:\d+)/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian
831 opts="pgpmode=previous" http://example.com/release/@PACKAGE@.html \
832 files/(?:\d+)/@PACKAGE@@ANY_VERSION@@SIGNATURE_EXT@ previous
833 (?:\d+) part can be any random value. The tarball file can have 53,
835 while the signature file can have 33.
836 ([\d\.]+) part for the signature file has a strict requirement to match
838 that for the upstream tarball specified in the previous line by having
839 previous as version in the watch line.
840 HTTP site (flexible)
842 Here is an example for the maximum flexibility of upstream tarball and
843 signature file extensions.
844 version=4
846 opts="pgpmode=next" http://example.com/DL/ \
847 files/(?:\d+)/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian
848 opts="pgpmode=previous" http://example.com/DL/ \
849 files/(?:\d+)/@PACKAGE@@ANY_VERSION@@SIGNATURE_EXT@ \
850 previous
851 HTTP site (basic MUT)
853 Here is an example for the basic multiple upstream tarballs.
854 version=4
856 opts="pgpsigurlmangle=s%$%.sig%" \
857 http://example.com/release/foo.html \
858 files/foo-@ANY_VERSION@@ARCHIVE_EXT@ debian
859 opts="pgpsigurlmangle=s%$%.sig%, component=bar" \
860 http://example.com/release/foo.html \
861 files/foobar-@ANY_VERSION@@ARCHIVE_EXT@ same
862 opts="pgpsigurlmangle=s%$%.sig%, component=baz" \
863 http://example.com/release/foo.html \
864 files/foobaz-@ANY_VERSION@@ARCHIVE_EXT@ same
865 For the main upstream source package foo-2.0.tar.gz and the secondary
867 upstream source packages foobar-2.0.tar.gz and foobaz-2.0.tar.gz which
868 install under bar/ and baz/, this watch file downloads and creates the
869 Debian orig.tar file foo_2.0.orig.tar.gz, foo_2.0.orig-bar.tar.gz and
870 foo_2.0.orig-baz.tar.gz. Also, these upstream tarballs are verified by
871 their signature files.
872 HTTP site (recursive directory scanning)
874 Here is an example with the recursive directory scanning for the
875 upstream tarball and its signature files released in a directory named
876 after their version.
877 version=4
879 opts="pgpsigurlmangle=s%$%.sig%, dirversionmangle=s/-PRE/~pre/;s/-RC/~rc/" \
880 http://tmrc.mit.edu/mirror/twisted/Twisted/@ANY_VERSION@/ \
881 Twisted-@ANY_VERSION@@ARCHIVE_EXT@
882 Here, the web site should be accessible at the following URL:
884 http://tmrc.mit.edu/mirror/twisted/Twisted/
886 Here, dirversionmangle option is used to normalize the sorting order of
888 the directory names.
889 HTTP site (alternative shorthand)
891 For the bare HTTP site where you can directly see archive filenames,
892 the normal watch file:
893 version=4
895 opts="pgpsigurlmangle=s%$%.sig%" \
896 http://www.cpan.org/modules/by-module/Text/ \
897 Text-CSV_XS-@ANY_VERSION@@ARCHIVE_EXT@
898 can be rewritten in an alternative shorthand form only with a single
900 string covering URL and filename:
901 version=4
903 opts="pgpsigurlmangle=s%$%.sig%" \
904 http://www.cpan.org/modules/by-module/Text/Text-CSV_XS-@ANY_VERSION@@ARCHIVE_EXT@
905 In version=4, initial white spaces are dropped. Thus, this alternative
907 shorthand form can also be written as:
908 version=4
910 opts="pgpsigurlmangle=s%$%.sig%" \
911 http://www.cpan.org/modules/by-module/Text/\
912 Text-CSV_XS-@ANY_VERSION@@ARCHIVE_EXT@
913 Please note the subtle difference of a space before the tailing \
915 between the first and the last examples.
916 HTTP site (funny version)
918 For a site which has funny version numbers, the parenthesized groups
919 will be joined with . (period) to make a sanitized version number.
920 version=4
922 http://www.site.com/pub/foobar/foobar_v(\d+)_(\d+)@ARCHIVE_EXT@
923 HTTP site (DFSG)
925 The upstream part of the Debian version number can be mangled to
926 indicate the source package was repackaged to clean up non-DFSG files:
927 version=4
929 opts="dversionmangle=s/\+dfsg\d*$//,repacksuffix=+dfsg1" \
930 http://some.site.org/some/path/foobar-@ANY_VERSION@@ARCHIVE_EXT@
931 See "COPYRIGHT FILE EXAMPLES".
933 HTTP site (filenamemangle)
935 The upstream tarball filename is found by taking the last component of
936 the URL and removing everything after any '?' or '#'.
937 If this does not fit to you, use filenamemangle. For example, <A
939 href="http://foo.bar.org/dl/?path=&dl=foo-0.1.1.tar.gz"> could be
940 handled as:
941 version=4
943 opts=filenamemangle=s/.*=(.*)/$1/ \
944 http://foo.bar.org/dl/\?path=&dl=foo-@ANY_VERSION@@ARCHIVE_EXT@
945 <A href="http://foo.bar.org/dl/?path=&dl_version=0.1.1"> could be
947 handled as:
948 version=4
950 opts=filenamemangle=s/.*=(.*)/foo-$1\.tar\.gz/ \
951 http://foo.bar.org/dl/\?path=&dl_version=@ANY_VERSION@
952 If the href string has no version using <I>matching-pattern>, the
954 version can be obtained from the full URL using filenamemangle.
955 version=4
957 opts=filenamemangle=s&.*/dl/(.*)/foo\.tar\.gz&foo-$1\.tar\.gz& \
958 http://foo.bar.org/dl/@ANY_VERSION@/ foo.tar.gz
959 HTTP site (downloadurlmangle)
961 The option downloadurlmangle can be used to mangle the URL of the file
962 to download. This can only be used with http:// URLs. This may be
963 necessary if the link given on the web page needs to be transformed in
964 some way into one which will work automatically, for example:
965 version=4
967 opts=downloadurlmangle=s/prdownload/download/ \
968 http://developer.berlios.de/project/showfiles.php?group_id=2051 \
969 http://prdownload.berlios.de/softdevice/vdr-softdevice-@ANY_VERSION@@ARCHIVE_EXT@
970 HTTP site (oversionmangle, MUT)
972 The option oversionmangle can be used to mangle the version of the
973 source tarball (.orig.tar.gz and .orig-bar.tar.gz). For example,
974 +dfsg1 can be added to the upstream version as:
975 version=4
977 opts=oversionmangle=s/(.*)/$1+dfsg1/ \
978 http://example.com/~user/release/foo.html \
979 files/foo-@ANY_VERSION@@ARCHIVE_EXT@ debian
980 opts="component=bar" \
981 http://example.com/~user/release/foo.html \
982 files/bar-@ANY_VERSION@@ARCHIVE_EXT@ same
983 See "COPYRIGHT FILE EXAMPLES".
985 HTTP site (pagemangle)
987 The option pagemangle can be used to mangle the downloaded web page
988 before applying other rules. The non-standard web page without proper
989 <a href=" << ... >> "> entries can be converted. For example, if
990 foo.html uses <a bogus=" ... ">, this can be converted to the standard
991 page format with:
992 version=4
994 opts=pagemangle="s/<a\s+bogus=/<a href=/g" \
995 http://example.com/release/foo.html \
996 files/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@
997 Please note the use of g here to replace all occurrences.
999 If foo.html uses <Key> ... </Key>, this can be converted to the
1001 standard page format with:
1002 version=4
1004 opts="pagemangle=s%<Key>([^<]*)</Key>%<Key><a href="$1">$1</a></Key>%g" \
1005 http://example.com/release/foo.html \
1006 (?:.*)/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@
1007 FTP site (basic):
1009 version=4
1010 ftp://ftp.tex.ac.uk/tex-archive/web/c_cpp/cweb/cweb-@ANY_VERSION@@ARCHIVE_EXT@
1011 FTP site (regex special characters):
1013 version=4
1014 ftp://ftp.worldforge.org/pub/worldforge/libs/\
1015 Atlas-C++/transitional/Atlas-C\+\+-@ANY_VERSION@@ARCHIVE_EXT@
1016 Please note that this URL is connected to be ... libs/Atlas-C++/ ...
1018 . For ++, the first one in the directory path is verbatim while the one
1019 in the filename is escaped by \.
1020 FTP site (funny version)
1022 This is another way of handling site with funny version numbers, this
1023 time using mangling. (Note that multiple groups will be concatenated
1024 before mangling is performed, and that mangling will only be performed
1025 on the basename version number, not any path version numbers.)
1026 version=4
1028 opts="uversionmangle=s/^/0.0./" \
1029 ftp://ftp.ibiblio.org/pub/Linux/ALPHA/wine/\
1030 development/Wine-@ANY_VERSION@@ARCHIVE_EXT@
1031 sf.net
1033 For SourceForge based projects, qa.debian.org runs a redirector which
1034 allows a simpler form of URL. The format below will automatically be
1035 rewritten to use the redirector with the watch file:
1036 version=4
1038 https://sf.net/<project>/ <tar-name>-@ANY_VERSION@@ARCHIVE_EXT@
1039 For audacity, set the watch file as:
1041 version=4
1043 https://sf.net/audacity/ audacity-minsrc-@ANY_VERSION@@ARCHIVE_EXT@
1044 Please note, you can still use normal functionalities of uscan to set
1046 up a watch file for this site without using the redirector.
1047 version=4
1049 opts="uversionmangle=s/-pre/~pre/, \
1050 filenamemangle=s%(?:.*)audacity-minsrc-(.+)\.tar\.xz/download%\
1051 audacity-$1.tar.xz%" \
1052 http://sourceforge.net/projects/audacity/files/audacity/@ANY_VERSION@/ \
1053 (?:.*)audacity-minsrc-@ANY_VERSION@@ARCHIVE_EXT@/download
1054 Here, % is used as the separator instead of the standard /.
1056 github.com
1058 For GitHub based projects, you can use the tags or releases page. The
1059 archive URL uses only the version as the filename. You can rename the
1060 downloaded upstream tarball from into the standard
1061 <project>-<version>.tar.gz using filenamemangle:
1062 version=4
1064 opts="filenamemangle=s%(?:.*?)?v?(\d[\d.]*@ARCHIVE_EXT@)%@PACKAGE@-$1%" \
1065 https://github.com/<user>/<project>/tags \
1066 (?:.*?/)?v?@ANY_VERSION@@ARCHIVE_EXT@
1067 PyPI
1069 For PyPI based projects, pypi.debian.net runs a redirector which allows
1070 a simpler form of URL. The format below will automatically be rewritten
1071 to use the redirector with the watch file:
1072 version=4
1074 https://pypi.python.org/packages/source/<initial>/<project>/ \
1075 <tar-name>-@@ANY_VERSION@@ARCHIVE_EXT@
1076 For cfn-sphere, set the watch file as:
1078 version=4
1080 https://pypi.python.org/packages/source/c/cfn-sphere/ \
1081 cfn-sphere-@ANY_VERSION@@ARCHIVE_EXT@
1082 Please note, you can still use normal functionalities of uscan to set
1084 up a watch file for this site without using the redirector.
1085 version=4
1087 opts="pgpmode=none" \
1088 https://pypi.python.org/pypi/cfn-sphere/ \
1089 https://pypi.python.org/packages/.*/.*/.*/\
1090 cfn-sphere-@ANY_VERSION@@ARCHIVE_EXT@#.*
1091 code.google.com
1093 Sites which used to be hosted on the Google Code service should have
1094 migrated to elsewhere (github?). Please look for the newer upstream
1095 site if available.
1096 npmjs.org (node modules)
1098 npmjs.org modules are published in JSON files. Here is a way to read
1099 them:
1100 version=4
1102 opts="searchmode=plain" \
1103 https://registry.npmjs.org/aes-js \
1104 https://registry.npmjs.org/aes-js/-/aes-js-@ANY_VERSION@@ARCHIVE_EXT@
1105 grouped package
1107 Some node modules are split into multiple little upstream package. Here
1108 is a way to group them:
1109 version=4
1111 opts="searchmode=plain,pgpmode=none" \
1112 https://registry.npmjs.org/mongodb \
1113 https://registry.npmjs.org/mongodb/-/mongodb-@ANY_VERSION@@ARCHIVE_EXT@ group
1114 opts="searchmode=plain,pgpmode=none,component=bson" \
1115 https://registry.npmjs.org/bson \
1116 https://registry.npmjs.org/bson/-/bson-@ANY_VERSION@@ARCHIVE_EXT@ group
1117 opts="searchmode=plain,pgpmode=none,component=mongodb-core" \
1118 https://registry.npmjs.org/mongodb-core \
1119 https://registry.npmjs.org/mongodb-core/-/mongodb-core-@ANY_VERSION@@ARCHIVE_EXT@ group
1120 opts="searchmode=plain,pgpmode=none,component=requireoptional" \
1121 https://registry.npmjs.org/require_optional \
1122 https://registry.npmjs.org/require_optional/-/require_optional-@ANY_VERSION@@ARCHIVE_EXT@ group
1123 Package version is then the concatenation of upstream versions
1125 separated by "+~".
1126 To avoid having a too long version, the "checksum" method can be used.
1128 In this case, the main source has to be declared as "group":
1129 version=4
1131 opts="searchmode=plain,pgpmode=none" \
1132 https://registry.npmjs.org/mongodb \
1133 https://registry.npmjs.org/mongodb/-/mongodb-@ANY_VERSION@@ARCHIVE_EXT@ group
1134 opts="searchmode=plain,pgpmode=none,component=bson" \
1135 https://registry.npmjs.org/bson \
1136 https://registry.npmjs.org/bson/-/bson-@ANY_VERSION@@ARCHIVE_EXT@ checksum
1137 opts="searchmode=plain,pgpmode=none,component=mongodb-core" \
1138 https://registry.npmjs.org/mongodb-core \
1139 https://registry.npmjs.org/mongodb-core/-/mongodb-core-@ANY_VERSION@@ARCHIVE_EXT@ checksum
1140 opts="searchmode=plain,pgpmode=none,component=requireoptional" \
1141 https://registry.npmjs.org/require_optional \
1142 https://registry.npmjs.org/require_optional/-/require_optional-@ANY_VERSION@@ARCHIVE_EXT@ checksum
1143 The "checksum" is made up of the separate sum of each number composing
1145 the component versions. Following is an example with 3 components
1146 whose versions are "1.2.4", "2.0.1" and "10.0", with the main tarball
1147 having version "2.0.6":
1148 Main: 2.0.6
1150 Comp1: 1 . 2 . 4
1151 Comp2: 2 . 0 . 1
1152 Comp3: 10 . 0
1153 ================================
1154 Result : 1+2+10 . 2+0+0 . 4+1
1155 Checksum: 13 . 2 . 5
1156 ================================
1157 Final Version: 2.0.6+~cs13.2.5
1158 uscan will also display the original version string before being
1160 encoded into the checksum, which can for example be used in a
1161 debian/changelog entry to easily follow the changes:
1162 2.0.6+~1.2.4+~2.0.1+~10.0
1164 Note: This feature currently accepts only versions composed of digits
1166 and full stops (`.`).
1167 direct access to the git repository (tags)
1169 If the upstream only publishes its code via the git repository and its
1170 code has no web interface to obtain the release tarball, you can use
1171 uscan with the tags of the git repository to track and package the new
1172 upstream release.
1173 version=4
1175 opts="mode=git, gitmode=full, pgpmode=none" \
1176 http://git.ao2.it/tweeper.git \
1177 refs/tags/v@ANY_VERSION@
1178 Please note "git ls-remote" is used to obtain references for tags.
1180 If a tag v20.5 is the newest tag, the above example downloads
1182 spkg-20.5.tar.xz after making a full clone of the git repository which
1183 is needed for dumb git server.
1184 If tags are signed, set pgpmode=gittag to verify them.
1186 direct access to the git repository (HEAD)
1188 If the upstream only publishes its code via the git repository and its
1189 code has no web interface nor the tags to obtain the released tarball,
1190 you can use uscan with the HEAD of the git repository to track and
1191 package the new upstream release with an automatically generated
1192 version string.
1193 version=4
1195 opts="mode=git, pgpmode=none" \
1196 https://github.com/Debian/dh-make-golang \
1197 HEAD
1198 Please note that a local shallow copy of the git repository is made
1200 with "git clone --bare --depth=1 ..." normally in the target directory.
1201 uscan generates the new upstream version with "git log
1202 --date=format:%Y%m%d --pretty=0.0~git%cd.%h" on this local copy of
1203 repository as its default behavior.
1204 The generation of the upstream version string may the adjusted to your
1206 taste by adding pretty and date options to the opts arguments.
1207 direct access to the Subversion repository (tags)
1209 If the upstream only publishes its code via the Subversion repository
1210 and its code has no web interface to obtain the release tarball, you
1211 can use uscan with the tags of the Subversion repository to track and
1212 package the new upstream release.
1213 version=4
1215 opts="mode=svn, pgpmode=none" \
1216 svn://svn.code.sf.net/p/jmol/code/tags/ \
1217 @ANY_VERSION@\/
1218 direct access to the Subversion repository (HEAD)
1220 If the upstream only publishes its code via the Subversion repository
1221 and its code has no web interface to obtain the release tarball, you
1222 can use uscan to get the most recent source of a subtree in the
1223 repository with an automatically generated version string.
1224 version=4
1226 opts="mode=svn, pgpmode=none" \
1227 svn://svn.code.sf.net/p/jmol/code/trunk/ \
1228 HEAD
1229 By default, uscan generates the new upstream version by appending the
1231 revision number to "0.0~svn". This can later be changed using
1232 uversionmangle.
1233
1235 Here is an example for the debian/copyright file which initiates
1236 automatic repackaging of the upstream tarball into
1237 <spkg>_<oversion>.orig.tar.gz (In debian/copyright, the Files-Excluded
1238 and Files-Excluded-component stanzas are a part of the first paragraph
1239 and there is a blank line before the following paragraphs which contain
1240 Files and other stanzas.):
1241 Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
1243 Files-Excluded: exclude-this
1244 exclude-dir
1245 */exclude-dir
1246 .*
1247 */js/jquery.js
1248 Files: *
1250 Copyright: ...
1251 ...
1252 Here is another example for the debian/copyright file which initiates
1254 automatic repackaging of the multiple upstream tarballs into
1255 <spkg>_<oversion>.orig.tar.gz and <spkg>_<oversion>.orig-bar.tar.gz:
1256 Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
1258 Files-Excluded: exclude-this
1259 exclude-dir
1260 */exclude-dir
1261 .*
1262 */js/jquery.js
1263 Files-Excluded-bar: exclude-this
1264 exclude-dir
1265 */exclude-dir
1266 .*
1267 */js/jquery.js
1268 Files: *
1270 Copyright: ...
1271 ...
1272 See mk-origtargz(1).
1274
1276 Let's assume that the upstream "uscan test key (no secret)
1277 <none@debian.org>" signs its package with a secret OpenPGP key and
1278 publishes the corresponding public OpenPGP key. This public OpenPGP
1279 key can be identified in 3 ways using the hexadecimal form.
1280 • The fingerprint as the 20 byte data calculated from the public
1282 OpenPGP key. E. g., 'CF21 8F0E 7EAB F584 B7E2 0402 C77E 2D68 7254
1283 3FAF'
1284 • The long keyid as the last 8 byte data of the fingerprint. E. g.,
1286 'C77E2D6872543FAF'
1287 • The short keyid is the last 4 byte data of the fingerprint. E. g.,
1289 '72543FAF'
1290 Considering the existence of the collision attack on the short keyid,
1292 the use of the long keyid is recommended for receiving keys from the
1293 public key servers. You must verify the downloaded OpenPGP key using
1294 its full fingerprint value which you know is the trusted one.
1295 The armored keyring file debian/upstream/signing-key.asc can be created
1297 by using the gpg (or gpg2) command as follows.
1298 $ gpg --recv-keys "C77E2D6872543FAF"
1300 ...
1301 $ gpg --finger "C77E2D6872543FAF"
1302 pub 4096R/72543FAF 2015-09-02
1303 Key fingerprint = CF21 8F0E 7EAB F584 B7E2 0402 C77E 2D68 7254 3FAF
1304 uid uscan test key (no secret) <none@debian.org>
1305 sub 4096R/52C6ED39 2015-09-02
1306 $ cd path/to/<upkg>-<uversion>
1307 $ mkdir -p debian/upstream
1308 $ gpg --export --export-options export-minimal --armor \
1309 'CF21 8F0E 7EAB F584 B7E2 0402 C77E 2D68 7254 3FAF' \
1310 >debian/upstream/signing-key.asc
1311 The binary keyring files, debian/upstream/signing-key.pgp and
1313 debian/upstream-signing-key.pgp, are still supported but deprecated.
1314 If a group of developers sign the package, you need to list
1316 fingerprints of all of them in the argument for gpg --export ... to
1317 make the keyring to contain all OpenPGP keys of them.
1318 Sometimes you may wonder who made a signature file. You can get the
1320 public keyid used to create the detached signature file
1321 foo-2.0.tar.gz.asc by running gpg as:
1322 $ gpg -vv foo-2.0.tar.gz.asc
1324 gpg: armor: BEGIN PGP SIGNATURE
1325 gpg: armor header: Version: GnuPG v1
1326 :signature packet: algo 1, keyid C77E2D6872543FAF
1327 version 4, created 1445177469, md5len 0, sigclass 0x00
1328 digest algo 2, begin of digest 7a c7
1329 hashed subpkt 2 len 4 (sig created 2015-10-18)
1330 subpkt 16 len 8 (issuer key ID C77E2D6872543FAF)
1331 data: [4091 bits]
1332 gpg: assuming signed data in `foo-2.0.tar.gz'
1333 gpg: Signature made Sun 18 Oct 2015 11:11:09 PM JST using RSA key ID 72543FAF
1334 ...
1335
1337 For the basic usage, uscan does not require to set these options.
1338 --conffile, --conf-file
1340 Add or replace default configuration files ("/etc/devscripts.conf"
1341 and "~/.devscripts"). This can only be used as the first option
1342 given on the command-line.
1343 replace:
1345 uscan --conf-file test.conf --verbose
1346 add:
1348 uscan --conf-file +test.conf --verbose
1349 If one --conf-file has no "+", default configuration files are
1351 ignored.
1352 --no-conf, --noconf
1354 Don't read any configuration files. This can only be used as the
1355 first option given on the command-line.
1356 --no-verbose
1358 Don't report verbose information. (default)
1359 --verbose, -v
1361 Report verbose information.
1362 --debug, -vv
1364 Report verbose information and some internal state values.
1365 --extra-debug, -vvv
1367 Report verbose information including the downloaded web pages as
1368 processed to STDERR for debugging.
1369 --dehs
1371 Send DEHS style output (XML-type) to STDOUT, while send all other
1372 uscan output to STDERR.
1373 --no-dehs
1375 Use only traditional uscan output format. (default)
1376 --download, -d
1378 Download the new upstream release. (default)
1379 --force-download, -dd
1381 Download the new upstream release even if up-to-date. (may not
1382 overwrite the local file)
1383 --overwrite-download, -ddd
1385 Download the new upstream release even if up-to-date. (may
1386 overwrite the local file)
1387 --no-download, --nodownload
1389 Don't download and report information.
1390 Previously downloaded tarballs may be used.
1392 Change default to --skip-signature.
1394 --signature
1396 Download signature. (default)
1397 --no-signature
1399 Don't download signature but verify if already downloaded.
1400 --skip-signature
1402 Don't bother download signature nor verifying signature.
1403 --safe, --report
1405 Avoid running unsafe scripts by skipping both the repacking of the
1406 downloaded package and the updating of the new source tree.
1407 Change default to --no-download and --skip-signature.
1409 When the objective of running uscan is to gather the upstream
1411 package status under the security conscious environment, please
1412 make sure to use this option.
1413 --report-status
1415 This is equivalent of setting "--verbose --safe".
1416 --download-version version
1418 Specify the version which the upstream release must match in order
1419 to be considered, rather than using the release with the highest
1420 version. (a best effort feature)
1421 --download-debversion version
1423 Specify the Debian package version to download the corresponding
1424 upstream release version. The dversionmangle and uversionmangle
1425 rules are considered. (a best effort feature)
1426 --download-current-version
1428 Download the currently packaged version. (a best effort feature)
1429 --check-dirname-level N
1431 See the below section "Directory name checking" for an explanation
1432 of this option.
1433 --check-dirname-regex regex
1435 See the below section "Directory name checking" for an explanation
1436 of this option.
1437 --destdir path Normally, uscan changes its internal current directory
1439 to the package's source directory where the debian/ is located. Then
1440 the destination directory for the downloaded tarball and other files is
1441 set to the parent directory ../ from this internal current directory.
1442 This default destination directory can be overridden by setting
1443 --destdir option to a particular path. If this path is a relative
1444 path, the destination directory is determined in relative to the
1445 internal current directory of uscan execution. If this path is a
1446 absolute path, the destination directory is set to path
1447 irrespective of the internal current directory of uscan execution.
1448 The above is true not only for the simple uscan run in the single
1450 source tree but also for the advanced scanning uscan run with
1451 subdirectories holding multiple source trees.
1452 One exception is when --watchfile and --package are used together.
1454 For this case, the internal current directory of uscan execution
1455 and the default destination directory are set to the current
1456 directory . where uscan is started. The default destination
1457 directory can be overridden by setting --destdir option as well.
1458 --package package
1460 Specify the name of the package to check for rather than examining
1461 debian/changelog; this requires the --upstream-version (unless a
1462 version is specified in the watch file) and --watchfile options as
1463 well. Furthermore, no directory scanning will be done and nothing
1464 will be downloaded. This option automatically sets --no-download
1465 and --skip-signature; and probably most useful in conjunction with
1466 the DEHS system (and --dehs).
1467 --upstream-version upstream-version
1469 Specify the current upstream version rather than examine
1470 debian/watch or debian/changelog to determine it. This is ignored
1471 if a directory scan is being performed and more than one
1472 debian/watch file is found.
1473 --watchfile watchfile
1475 Specify the watchfile rather than perform a directory scan to
1476 determine it. If this option is used without --package, then uscan
1477 must be called from within the Debian package source tree (so that
1478 debian/changelog can be found simply by stepping up through the
1479 tree).
1480 One exception is when --watchfile and --package are used together.
1482 uscan can be called from anywhare and the internal current
1483 directory of uscan execution and the default destination directory
1484 are set to the current directory . where uscan is started.
1485 See more in the --destdir explanation.
1487 --bare
1489 Disable all site specific special case codes to perform URL
1490 redirections and page content alterations.
1491 --http-header
1493 Add specified header in HTTP requests for matching url. This option
1494 can be used more than one time, values must be in the form
1495 "baseUrl@Name=value. Example:
1496 uscan --http-header https://example.org@My-Token=qwertyuiop
1498 Security:
1500 The given baseUrl must exactly match the base url before '/'.
1502 Examples:
1503 | --http-header value | Good for | Never used |
1504 +------------------------------------+-----------------------------+------------+
1505 | https://example.org.com@Hdr=Value | https://example.org.com/... | |
1506 | https://example.org.com/@Hdr=Value | | X |
1507 | https://e.com:1879@Hdr=Value | https://e.com:1879/... | |
1508 | https://e.com:1879/dir@Hdr=Value | https://e.com:1879/dir/... | |
1509 | https://e.com:1879/dir/@Hdr=Value | | X |
1510 It is strongly recommended to not use this feature to pass a secret
1512 token over unciphered connection (http://)
1513 You can use "USCAN_HTTP_HEADER" variable (in "~/.devscripts") to
1514 hide secret token from scripts
1515 --no-exclusion
1516 Don't automatically exclude files mentioned in debian/copyright
1517 field Files-Excluded.
1518 --pasv
1520 Force PASV mode for FTP connections.
1521 --no-pasv
1523 Don't use PASV mode for FTP connections.
1524 --no-symlink
1526 Don't rename nor repack upstream tarball.
1527 --timeout N
1529 Set timeout to N seconds (default 20 seconds).
1530 --user-agent, --useragent
1532 Override the default user agent header.
1533 --help
1535 Give brief usage information.
1536 --version
1538 Display version information.
1539 uscan also accepts following options and passes them to mk-origtargz:
1541 --symlink
1543 Make orig.tar.gz (with the appropriate extension) symlink to the
1544 downloaded files. (This is the default behavior.)
1545 --copy
1547 Instead of symlinking as described above, copy the downloaded
1548 files.
1549 --rename
1551 Instead of symlinking as described above, rename the downloaded
1552 files.
1553 --repack
1555 After having downloaded an lzma tar, xz tar, bzip tar, gz tar, zip,
1556 jar, xpi, zstd archive, repack it to the specified compression (see
1557 --compression).
1558 The unzip package must be installed in order to repack zip and jar
1560 archives, the mozilla-devscripts package must be installed to
1561 repack xpi archives, the xz-utils package must be installed to
1562 repack lzma or xz tar archives, and zstd must be installed to
1563 repack zstd archives.
1564 --compression [ gzip | bzip2 | lzma | xz ]
1566 In the case where the upstream sources are repacked (either because
1567 --repack option is given or debian/copyright contains the field
1568 Files-Excluded), it is possible to control the compression method
1569 via the parameter. The default is gzip for normal tarballs, and xz
1570 for tarballs generated directly from the git repository.
1571 --copyright-file copyright-file
1573 Exclude files mentioned in Files-Excluded in the given copyright-
1574 file. This is useful when running uscan not within a source
1575 package directory.
1576
1578 For the basic usage, uscan does not require to set these configuration
1579 variables.
1580 The two configuration files /etc/devscripts.conf and ~/.devscripts are
1582 sourced by a shell in that order to set configuration variables. These
1583 may be overridden by command line options. Environment variable
1584 settings are ignored for this purpose. If the first command line option
1585 given is --noconf, then these files will not be read. The currently
1586 recognized variables are:
1587 USCAN_DOWNLOAD
1589 Download or report only:
1590 no: equivalent to --no-download, newer upstream files will not be
1592 downloaded.
1593 yes: equivalent to --download, newer upstream files will be
1594 downloaded. This is the default behavior.
1595 See also --force-download and --overwrite-download.
1596 USCAN_SAFE
1598 If this is set to yes, then uscan avoids running unsafe scripts by
1599 skipping both the repacking of the downloaded package and the
1600 updating of the new source tree; this is equivalent to the --safe
1601 options; this also sets the default to --no-download and
1602 --skip-signature.
1603 USCAN_PASV
1605 If this is set to yes or no, this will force FTP connections to use
1606 PASV mode or not to, respectively. If this is set to default, then
1607 Net::FTP(3) makes the choice (primarily based on the FTP_PASSIVE
1608 environment variable).
1609 USCAN_TIMEOUT
1611 If set to a number N, then set the timeout to N seconds. This is
1612 equivalent to the --timeout option.
1613 USCAN_SYMLINK
1615 If this is set to no, then a pkg_version.orig.tar.{gz|bz2|lzma|xz}
1616 symlink will not be made (equivalent to the --no-symlink option).
1617 If it is set to yes or symlink, then the symlinks will be made. If
1618 it is set to rename, then the files are renamed (equivalent to the
1619 --rename option).
1620 USCAN_DEHS_OUTPUT
1622 If this is set to yes, then DEHS-style output will be used. This is
1623 equivalent to the --dehs option.
1624 USCAN_VERBOSE
1626 If this is set to yes, then verbose output will be given. This is
1627 equivalent to the --verbose option.
1628 USCAN_USER_AGENT
1630 If set, the specified user agent string will be used in place of
1631 the default. This is equivalent to the --user-agent option.
1632 USCAN_DESTDIR
1634 If set, the downloaded files will be placed in this directory.
1635 This is equivalent to the --destdir option.
1636 USCAN_REPACK
1638 If this is set to yes, then after having downloaded a bzip tar,
1639 lzma tar, xz tar, zip or zstd archive, uscan will repack it to the
1640 specified compression (see --compression). This is equivalent to
1641 the --repack option.
1642 USCAN_EXCLUSION
1644 If this is set to no, files mentioned in the field Files-Excluded
1645 of debian/copyright will be ignored and no exclusion of files will
1646 be tried. This is equivalent to the --no-exclusion option.
1647 USCAN_HTTP_HEADER
1649 If set, the specified http header will be used if URL match. This
1650 is equivalent to --http-header option.
1651
1653 The exit status gives some indication of whether a newer version was
1654 found or not; one is advised to read the output to determine exactly
1655 what happened and whether there were any warnings to be noted.
1656 0 Either --help or --version was used, or for some watch file which
1658 was examined, a newer upstream version was located.
1659 1 No newer upstream versions were located for any of the watch files
1661 examined.
1662
1664 uscan has many other enhanced features which are skipped in the above
1665 section for the simplicity. Let's check their highlights.
1666 uscan can be executed with path as its argument to change the starting
1668 directory of search from the current directory to path .
1669 If you are not sure what exactly is happening behind the scene, please
1671 enable the --verbose option. If this is not enough, enable the --debug
1672 option too see all the internal activities.
1673 See "COMMANDLINE OPTIONS" and "DEVSCRIPT CONFIGURATION VARIABLES" for
1675 other variations.
1676 Custom script
1678 The optional script parameter in debian/watch means to execute script
1679 with options after processing this line if specified.
1680 See "HISTORY AND UPGRADING" for how uscan invokes the custom script.
1682 For compatibility with other tools such as git-buildpackage, it may not
1684 be wise to create custom scripts with random behavior. In general,
1685 uupdate is the best choice for the non-native package and custom
1686 scripts, if created, should behave as if uupdate. For possible use
1687 case, see <http://bugs.debian.org/748474> as an example.
1688 URL diversion
1690 Some popular web sites changed their web page structure causing
1691 maintenance problems to the watch file. There are some redirection
1692 services created to ease maintenance of the watch file. Currently,
1693 uscan makes automatic diversion of URL requests to the following URLs
1694 to cope with this situation.
1695 • <http://sf.net>
1697 • <http://pypi.python.org>
1699 Directory name checking
1701 Similarly to several other scripts in the devscripts package, uscan
1702 explores the requested directory trees looking for debian/changelog and
1703 debian/watch files. As a safeguard against stray files causing
1704 potential problems, and in order to promote efficiency, it will examine
1705 the name of the parent directory once it finds the debian/changelog
1706 file, and check that the directory name corresponds to the package
1707 name. It will only attempt to download newer versions of the package
1708 and then perform any requested action if the directory name matches the
1709 package name. Precisely how it does this is controlled by two
1710 configuration file variables DEVSCRIPTS_CHECK_DIRNAME_LEVEL and
1711 DEVSCRIPTS_CHECK_DIRNAME_REGEX, and their corresponding command-line
1712 options --check-dirname-level and --check-dirname-regex.
1713 DEVSCRIPTS_CHECK_DIRNAME_LEVEL can take the following values:
1715 0 Never check the directory name.
1717 1 Only check the directory name if we have had to change directory in
1719 our search for debian/changelog, that is, the directory containing
1720 debian/changelog is not the directory from which uscan was invoked.
1721 This is the default behavior.
1722 2 Always check the directory name.
1724 The directory name is checked by testing whether the current directory
1726 name (as determined by pwd(1)) matches the regex given by the
1727 configuration file option DEVSCRIPTS_CHECK_DIRNAME_REGEX or by the
1728 command line option --check-dirname-regex regex. Here regex is a Perl
1729 regex (see perlre(3perl)), which will be anchored at the beginning and
1730 the end. If regex contains a /, then it must match the full directory
1731 path. If not, then it must match the full directory name. If regex
1732 contains the string package, this will be replaced by the source
1733 package name, as determined from the debian/changelog. The default
1734 value for the regex is: package(-.+)?, thus matching directory names
1735 such as package and package-version.
1736
1738 This section briefly describes the backwards-incompatible watch file
1739 features which have been added in each watch file version, and the
1740 first version of the devscripts package which understood them.
1741 Pre-version 2
1743 The watch file syntax was significantly different in those days.
1744 Don't use it. If you are upgrading from a pre-version 2 watch
1745 file, you are advised to read this manpage and to start from
1746 scratch.
1747 Version 2
1749 devscripts version 2.6.90: The first incarnation of the current
1750 style of watch files. This version is also deprecated and will be
1751 rejected after the Debian 11 release.
1752 Version 3
1754 devscripts version 2.8.12: Introduced the following: correct
1755 handling of regex special characters in the path part,
1756 directory/path pattern matching, version number in several parts,
1757 version number mangling. Later versions have also introduced URL
1758 mangling.
1759 If you are upgrading from version 2, the key incompatibility is if
1761 you have multiple groups in the pattern part; whereas only the
1762 first one would be used in version 2, they will all be used in
1763 version 3. To avoid this behavior, change the non-version-number
1764 groups to be (?: ... ) instead of a plain ( ... ) group.
1765 • uscan invokes the custom script as "script --upstream-version
1767 version ../spkg_version.orig.tar.gz".
1768 • uscan invokes the standard uupdate as "uupdate --no-symlink
1770 --upstream-version version ../spkg_version.orig.tar.gz".
1771 Version 4
1773 devscripts version 2.15.10: The first incarnation of watch files
1774 supporting multiple upstream tarballs.
1775 The syntax of the watch file is relaxed to allow more spaces for
1777 readability.
1778 If you have a custom script in place of uupdate, you may also
1780 encounter problems updating from Version 3.
1781 • uscan invokes the custom script as "script --upstream-version
1783 version".
1784 • uscan invokes the standard uupdate as "uupdate --find
1786 --upstream-version version".
1787 Restriction for --dehs is lifted by redirecting other output to
1789 STDERR when it is activated.
1790
1792 dpkg(1), mk-origtargz(1), perlre(1), uupdate(1), devscripts.conf(5)
1793
1795 The original version of uscan was written by Christoph Lameter
1796 <clameter@debian.org>. Significant improvements, changes and bugfixes
1797 were made by Julian Gilbey <jdg@debian.org>. HTTP support was added by
1798 Piotr Roszatycki <dexter@debian.org>. The program was rewritten in Perl
1799 by Julian Gilbey. Xavier Guimard converted it in object-oriented Perl
1800 using Moo.
1801Debian Utilities 2022-01-25 USCAN(1)