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.
14 Then typically the following happens:
15 · uscan reads the first entry in debian/changelog to determine the
17 source package name <spkg> and the last upstream version.
18 · uscan process the watch lines debian/watch from the top to the
20 bottom in a single pass.
21 · uscan downloads a web page from the specified URL in
23 debian/watch.
24 · uscan extracts hrefs pointing to the upstream tarball(s) from
26 the web page using the specified matching-pattern in
27 debian/watch.
28 · uscan downloads the upstream tarball with the highest version
30 newer than the last upstream version.
31 · uscan saves the downloaded tarball to the parent ../ directory:
33 ../<upkg>-<uversion>.tar.gz
34 · uscan invokes mk-origtargz to create the source tarball:
36 ../<spkg>_<oversion>.orig.tar.gz
37 · For a multiple upstream tarball (MUT) package, the
39 secondary upstream tarball will instead be named
40 ../<spkg>_<oversion>.orig-<component>.tar.gz.
41 · Repeat until all lines in debian/watch are processed.
43 · uscan invokes uupdate to create the Debianized source tree:
45 ../<spkg>-<oversion>/*
46 Please note the following.
48 · For simplicity, the compression method used in examples is gzip
50 with .gz suffix. Other methods such as xz, bzip2, and lzma with
51 corresponding xz, bz2, and lzma suffixes may also be used.
52 · The new version=4 enables handling of multiple upstream tarball
54 (MUT) packages but this is a rare case for Debian packaging. For a
55 single upstream tarball package, there is only one watch line and
56 no ../<spkg>_<oversion>.orig-<component>.tar.gz .
57 · uscan with the --verbose option produces a human readable report of
59 uscan's execution.
60 · uscan with the --debug option produces a human readable report of
62 uscan's execution including internal variable states.
63 · uscan with the --dehs option produces an upstream package status
65 report in XML format for other programs such as the Debian External
66 Health System.
67 · The primary objective of uscan is to help identify if the latest
69 version upstream tarball is used or not; and to download the latest
70 upstream tarball. The ordering of versions is decided by dpkg
71 --compare-versions.
72 · uscan with the --safe option limits the functionality of uscan to
74 its primary objective. Both the repacking of downloaded files and
75 updating of the source tree are skipped to avoid running unsafe
76 scripts. This also changes the default to --no-download and
77 --skip-signature.
78
80 The current version 4 format of debian/watch can be summarized as
81 follows:
82 · Leading spaces and tabs are dropped.
84 · Empty lines are dropped.
86 · A line started by # (hash) is a comment line and dropped.
88 · A single \ (back slash) at the end of a line is dropped and the
90 next line is concatenated after removing leading spaces and tabs.
91 The concatenated line is parsed as a single line. (The existence or
92 non-existence of the space before the tailing single \ is
93 significant.)
94 · The first non-comment line is:
96 version=4
98 This is a required line and the recommended version number.
100 If you use "version=3" instead here, some features may not work as
102 documented here. See "HISTORY AND UPGRADING".
103 · The following non-comment lines (watch lines) specify the rules for
105 the selection of the candidate upstream tarball URLs and are in one
106 of the following three formats:
107 · opts=" ... " http://URL matching-pattern [version [script]]
109 · http://URL matching-pattern [version [script]]
111 · opts=" ... "
113 Here,
115 · opts=" ... " specifies the behavior of uscan. See "WATCH FILE
117 OPTIONS".
118 · http://URL specifies the web page where upstream publishes the
120 link to the latest source archive.
121 · https://URL may also be used, as may
123 · ftp://URL
125 · Some parts of URL may be in the regex match pattern
127 surrounded between ( and ) such as /foo/bar-([\.\d]+)/.
128 (If multiple directories match, the highest version is
129 picked.) Otherwise, the URL is taken as verbatim.
130 · matching-pattern specifies the full string matching pattern for
132 hrefs in the web page. See "WATCH FILE EXAMPLES".
133 · All matching parts in ( and ) are concatenated with .
135 (period) to form the upstream version.
136 · If the hrefs do not contain directories, you can combine
138 this with the previous entry. I.e., http://URL/matching-
139 pattern .
140 · version restricts the upstream tarball which may be downloaded.
142 The newest available version is chosen in each case.
143 · debian (default) requires the downloading upstream tarball
145 to be newer than the version obtained from
146 debian/changelog.
147 · version-number such as 12.5 requires the upstream tarball
149 to be newer than the version-number.
150 · same requires the downloaded version of the secondary
152 tarballs to be exactly the same as the one for the first
153 upstream tarball downloaded. (Useful only for MUT)
154 · previous restricts the version of the signature file. (Used
156 with pgpmode=previous)
157 · ignore does not restrict the version of the secondary
159 tarballs. (Maybe useful for MUT)
160 · group requires the downloading upstream tarball to be newer
162 than the version obtained from debian/changelog. Package
163 version is the concatenation of all "group" upstream
164 version.
165 · script is executed at the end of uscan execution with
167 appropriate arguments provided by uscan (default: no action).
168 · The typical Debian package is a non-native package made
170 from one upstream tarball. Only a single line of the watch
171 line in one of the first two formats is usually used with
172 its version set to debian and script set to uupdate.
173 · A native package should not specify script.
175 · A multiple upstream tarball (MUT) package should specify
177 uupdate as script in the last watch line and should skip
178 specifying script in the rest of the watch lines.
179 · The last format of the watch line is useful to set the
181 persistent parameters: user-agent, compression. If this format
182 is used, this must be followed by the URL defining watch
183 line(s).
184 · [ and ] in the above format are there to mark the optional
186 parts and should not be typed.
187 There are a few special strings which are substituted by uscan to make
189 it easy to write the watch file.
190 @PACKAGE@
192 This is substituted with the source package name found in the first
193 line of the debian/changelog file.
194 @ANY_VERSION@
196 This is substituted by the legal upstream version regex
197 (capturing).
198 [-_]?(\d[\-+\.:\~\da-zA-Z]*)
200 @ARCHIVE_EXT@
202 This is substituted by the typical archive file extension regex
203 (non-capturing).
204 (?i)\.(?:tar\.xz|tar\.bz2|tar\.gz|zip|tgz|tbz|txz)
206 @SIGNATURE_EXT@
208 This is substituted by the typical signature file extension regex
209 (non-capturing).
210 (?i)\.(?:tar\.xz|tar\.bz2|tar\.gz|zip|tgz|tbz|txz)\.(?:asc|pgp|gpg|sig|sign)
212 @DEB_EXT@
214 This is substituted by the typical Debian extension regexp
215 (capturing).
216 [\+~](debian|dfsg|ds|deb)(\.)?(\d+)?$
218 Some file extensions are not included in the above intentionally to
220 avoid false positives. You can still set such file extension patterns
221 manually.
222
224 uscan reads the watch options specified in opts=" ... " to customize
225 its behavior. Multiple options option1, option2, option3, ... can be
226 set as opts="option1, option2, option3, ... " . The double quotes
227 are necessary if options contain any spaces.
228 Unless otherwise noted as persistent, most options are valid only
230 within their containing watch line.
231 The available watch options are:
233 component=component
235 Set the name of the secondary source tarball as
236 <spkg>_<oversion>.orig-<component>.tar.gz for a MUT package.
237 compression=method
239 Set the compression method when the tarball is repacked
240 (persistent).
241 Available method values are what mk-origtargz supports, so xz, gzip
243 (alias gz), bzip2 (alias bz2), lzma, default. The default method is
244 currently xz. When uscan is launched in a debian source repository
245 which format is "1.0" or undefined, the method switches to gzip.
246 Please note the repacking of the upstream tarballs by mk-origtargz
248 happens only if one of the following conditions is satisfied:
249 · USCAN_REPACK is set in the devscript configuration. See
251 "DEVSCRIPT CONFIGURATION VARIABLES".
252 · --repack is set on the commandline. See <COMMANDLINE OPTIONS>.
254 · repack is set in the watch line as opts="repack,...".
256 · The upstream archive is of zip type including jar, xpi, ...
258 · Files-Excluded or Files-Excluded-component stanzas are set in
260 debian/copyright to make mk-origtargz invoked from uscan remove
261 files from the upstream tarball and repack it. See "COPYRIGHT
262 FILE EXAMPLES" and mk-origtargz(1).
263 repack
265 Force repacking of the upstream tarball using the compression
266 method.
267 repacksuffix=suffix
269 Add suffix to the Debian package upstream version only when the
270 source tarball is repackaged. This rule should be used only for a
271 single upstream tarball package.
272 mode=mode
274 Set the archive download mode.
275 LWP This mode is the default one which downloads the specified
277 tarball from the archive URL on the web. Automatically
278 internal mode value is updated to either http or ftp by URL.
279 git This mode accesses the upstream git archive directly with the
281 git command and packs the source tree with the specified tag
282 via matching-pattern into spkg-version.tar.xz.
283 If the upstream publishes the released tarball via its web
285 interface, please use it instead of using this mode. This mode
286 is the last resort method.
287 For git mode, matching-pattern specifies the full string
289 matching pattern for tags instead of hrefs. If matching-pattern
290 is set to refs/tags/tag-matching-pattern, uscan downloads
291 source from the refs/tags/matched-tag of the git repository.
292 The upstream version is extracted from concatenating the
293 matched parts in ( ... ) with . . See "WATCH FILE EXAMPLES".
294 If matching-pattern is set to HEAD, uscan downloads source from
296 the HEAD of the git repository and the pertinent version is
297 automatically generated with the date and hash of the HEAD of
298 the git repository.
299 If matching-pattern is set to heads/branch, uscan downloads
301 source from the named branch of the git repository.
302 The local repository is temporarily created as a bare git
304 repository directory under the destination directory where the
305 downloaded archive is generated. This is normally erased after
306 the uscan execution. This local repository is kept if --debug
307 option is used.
308 If the current directory is a git repository and the searched
310 repository is listed among the registered "remotes", then uscan
311 will use it instead of cloning separately. The only local
312 change is that uscan will run a "fetch" command to refresh the
313 repository.
314 pretty=rule
316 Set the upstream version string to an arbitrary format as an
317 optional opts argument when the matching-pattern is HEAD or
318 heads/branch for git mode. For the exact syntax, see the get-log
319 manpage under tformat. The default is pretty=0.0~git%cd.%h. No
320 uversionmangle rules is applicable for this case.
321 When pretty=describe is used, the upstream version string is the
323 output of the "git describe --tags | sed s/-/./g" command instead.
324 For example, if the commit is the 5-th after the last tag v2.17.12
325 and its short hash is ged992511, then the string is
326 v2.17.12.5.ged992511 . For this case, it is good idea to add
327 uversionmangle=s/^/0.0~/ or uversionmangle=s/^v// to make the
328 upstream version string compatible with Debian.
329 uversionmangle=s/^v// may work as well. Please note that in order
330 for pretty=describe to function well, upstream need to avoid
331 tagging with random alphabetic tags.
332 The pretty=describe forces to set gitmode=full to make a full local
334 clone of the repository automatically.
335 date=rule
337 Set the date string used by the pretty option to an arbitrary
338 format as an optional opts argument when the matching-pattern is
339 HEAD or heads/branch for git mode. For the exact syntax, see the
340 strftime manpage. The default is date=%Y%m%d.
341 gitmode=mode
343 Set the git clone operation mode. The default is gitmode=shallow.
344 For some dumb git server, you may need to manually set gitmode=full
345 to force full clone operation.
346 If the current directory is a git repository and the searched
348 repository is listed among the registered "remotes", then uscan
349 will use it instead of cloning separately.
350 pgpmode=mode
352 Set the PGP/GPG signature verification mode.
353 auto
355 uscan checks possible URLs for the signature file and
356 autogenerates a pgpsigurlmangle rule to use it.
357 default
359 Use pgpsigurlmangle=rules to generate the candidate upstream
360 signature file URL string from the upstream tarball URL.
361 (default)
362 If the specified pgpsigurlmangle is missing, uscan checks
364 possible URLs for the signature file and suggests adding a
365 pgpsigurlmangle rule.
366 mangle
368 Use pgpsigurlmangle=rules to generate the candidate upstream
369 signature file URL string from the upstream tarball URL.
370 next
372 Verify this downloaded tarball file with the signature file
373 specified in the next watch line. The next watch line must be
374 pgpmode=previous. Otherwise, no verification occurs.
375 previous
377 Verify the downloaded tarball file specified in the previous
378 watch line with this signature file. The previous watch line
379 must be pgpmode=next.
380 self
382 Verify the downloaded file foo.ext with its self signature and
383 extract its content tarball file as foo.
384 gittag
386 Verify tag signature if mode=git.
387 none
389 No signature available. (No warning.)
390 searchmode=mode
392 Set the parsing search mode.
393 html (default): search pattern in "href" parameter of <a> HTML tags
395 plain: search pattern in the full page
396 This is useful is page content is not HTML but in JSON. Example
397 with npmjs.com:
398 version=4
400 opts="searchmode=plain" \
401 https://registry.npmjs.org/aes-js \
402 https://registry.npmjs.org/aes-js/-/aes-js-(\d[\d\.]*)@ARCHIVE_EXT@
403 decompress
405 Decompress compressed archive before the pgp/gpg signature
406 verification.
407 bare
409 Disable all site specific special case code such as URL redirector
410 uses and page content alterations. (persistent)
411 user-agent=user-agent-string
413 Set the user-agent string used to contact the HTTP(S) server as
414 user-agent-string. (persistent)
415 user-agent option should be specified by itself in the watch line
417 without URL, to allow using semicolons and commas in it.
418 pasv, passive
420 Use PASV mode for the FTP connection.
421 If PASV mode is required due to the client side network
423 environment, set uscan to use PASV mode via "COMMANDLINE OPTIONS"
424 or "DEVSCRIPT CONFIGURATION VARIABLES" instead.
425 active, nopasv
427 Don't use PASV mode for the FTP connection.
428 unzipopt=options
430 Add the extra options to use with the unzip command, such as -a,
431 -aa, and -b, when executed by mk-origtargz.
432 dversionmangle=rules
434 Normalize the last upstream version string found in
435 debian/changelog to compare it to the available upstream tarball
436 version. Removal of the Debian specific suffix such as
437 s/@DEB_EXT@// is usually done here.
438 You can also use dversionmangle=auto, this is exactly the same than
440 dversionmangle=s/@DEB_EXT@//
441 dirversionmangle=rules
443 Normalize the directory path string matching the regex in a set of
444 parentheses of http://URL as the sortable version index string.
445 This is used as the directory path sorting index only.
446 Substitution such as s/PRE/~pre/; s/RC/~rc/ may help.
448 pagemangle=rules
450 Normalize the downloaded web page string. (Don't use this unless
451 this is absolutely needed. Generally, g flag is required for these
452 rules.)
453 This is handy if you wish to access Amazon AWS or Subversion
455 repositories in which <a href="..."> is not used.
456 uversionmangle=rules
458 Normalize the candidate upstream version strings extracted from
459 hrefs in the source of the web page. This is used as the version
460 sorting index when selecting the latest upstream version.
461 Substitution such as s/PRE/~pre/; s/RC/~rc/ may help.
463 versionmangle=rules
465 Syntactic shorthand for uversionmangle=rules, dversionmangle=rules
466 hrefdecode=percent-encoding
468 Convert the selected upstream tarball href string from the percent-
469 encoded hexadecimal string to the decoded normal URL string for
470 obfuscated web sites. Only percent-encoding is available and it is
471 decoded with s/%([A-Fa-f\d]{2})/chr hex $1/eg.
472 downloadurlmangle=rules
474 Convert the selected upstream tarball href string into the
475 accessible URL for obfuscated web sites. This is run after
476 hrefdecode.
477 filenamemangle=rules
479 Generate the upstream tarball filename from the selected href
480 string if matching-pattern can extract the latest upstream version
481 <uversion> from the selected href string. Otherwise, generate the
482 upstream tarball filename from its full URL string and set the
483 missing <uversion> from the generated upstream tarball filename.
484 Without this option, the default upstream tarball filename is
486 generated by taking the last component of the URL and removing
487 everything after any '?' or '#'.
488 pgpsigurlmangle=rules
490 Generate the candidate upstream signature file URL string from the
491 upstream tarball URL.
492 oversionmangle=rules
494 Generate the version string <oversion> of the source tarball
495 <spkg>_<oversion>.orig.tar.gz from <uversion>. This should be used
496 to add a suffix such as +dfsg1 to a MUT package.
497 Here, the mangling rules apply the rules to the pertinent string.
499 Multiple rules can be specified in a mangling rule string by making a
500 concatenated string of each mangling rule separated by ; (semicolon).
501 Each mangling rule cannot contain ; (semicolon), , (comma), or "
503 (double quote).
504 Each mangling rule behaves as if a Perl command "$string =~ rule" is
506 executed. There are some notable details.
507 · rule may only use the s, tr, and y operations.
509 s/regex/replacement/options
511 Regex pattern match and replace the target string. Only the g,
512 i and x flags are available. Use the $1 syntax for back
513 references (No \1 syntax). Code execution is not allowed (i.e.
514 no (?{}) or (??{}) constructs).
515 y/source/dest/ or tr/source/dest/
517 Transliterate the characters in the target string.
518
520 uscan reads the first entry in debian/changelog to determine the source
521 package name and the last upstream version.
522 For example, if the first entry of debian/changelog is:
524 · bar (3:2.03+dfsg1-4) unstable; urgency=low
526 then, the source package name is bar and the last Debian package
528 version is 3:2.03+dfsg1-4.
529 The last upstream version is normalized to 2.03+dfsg1 by removing the
531 epoch and the Debian revision.
532 If the dversionmangle rule exists, the last upstream version is further
534 normalized by applying this rule to it. For example, if the last
535 upstream version is 2.03+dfsg1 indicating the source tarball is
536 repackaged, the suffix +dfsg1 is removed by the string substitution
537 s/\+dfsg\d*$// to make the (dversionmangled) last upstream version 2.03
538 and it is compared to the candidate upstream tarball versions such as
539 2.03, 2.04, ... found in the remote site. Thus, set this rule as:
540 · opts="dversionmangle=s/\+dfsg\d*$//"
542 uscan downloads a web page from http://URL specified in debian/watch.
544 · If the directory name part of URL has no parentheses, ( and ), it
546 is taken as verbatim.
547 · If the directory name part of URL has parentheses, ( and ), then
549 uscan recursively searches all possible directories to find a page
550 for the newest version. If the dirversionmangle rule exists, the
551 generated sorting index is used to find the newest version. If a
552 specific version is specified for the download, the matching
553 version string has priority over the newest version.
554 For example, this http://URL may be specified as:
556 · http://www.example.org/([\d\.]+)/
558 Please note the trailing / in the above to make ([\d\.]+) as the
560 directory.
561 If the pagemangle rule exists, the whole downloaded web page as a
563 string is normalized by applying this rule to it. This is very
564 powerful tool and needs to be used with caution. If other mangling
565 rules can be used to address your objective, do not use this rule.
566 The downloaded web page is scanned for hrefs defined in the <a href="
568 ... "> tag to locate the candidate upstream tarball hrefs. These
569 candidate upstream tarball hrefs are matched by the Perl regex pattern
570 matching-pattern such as DL-(?:[\d\.]+?)/foo-(.+)\.tar\.gz to narrow
571 down the candidates. This pattern match needs to be anchored at the
572 beginning and the end. For example, candidate hrefs may be:
573 · DL-2.02/foo-2.02.tar.gz
575 · DL-2.03/foo-2.03.tar.gz
577 · DL-2.04/foo-2.04.tar.gz
579 Here the matching string of (.+) in matching-pattern is considered as
581 the candidate upstream version. If there are multiple matching strings
582 of capturing patterns in matching-pattern, they are all concatenated
583 with . (period) to form the candidate upstream version. Make sure to
584 use the non-capturing regex such as (?:[\d\.]+?) instead for the
585 variable text matching part unrelated to the version.
586 Then, the candidate upstream versions are:
588 · 2.02
590 · 2.03
592 · 2.04
594 The downloaded tarball filename is basically set to the same as the
596 filename in the remote URL of the selected href.
597 If the uversionmangle rule exists, the candidate upstream versions are
599 normalized by applying this rule to them. (This rule may be useful if
600 the upstream version scheme doesn't sort correctly to identify the
601 newest version.)
602 The upstream tarball href corresponding to the newest (uversionmangled)
604 candidate upstream version newer than the (dversionmangled) last
605 upstream version is selected.
606 If multiple upstream tarball hrefs corresponding to a single version
608 with different extensions exist, the highest compression one is chosen.
609 (Priority: tar.xz > tar.lzma > tar.bz2 > tar.gz.)
610 If the selected upstream tarball href is the relative URL, it is
612 converted to the absolute URL using the base URL of the web page. If
613 the <base href=" ... "> tag exists in the web page, the selected
614 upstream tarball href is converted to the absolute URL using the
615 specified base URL in the base tag, instead.
616 If the downloadurlmangle rule exists, the selected upstream tarball
618 href is normalized by applying this rule to it. (This is useful for
619 some sites with the obfuscated download URL.)
620 If the filenamemangle rule exists, the downloaded tarball filename is
622 generated by applying this rule to the selected href if matching-
623 pattern can extract the latest upstream version <uversion> from the
624 selected href string. Otherwise, generate the upstream tarball filename
625 from its full URL string and set the missing <uversion> from the
626 generated upstream tarball filename.
627 Without the filenamemangle rule, the default upstream tarball filename
629 is generated by taking the last component of the URL and removing
630 everything after any '?' or '#'.
631 uscan downloads the selected upstream tarball to the parent ../
633 directory. For example, the downloaded file may be:
634 · ../foo-2.04.tar.gz
636 Let's call this downloaded version 2.04 in the above example
638 generically as <uversion> in the following.
639 If the pgpsigurlmangle rule exists, the upstream signature file URL is
641 generated by applying this rule to the (downloadurlmangled) selected
642 upstream tarball href and the signature file is tried to be downloaded
643 from it.
644 If the pgpsigurlmangle rule doesn't exist, uscan warns user if the
646 matching upstream signature file is available from the same URL with
647 their filename being suffixed by the 5 common suffix asc, gpg, pgp, sig
648 and sign. (You can avoid this warning by setting pgpmode=none.)
649 If the signature file is downloaded, the downloaded upstream tarball is
651 checked for its authenticity against the downloaded signature file
652 using the armored keyring debian/upstream/signing-key.asc (see
653 "KEYRING FILE EXAMPLES"). If its signature is not valid, or not made
654 by one of the listed keys, uscan will report an error.
655 If the oversionmangle rule exists, the source tarball version oversion
657 is generated from the downloaded upstream version uversion by applying
658 this rule. This rule is useful to add suffix such as +dfsg1 to the
659 version of all the source packages of the MUT package for which the
660 repacksuffix mechanism doesn't work.
661 uscan invokes mk-origtargz to create the source tarball properly named
663 for the source package with .orig. (or .orig-<component>. for the
664 secondary tarballs) in its filename.
665 case A: packaging of the upstream tarball as is
667 mk-origtargz creates a symlink ../bar_<oversion>.orig.tar.gz linked
668 to the downloaded local upstream tarball. Here, bar is the source
669 package name found in debian/changelog. The generated symlink may
670 be:
671 · ../bar_2.04.orig.tar.gz -> foo-2.04.tar.gz (as is)
673 Usually, there is no need to set up opts="dversionmangle= ... " for
675 this case.
676 case B: packaging of the upstream tarball after removing non-DFSG files
678 mk-origtargz checks the filename glob of the Files-Excluded stanza
679 in the first section of debian/copyright, removes matching files to
680 create a repacked upstream tarball. Normally, the repacked
681 upstream tarball is renamed with suffix to
682 ../bar_<oversion><suffix>.orig.tar.gz using the repacksuffix option
683 for the single upstream package. Here <oversion> is updated to
684 be <oversion><suffix>.
685 The removal of files is required if files are not DFSG-compliant.
687 For such case, +dfsg1 is used as suffix.
688 So the combined options are set as
690 opts="dversionmangle=s/\+dfsg\d*$// ,repacksuffix=+dfsg1", instead.
691 For example, the repacked upstream tarball may be:
693 · ../bar_2.04+dfsg1.orig.tar.gz (repackaged)
695 uscan normally invokes "uupdate --find --upstream-version oversion "
697 for the version=4 watch file.
698 Please note that --find option is used here since mk-origtargz has been
700 invoked to make *.orig.tar.gz file already. uscan picks bar from
701 debian/changelog.
702 It creates the new upstream source tree under the ../bar-<oversion>
704 directory and Debianize it leveraging the last package contents.
705
707 When writing the watch file, you should rely on the latest upstream
708 source announcement web page. You should not try to second guess the
709 upstream archive structure if possible. Here are the typical
710 debian/watch files.
711 Please note that executing uscan with -v or -vv reveals what exactly
713 happens internally.
714 The existence and non-existence of a space the before tailing \ (back
716 slash) are significant.
717 Some undocumented shorter configuration strings are used in the below
719 EXAMPLES to help you with typing. These are intentional ones. uscan
720 is written to accept such common sense abbreviations but don't push the
721 limit.
722 HTTP site (basic)
724 Here is an example for the basic single upstream tarball.
725 version=4
727 http://example.com/~user/release/foo.html \
728 files/foo-([\d\.]+)\.tar\.gz debian uupdate
729 Or using the special strings:
731 version=4
733 http://example.com/~user/release/@PACKAGE@.html \
734 files/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian uupdate
735 For the upstream source package foo-2.0.tar.gz, this watch file
737 downloads and creates the Debian orig.tar file foo_2.0.orig.tar.gz.
738 HTTP site (pgpsigurlmangle)
740 Here is an example for the basic single upstream tarball with the
741 matching signature file in the same file path.
742 version=4
744 opts="pgpsigurlmangle=s%$%.asc%" http://example.com/release/@PACKAGE@.html \
745 files/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian uupdate
746 For the upstream source package foo-2.0.tar.gz and the upstream
748 signature file foo-2.0.tar.gz.asc, this watch file downloads these
749 files, verifies the authenticity using the keyring
750 debian/upstream/signing-key.asc and creates the Debian orig.tar file
751 foo_2.0.orig.tar.gz.
752 Here is another example for the basic single upstream tarball with the
754 matching signature file on decompressed tarball in the same file path.
755 version=4
757 opts="pgpsigurlmangle=s%@ARCHIVE_EXT@$%.asc%,decompress" \
758 http://example.com/release/@PACKAGE@.html \
759 files/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian uupdate
760 For the upstream source package foo-2.0.tar.gz and the upstream
762 signature file foo-2.0.tar.asc, this watch file downloads these files,
763 verifies the authenticity using the keyring
764 debian/upstream/signing-key.asc and creates the Debian orig.tar file
765 foo_2.0.orig.tar.gz.
766 HTTP site (pgpmode=next/previous)
768 Here is an example for the basic single upstream tarball with the
769 matching signature file in the unrelated file path.
770 version=4
772 opts="pgpmode=next" http://example.com/release/@PACKAGE@.html \
773 files/(?:\d+)/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian
774 opts="pgpmode=previous" http://example.com/release/@PACKAGE@.html \
775 files/(?:\d+)/@PACKAGE@@ANY_VERSION@@SIGNATURE_EXT@ previous uupdate
776 (?:\d+) part can be any random value. The tarball file can have 53,
778 while the signature file can have 33.
779 ([\d\.]+) part for the signature file has a strict requirement to match
781 that for the upstream tarball specified in the previous line by having
782 previous as version in the watch line.
783 HTTP site (flexible)
785 Here is an example for the maximum flexibility of upstream tarball and
786 signature file extensions.
787 version=4
789 opts="pgpmode=next" http://example.com/DL/ \
790 files/(?:\d+)/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian
791 opts="pgpmode=previous" http://example.com/DL/ \
792 files/(?:\d+)/@PACKAGE@@ANY_VERSION@@SIGNATURE_EXT@ \
793 previous uupdate
794 HTTP site (basic MUT)
796 Here is an example for the basic multiple upstream tarballs.
797 version=4
799 opts="pgpsigurlmangle=s%$%.sig%" \
800 http://example.com/release/foo.html \
801 files/foo-([\d\.]+)\.tar\.gz debian
802 opts="pgpsigurlmangle=s%$%.sig%, component=bar" \
803 http://example.com/release/foo.html \
804 files/foobar-([\d\.]+)\.tar\.gz same
805 opts="pgpsigurlmangle=s%$%.sig%, component=baz" \
806 http://example.com/release/foo.html \
807 files/foobaz-([\d\.]+)\.tar\.gz same uupdate
808 For the main upstream source package foo-2.0.tar.gz and the secondary
810 upstream source packages foobar-2.0.tar.gz and foobaz-2.0.tar.gz which
811 install under bar/ and baz/, this watch file downloads and creates the
812 Debian orig.tar file foo_2.0.orig.tar.gz, foo_2.0.orig-bar.tar.gz and
813 foo_2.0.orig-baz.tar.gz. Also, these upstream tarballs are verified by
814 their signature files.
815 HTTP site (recursive directory scanning)
817 Here is an example with the recursive directory scanning for the
818 upstream tarball and its signature files released in a directory named
819 after their version.
820 version=4
822 opts="pgpsigurlmangle=s%$%.sig%, dirversionmangle=s/-PRE/~pre/;s/-RC/~rc/" \
823 http://tmrc.mit.edu/mirror/twisted/Twisted/([\d+\.]+)/ \
824 Twisted-([\d\.]+)\.tar\.xz debian uupdate
825 Here, the web site should be accessible at the following URL:
827 http://tmrc.mit.edu/mirror/twisted/Twisted/
829 Here, dirversionmangle option is used to normalize the sorting order of
831 the directory names.
832 HTTP site (alternative shorthand)
834 For the bare HTTP site where you can directly see archive filenames,
835 the normal watch file:
836 version=4
838 opts="pgpsigurlmangle=s%$%.sig%" \
839 http://www.cpan.org/modules/by-module/Text/ \
840 Text-CSV_XS-(.+)\.tar\.gz \
841 debian uupdate
842 can be rewritten in an alternative shorthand form only with a single
844 string covering URL and filename:
845 version=4
847 opts="pgpsigurlmangle=s%$%.sig%" \
848 http://www.cpan.org/modules/by-module/Text/Text-CSV_XS-(.+)\.tar\.gz \
849 debian uupdate
850 In version=4, initial white spaces are dropped. Thus, this alternative
852 shorthand form can also be written as:
853 version=4
855 opts="pgpsigurlmangle=s%$%.sig%" \
856 http://www.cpan.org/modules/by-module/Text/\
857 Text-CSV_XS-(.+)\.tar\.gz \
858 debian uupdate
859 Please note the subtle difference of a space before the tailing \
861 between the first and the last examples.
862 HTTP site (funny version)
864 For a site which has funny version numbers, the parenthesized groups
865 will be joined with . (period) to make a sanitized version number.
866 version=4
868 http://www.site.com/pub/foobar/foobar_v(\d+)_(\d+)\.tar\.gz \
869 debian uupdate
870 HTTP site (DFSG)
872 The upstream part of the Debian version number can be mangled to
873 indicate the source package was repackaged to clean up non-DFSG files:
874 version=4
876 opts="dversionmangle=s/\+dfsg\d*$//,repacksuffix=+dfsg1" \
877 http://some.site.org/some/path/foobar-(.+)\.tar\.gz debian uupdate
878 See "COPYRIGHT FILE EXAMPLES".
880 HTTP site (filenamemangle)
882 The upstream tarball filename is found by taking the last component of
883 the URL and removing everything after any '?' or '#'.
884 If this does not fit to you, use filenamemangle. For example, <A
886 href="http://foo.bar.org/dl/?path=&dl=foo-0.1.1.tar.gz"> could be
887 handled as:
888 version=4
890 opts=filenamemangle=s/.*=(.*)/$1/ \
891 http://foo.bar.org/dl/\?path=&dl=foo-(.+)\.tar\.gz \
892 debian uupdate
893 <A href="http://foo.bar.org/dl/?path=&dl_version=0.1.1"> could be
895 handled as:
896 version=4
898 opts=filenamemangle=s/.*=(.*)/foo-$1\.tar\.gz/ \
899 http://foo.bar.org/dl/\?path=&dl_version=(.+) \
900 debian uupdate
901 If the href string has no version using <I>matching-pattern>, the
903 version can be obtained from the full URL using filenamemangle.
904 version=4
906 opts=filenamemangle=s&.*/dl/(.*)/foo\.tar\.gz&foo-$1\.tar\.gz& \
907 http://foo.bar.org/dl/([\.\d]+)/ foo.tar.gz \
908 debian uupdate
909 HTTP site (downloadurlmangle)
911 The option downloadurlmangle can be used to mangle the URL of the file
912 to download. This can only be used with http:// URLs. This may be
913 necessary if the link given on the web page needs to be transformed in
914 some way into one which will work automatically, for example:
915 version=4
917 opts=downloadurlmangle=s/prdownload/download/ \
918 http://developer.berlios.de/project/showfiles.php?group_id=2051 \
919 http://prdownload.berlios.de/softdevice/vdr-softdevice-(.+).tgz \
920 debian uupdate
921 HTTP site (oversionmangle, MUT)
923 The option oversionmangle can be used to mangle the version of the
924 source tarball (.orig.tar.gz and .orig-bar.tar.gz). For example,
925 +dfsg1 can be added to the upstream version as:
926 version=4
928 opts=oversionmangle=s/(.*)/$1+dfsg1/ \
929 http://example.com/~user/release/foo.html \
930 files/foo-([\d\.]*).tar.gz debian
931 opts="component=bar" \
932 http://example.com/~user/release/foo.html \
933 files/bar-([\d\.]*).tar.gz same uupdate
934 See "COPYRIGHT FILE EXAMPLES".
936 HTTP site (pagemangle)
938 The option pagemangle can be used to mangle the downloaded web page
939 before applying other rules. The non-standard web page without proper
940 <a href=" << ... >> "> entries can be converted. For example, if
941 foo.html uses <a bogus=" ... ">, this can be converted to the standard
942 page format with:
943 version=4
945 opts=pagemangle="s/<a\s+bogus=/<a href=/g" \
946 http://example.com/release/foo.html \
947 files/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian uupdate
948 Please note the use of g here to replace all occurrences.
950 If foo.html uses <Key> ... </Key>, this can be converted to the
952 standard page format with:
953 version=4
955 opts="pagemangle=s%<Key>([^<]*)</Key>%<Key><a href="$1">$1</a></Key>%g" \
956 http://example.com/release/foo.html \
957 (?:.*)/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian uupdate
958 FTP site (basic):
960 version=4
961 ftp://ftp.tex.ac.uk/tex-archive/web/c_cpp/cweb/cweb-(.+)\.tar\.gz \
962 debian uupdate
963 FTP site (regex special characters):
965 version=4
966 ftp://ftp.worldforge.org/pub/worldforge/libs/\
967 Atlas-C++/transitional/Atlas-C\+\+-(.+)\.tar\.gz debian uupdate
968 Please note that this URL is connected to be ... libs/Atlas-C++/ ...
970 . For ++, the first one in the directory path is verbatim while the one
971 in the filename is escaped by \.
972 FTP site (funny version)
974 This is another way of handling site with funny version numbers, this
975 time using mangling. (Note that multiple groups will be concatenated
976 before mangling is performed, and that mangling will only be performed
977 on the basename version number, not any path version numbers.)
978 version=4
980 opts="uversionmangle=s/^/0.0./" \
981 ftp://ftp.ibiblio.org/pub/Linux/ALPHA/wine/\
982 development/Wine-(.+)\.tar\.gz debian uupdate
983 sf.net
985 For SourceForge based projects, qa.debian.org runs a redirector which
986 allows a simpler form of URL. The format below will automatically be
987 rewritten to use the redirector with the watch file:
988 version=4
990 https://sf.net/<project>/ <tar-name>-(.+)\.tar\.gz debian uupdate
991 For audacity, set the watch file as:
993 version=4
995 https://sf.net/audacity/ audacity-minsrc-(.+)\.tar\.gz debian uupdate
996 Please note, you can still use normal functionalities of uscan to set
998 up a watch file for this site without using the redirector.
999 version=4
1001 opts="uversionmangle=s/-pre/~pre/, \
1002 filenamemangle=s%(?:.*)audacity-minsrc-(.+)\.tar\.xz/download%\
1003 audacity-$1.tar.xz%" \
1004 http://sourceforge.net/projects/audacity/files/audacity/(\d[\d\.]+)/ \
1005 (?:.*)audacity-minsrc-([\d\.]+)\.tar\.xz/download debian uupdate
1006 Here, % is used as the separator instead of the standard /.
1008 github.com
1010 For GitHub based projects, you can use the tags or releases page. The
1011 archive URL uses only the version as the filename. You can rename the
1012 downloaded upstream tarball from into the standard
1013 <project>-<version>.tar.gz using filenamemangle:
1014 version=4
1016 opts="filenamemangle=s%(?:.*?)?v?(\d[\d.]*)\.tar\.gz%<project>-$1.tar.gz%" \
1017 https://github.com/<user>/<project>/tags \
1018 (?:.*?/)?v?(\d[\d.]*)\.tar\.gz debian uupdate
1019 PyPI
1021 For PyPI based projects, pypi.debian.net runs a redirector which allows
1022 a simpler form of URL. The format below will automatically be rewritten
1023 to use the redirector with the watch file:
1024 version=4
1026 https://pypi.python.org/packages/source/<initial>/<project>/ \
1027 <tar-name>-(.+)\.tar\.gz debian uupdate
1028 For cfn-sphere, set the watch file as:
1030 version=4
1032 https://pypi.python.org/packages/source/c/cfn-sphere/ \
1033 cfn-sphere-([\d\.]+).tar.gz debian uupdate
1034 Please note, you can still use normal functionalities of uscan to set
1036 up a watch file for this site without using the redirector.
1037 version=4
1039 opts="pgpmode=none" \
1040 https://pypi.python.org/pypi/cfn-sphere/ \
1041 https://pypi.python.org/packages/.*/.*/.*/\
1042 cfn-sphere-([\d\.]+).tar.gz#.* debian uupdate
1043 code.google.com
1045 Sites which used to be hosted on the Google Code service should have
1046 migrated to elsewhere (github?). Please look for the newer upstream
1047 site if available.
1048 npmjs.org (node modules)
1050 npmjs.org modules are published in JSON files. Here is a way to read
1051 them:
1052 version=4
1054 opts="searchmode=plain" \
1055 https://registry.npmjs.org/aes-js \
1056 https://registry.npmjs.org/aes-js/-/aes-js-(\d[\d\.]*)@ARCHIVE_EXT@
1057 grouped package
1059 Some node modules are split into multiple little upstream package. Here
1060 is a way to group them:
1061 version=4
1063 opts="searchmode=plain,pgpmode=none" \
1064 https://registry.npmjs.org/mongodb \
1065 https://registry.npmjs.org/mongodb/-/mongodb-(\d[\d\.]*)@ARCHIVE_EXT@ group
1066 opts="searchmode=plain,pgpmode=none,component=bson" \
1067 https://registry.npmjs.org/bson \
1068 https://registry.npmjs.org/bson/-/bson-(\d[\d\.]*)@ARCHIVE_EXT@ group
1069 opts="searchmode=plain,pgpmode=none,component=mongodb-core" \
1070 https://registry.npmjs.org/mongodb-core \
1071 https://registry.npmjs.org/mongodb-core/-/mongodb-core-(\d[\d\.]*)@ARCHIVE_EXT@ group
1072 opts="searchmode=plain,pgpmode=none,component=requireoptional" \
1073 https://registry.npmjs.org/require_optional \
1074 https://registry.npmjs.org/require_optional/-/require_optional-(\d[\d\.]*)@ARCHIVE_EXT@ group
1075 Package version is then the concatenation of upstream versions
1077 separated by "+~".
1078 direct access to the git repository (tags)
1080 If the upstream only publishes its code via the git repository and its
1081 code has no web interface to obtain the release tarball, you can use
1082 uscan with the tags of the git repository to track and package the new
1083 upstream release.
1084 version=4
1086 opts="mode=git, gitmode=full, pgpmode=none" \
1087 http://git.ao2.it/tweeper.git \
1088 refs/tags/v([\d\.]+) debian uupdate
1089 Please note "git ls-remote" is used to obtain references for tags.
1091 If a tag v20.5 is the newest tag, the above example downloads
1093 spkg-20.5.tar.xz after making a full clone of the git repository which
1094 is needed for dumb git server.
1095 If tags are signed, set pgpmode=gittag to verify them.
1097 direct access to the git repository (HEAD)
1099 If the upstream only publishes its code via the git repository and its
1100 code has no web interface nor the tags to obtain the released tarball,
1101 you can use uscan with the HEAD of the git repository to track and
1102 package the new upstream release with an automatically generated
1103 version string.
1104 version=4
1106 opts="mode=git, pgpmode=none" \
1107 https://github.com/Debian/dh-make-golang \
1108 HEAD debian uupdate
1109 Please note that a local shallow copy of the git repository is made
1111 with "git clone --bare --depth=1 ..." normally in the target directory.
1112 uscan generates the new upstream version with "git log
1113 --date=format:%Y%m%d --pretty=0.0~git%cd.%h" on this local copy of
1114 repository as its default behavior.
1115 The generation of the upstream version string may the adjusted to your
1117 taste by adding pretty and date options to the opts arguments.
1118
1120 Here is an example for the debian/copyright file which initiates
1121 automatic repackaging of the upstream tarball into
1122 <spkg>_<oversion>.orig.tar.gz (In debian/copyright, the Files-Excluded
1123 and Files-Excluded-component stanzas are a part of the first paragraph
1124 and there is a blank line before the following paragraphs which contain
1125 Files and other stanzas.):
1126 Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
1128 Files-Excluded: exclude-this
1129 exclude-dir
1130 */exclude-dir
1131 .*
1132 */js/jquery.js
1133 Files: *
1135 Copyright: ...
1136 ...
1137 Here is another example for the debian/copyright file which initiates
1139 automatic repackaging of the multiple upstream tarballs into
1140 <spkg>_<oversion>.orig.tar.gz and <spkg>_<oversion>.orig-bar.tar.gz:
1141 Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
1143 Files-Excluded: exclude-this
1144 exclude-dir
1145 */exclude-dir
1146 .*
1147 */js/jquery.js
1148 Files-Excluded-bar: exclude-this
1149 exclude-dir
1150 */exclude-dir
1151 .*
1152 */js/jquery.js
1153 Files: *
1155 Copyright: ...
1156 ...
1157 See mk-origtargz(1).
1159
1161 Let's assume that the upstream "uscan test key (no secret)
1162 <none@debian.org>" signs its package with a secret OpenPGP key and
1163 publishes the corresponding public OpenPGP key. This public OpenPGP
1164 key can be identified in 3 ways using the hexadecimal form.
1165 · The fingerprint as the 20 byte data calculated from the public
1167 OpenPGP key. E. g., 'CF21 8F0E 7EAB F584 B7E2 0402 C77E 2D68 7254
1168 3FAF'
1169 · The long keyid as the last 8 byte data of the fingerprint. E. g.,
1171 'C77E2D6872543FAF'
1172 · The short keyid is the last 4 byte data of the fingerprint. E. g.,
1174 '72543FAF'
1175 Considering the existence of the collision attack on the short keyid,
1177 the use of the long keyid is recommended for receiving keys from the
1178 public key servers. You must verify the downloaded OpenPGP key using
1179 its full fingerprint value which you know is the trusted one.
1180 The armored keyring file debian/upstream/signing-key.asc can be created
1182 by using the gpg (or gpg2) command as follows.
1183 $ gpg --recv-keys "C77E2D6872543FAF"
1185 ...
1186 $ gpg --finger "C77E2D6872543FAF"
1187 pub 4096R/72543FAF 2015-09-02
1188 Key fingerprint = CF21 8F0E 7EAB F584 B7E2 0402 C77E 2D68 7254 3FAF
1189 uid uscan test key (no secret) <none@debian.org>
1190 sub 4096R/52C6ED39 2015-09-02
1191 $ cd path/to/<upkg>-<uversion>
1192 $ mkdir -p debian/upstream
1193 $ gpg --export --export-options export-minimal --armor \
1194 'CF21 8F0E 7EAB F584 B7E2 0402 C77E 2D68 7254 3FAF' \
1195 >debian/upstream/signing-key.asc
1196 The binary keyring files, debian/upstream/signing-key.pgp and
1198 debian/upstream-signing-key.pgp, are still supported but deprecated.
1199 If a group of developers sign the package, you need to list
1201 fingerprints of all of them in the argument for gpg --export ... to
1202 make the keyring to contain all OpenPGP keys of them.
1203 Sometimes you may wonder who made a signature file. You can get the
1205 public keyid used to create the detached signature file
1206 foo-2.0.tar.gz.asc by running gpg as:
1207 $ gpg -vv foo-2.0.tar.gz.asc
1209 gpg: armor: BEGIN PGP SIGNATURE
1210 gpg: armor header: Version: GnuPG v1
1211 :signature packet: algo 1, keyid C77E2D6872543FAF
1212 version 4, created 1445177469, md5len 0, sigclass 0x00
1213 digest algo 2, begin of digest 7a c7
1214 hashed subpkt 2 len 4 (sig created 2015-10-18)
1215 subpkt 16 len 8 (issuer key ID C77E2D6872543FAF)
1216 data: [4091 bits]
1217 gpg: assuming signed data in `foo-2.0.tar.gz'
1218 gpg: Signature made Sun 18 Oct 2015 11:11:09 PM JST using RSA key ID 72543FAF
1219 ...
1220
1222 For the basic usage, uscan does not require to set these options.
1223 --conffile, --conf-file
1225 Add or replace default configuration files ("/etc/devscripts.conf"
1226 and "~/.devscripts"). This can only be used as the first option
1227 given on the command-line.
1228 replace:
1230 uscan --conf-file test.conf --verbose
1231 add:
1233 uscan --conf-file +test.conf --verbose
1234 If one --conf-file has no "+", default configuration files are
1236 ignored.
1237 --no-conf, --noconf
1239 Don't read any configuration files. This can only be used as the
1240 first option given on the command-line.
1241 --no-verbose
1243 Don't report verbose information. (default)
1244 --verbose, -v
1246 Report verbose information.
1247 --debug, -vv
1249 Report verbose information including the downloaded web pages as
1250 processed to STDERR for debugging.
1251 --dehs
1253 Send DEHS style output (XML-type) to STDOUT, while send all other
1254 uscan output to STDERR.
1255 --no-dehs
1257 Use only traditional uscan output format. (default)
1258 --download, -d
1260 Download the new upstream release. (default)
1261 --force-download, -dd
1263 Download the new upstream release even if up-to-date. (may not
1264 overwrite the local file)
1265 --overwrite-download, -ddd
1267 Download the new upstream release even if up-to-date. (may
1268 overwrite the local file)
1269 --no-download, --nodownload
1271 Don't download and report information.
1272 Previously downloaded tarballs may be used.
1274 Change default to --skip-signature.
1276 --signature
1278 Download signature. (default)
1279 --no-signature
1281 Don't download signature but verify if already downloaded.
1282 --skip-signature
1284 Don't bother download signature nor verifying signature.
1285 --safe, --report
1287 Avoid running unsafe scripts by skipping both the repacking of the
1288 downloaded package and the updating of the new source tree.
1289 Change default to --no-download and --skip-signature.
1291 When the objective of running uscan is to gather the upstream
1293 package status under the security conscious environment, please
1294 make sure to use this option.
1295 --report-status
1297 This is equivalent of setting "--verbose --safe".
1298 --download-version version
1300 Specify the version which the upstream release must match in order
1301 to be considered, rather than using the release with the highest
1302 version. (a best effort feature)
1303 --download-debversion version
1305 Specify the Debian package version to download the corresponding
1306 upstream release version. The dversionmangle and uversionmangle
1307 rules are considered. (a best effort feature)
1308 --download-current-version
1310 Download the currently packaged version. (a best effort feature)
1311 --check-dirname-level N
1313 See the below section "Directory name checking" for an explanation
1314 of this option.
1315 --check-dirname-regex regex
1317 See the below section "Directory name checking" for an explanation
1318 of this option.
1319 --destdir path Normally, uscan changes its internal current directory
1321 to the package's source directory where the debian/ is located. Then
1322 the destination directory for the downloaded tarball and other files is
1323 set to the parent directory ../ from this internal current directory.
1324 This default destination directory can be overridden by setting
1325 --destdir option to a particular path. If this path is a relative
1326 path, the destination directory is determined in relative to the
1327 internal current directory of uscan execution. If this path is a
1328 absolute path, the destination directory is set to path
1329 irrespective of the internal current directory of uscan execution.
1330 The above is true not only for the sinple uscan run in the single
1332 source tree but also for the advanced scanning uscan run with
1333 subdirectories holding multiple source trees.
1334 One exception is when --watchfile and --package are used together.
1336 For this case, the internal current directory of uscan execution
1337 and the default destination directory are set to the current
1338 directory . where uscan is started. The default destination
1339 directory can be overridden by setting --destdir option as well.
1340 --package package
1342 Specify the name of the package to check for rather than examining
1343 debian/changelog; this requires the --upstream-version (unless a
1344 version is specified in the watch file) and --watchfile options as
1345 well. Furthermore, no directory scanning will be done and nothing
1346 will be downloaded. This option automatically sets --no-download
1347 and --skip-signature; and probably most useful in conjunction with
1348 the DEHS system (and --dehs).
1349 --upstream-version upstream-version
1351 Specify the current upstream version rather than examine
1352 debian/watch or debian/changelog to determine it. This is ignored
1353 if a directory scan is being performed and more than one
1354 debian/watch file is found.
1355 --watchfile watchfile
1357 Specify the watchfile rather than perform a directory scan to
1358 determine it. If this option is used without --package, then uscan
1359 must be called from within the Debian package source tree (so that
1360 debian/changelog can be found simply by stepping up through the
1361 tree).
1362 One exception is when --watchfile and --package are used together.
1364 uscan can be called from anywhare and the internal current
1365 directory of uscan execution and the default destination directory
1366 are set to the current directory . where uscan is started.
1367 See more in the --destdir explanation.
1369 --bare
1371 Disable all site specific special case codes to perform URL
1372 redirections and page content alterations.
1373 --no-exclusion
1375 Don't automatically exclude files mentioned in debian/copyright
1376 field Files-Excluded.
1377 --pasv
1379 Force PASV mode for FTP connections.
1380 --no-pasv
1382 Don't use PASV mode for FTP connections.
1383 --no-symlink
1385 Don't rename nor repack upstream tarball.
1386 --timeout N
1388 Set timeout to N seconds (default 20 seconds).
1389 --user-agent, --useragent
1391 Override the default user agent header.
1392 --help
1394 Give brief usage information.
1395 --version
1397 Display version information.
1398 uscan also accepts following options and passes them to mk-origtargz:
1400 --symlink
1402 Make orig.tar.gz (with the appropriate extension) symlink to the
1403 downloaded files. (This is the default behavior.)
1404 --copy
1406 Instead of symlinking as described above, copy the downloaded
1407 files.
1408 --rename
1410 Instead of symlinking as described above, rename the downloaded
1411 files.
1412 --repack
1414 After having downloaded an lzma tar, xz tar, bzip tar, gz tar, zip,
1415 jar, xpi archive, repack it to the specified compression (see
1416 --compression).
1417 The unzip package must be installed in order to repack zip and jar
1419 archives, the mozilla-devscripts package must be installed to
1420 repack xpi archives, and the xz-utils package must be installed to
1421 repack lzma or xz tar archives.
1422 --compression [ gzip | bzip2 | lzma | xz ]
1424 In the case where the upstream sources are repacked (either because
1425 --repack option is given or debian/copyright contains the field
1426 Files-Excluded), it is possible to control the compression method
1427 via the parameter. The default is gzip for normal tarballs, and xz
1428 for tarballs generated directly from the git repository.
1429 --copyright-file copyright-file
1431 Exclude files mentioned in Files-Excluded in the given copyright-
1432 file. This is useful when running uscan not within a source
1433 package directory.
1434
1436 For the basic usage, uscan does not require to set these configuration
1437 variables.
1438 The two configuration files /etc/devscripts.conf and ~/.devscripts are
1440 sourced by a shell in that order to set configuration variables. These
1441 may be overridden by command line options. Environment variable
1442 settings are ignored for this purpose. If the first command line option
1443 given is --noconf, then these files will not be read. The currently
1444 recognized variables are:
1445 USCAN_DOWNLOAD
1447 Download or report only:
1448 no: equivalent to --no-download, newer upstream files will not be
1450 downloaded.
1451 yes: equivalent to --download, newer upstream files will be
1452 downloaded. This is the default behavior.
1453 See also --force-download and --overwrite-download.
1454 USCAN_SAFE
1456 If this is set to yes, then uscan avoids running unsafe scripts by
1457 skipping both the repacking of the downloaded package and the
1458 updating of the new source tree; this is equivalent to the --safe
1459 options; this also sets the default to --no-download and
1460 --skip-signature.
1461 USCAN_PASV
1463 If this is set to yes or no, this will force FTP connections to use
1464 PASV mode or not to, respectively. If this is set to default, then
1465 Net::FTP(3) makes the choice (primarily based on the FTP_PASSIVE
1466 environment variable).
1467 USCAN_TIMEOUT
1469 If set to a number N, then set the timeout to N seconds. This is
1470 equivalent to the --timeout option.
1471 USCAN_SYMLINK
1473 If this is set to no, then a pkg_version.orig.tar.{gz|bz2|lzma|xz}
1474 symlink will not be made (equivalent to the --no-symlink option).
1475 If it is set to yes or symlink, then the symlinks will be made. If
1476 it is set to rename, then the files are renamed (equivalent to the
1477 --rename option).
1478 USCAN_DEHS_OUTPUT
1480 If this is set to yes, then DEHS-style output will be used. This is
1481 equivalent to the --dehs option.
1482 USCAN_VERBOSE
1484 If this is set to yes, then verbose output will be given. This is
1485 equivalent to the --verbose option.
1486 USCAN_USER_AGENT
1488 If set, the specified user agent string will be used in place of
1489 the default. This is equivalent to the --user-agent option.
1490 USCAN_DESTDIR
1492 If set, the downloaded files will be placed in this directory.
1493 This is equivalent to the --destdir option.
1494 USCAN_REPACK
1496 If this is set to yes, then after having downloaded a bzip tar,
1497 lzma tar, xz tar, or zip archive, uscan will repack it to the
1498 specified compression (see --compression). This is equivalent to
1499 the --repack option.
1500 USCAN_EXCLUSION
1502 If this is set to no, files mentioned in the field Files-Excluded
1503 of debian/copyright will be ignored and no exclusion of files will
1504 be tried. This is equivalent to the --no-exclusion option.
1505
1507 The exit status gives some indication of whether a newer version was
1508 found or not; one is advised to read the output to determine exactly
1509 what happened and whether there were any warnings to be noted.
1510 0 Either --help or --version was used, or for some watch file which
1512 was examined, a newer upstream version was located.
1513 1 No newer upstream versions were located for any of the watch files
1515 examined.
1516
1518 uscan has many other enhanced features which are skipped in the above
1519 section for the simplicity. Let's check their highlights.
1520 uscan actually scans not just the current directory but all its
1522 subdirectories looking for debian/watch to process them all. See
1523 "Directory name checking".
1524 uscan can be executed with path as its argument to change the starting
1526 directory of search from the current directory to path .
1527 If you are not sure what exactly is happening behind the scene, please
1529 enable the --verbose option. If this is not enough, enable the --debug
1530 option too see all the internal activities.
1531 See "COMMANDLINE OPTIONS" and "DEVSCRIPT CONFIGURATION VARIABLES" for
1533 other variations.
1534 Custom script
1536 The optional script parameter in debian/watch means to execute script
1537 with options after processing this line if specified.
1538 See "HISTORY AND UPGRADING" for how uscan invokes the custom script.
1540 For compatibility with other tools such as git-buildpackage, it may not
1542 be wise to create custom scripts with random behavior. In general,
1543 uupdate is the best choice for the non-native package and custom
1544 scripts, if created, should behave as if uupdate. For possible use
1545 case, see <http://bugs.debian.org/748474> as an example.
1546 URL diversion
1548 Some popular web sites changed their web page structure causing
1549 maintenance problems to the watch file. There are some redirection
1550 services created to ease maintenance of the watch file. Currently,
1551 uscan makes automatic diversion of URL requests to the following URLs
1552 to cope with this situation.
1553 · <http://sf.net>
1555 · <http://pypi.python.org>
1557 Directory name checking
1559 Similarly to several other scripts in the devscripts package, uscan
1560 explores the requested directory trees looking for debian/changelog and
1561 debian/watch files. As a safeguard against stray files causing
1562 potential problems, and in order to promote efficiency, it will examine
1563 the name of the parent directory once it finds the debian/changelog
1564 file, and check that the directory name corresponds to the package
1565 name. It will only attempt to download newer versions of the package
1566 and then perform any requested action if the directory name matches the
1567 package name. Precisely how it does this is controlled by two
1568 configuration file variables DEVSCRIPTS_CHECK_DIRNAME_LEVEL and
1569 DEVSCRIPTS_CHECK_DIRNAME_REGEX, and their corresponding command-line
1570 options --check-dirname-level and --check-dirname-regex.
1571 DEVSCRIPTS_CHECK_DIRNAME_LEVEL can take the following values:
1573 0 Never check the directory name.
1575 1 Only check the directory name if we have had to change directory in
1577 our search for debian/changelog, that is, the directory containing
1578 debian/changelog is not the directory from which uscan was invoked.
1579 This is the default behavior.
1580 2 Always check the directory name.
1582 The directory name is checked by testing whether the current directory
1584 name (as determined by pwd(1)) matches the regex given by the
1585 configuration file option DEVSCRIPTS_CHECK_DIRNAME_REGEX or by the
1586 command line option --check-dirname-regex regex. Here regex is a Perl
1587 regex (see perlre(3perl)), which will be anchored at the beginning and
1588 the end. If regex contains a /, then it must match the full directory
1589 path. If not, then it must match the full directory name. If regex
1590 contains the string package, this will be replaced by the source
1591 package name, as determined from the debian/changelog. The default
1592 value for the regex is: package(-.+)?, thus matching directory names
1593 such as package and package-version.
1594
1596 This section briefly describes the backwards-incompatible watch file
1597 features which have been added in each watch file version, and the
1598 first version of the devscripts package which understood them.
1599 Pre-version 2
1601 The watch file syntax was significantly different in those days.
1602 Don't use it. If you are upgrading from a pre-version 2 watch
1603 file, you are advised to read this manpage and to start from
1604 scratch.
1605 Version 2
1607 devscripts version 2.6.90: The first incarnation of the current
1608 style of watch files.
1609 Version 3
1611 devscripts version 2.8.12: Introduced the following: correct
1612 handling of regex special characters in the path part,
1613 directory/path pattern matching, version number in several parts,
1614 version number mangling. Later versions have also introduced URL
1615 mangling.
1616 If you are upgrading from version 2, the key incompatibility is if
1618 you have multiple groups in the pattern part; whereas only the
1619 first one would be used in version 2, they will all be used in
1620 version 3. To avoid this behavior, change the non-version-number
1621 groups to be (?: ... ) instead of a plain ( ... ) group.
1622 · uscan invokes the custom script as "script --upstream-version
1624 version ../spkg_version.orig.tar.gz".
1625 · uscan invokes the standard uupdate as "uupdate --no-symlink
1627 --upstream-version version ../spkg_version.orig.tar.gz".
1628 Version 4
1630 devscripts version 2.15.10: The first incarnation of watch files
1631 supporting multiple upstream tarballs.
1632 The syntax of the watch file is relaxed to allow more spaces for
1634 readability.
1635 If you have a custom script in place of uupdate, you may also
1637 encounter problems updating from Version 3.
1638 · uscan invokes the custom script as "script --upstream-version
1640 version".
1641 · uscan invokes the standard uupdate as "uupdate --find
1643 --upstream-version version".
1644 Restriction for --dehs is lifted by redirecting other output to
1646 STDERR when it is activated.
1647
1649 dpkg(1), mk-origtargz(1), perlre(1), uupdate(1), devscripts.conf(5)
1650
1652 The original version of uscan was written by Christoph Lameter
1653 <clameter@debian.org>. Significant improvements, changes and bugfixes
1654 were made by Julian Gilbey <jdg@debian.org>. HTTP support was added by
1655 Piotr Roszatycki <dexter@debian.org>. The program was rewritten in Perl
1656 by Julian Gilbey. Xavier Guimard converted it in object-oriented Perl
1657 using Moo.
1658Debian Utilities 2018-12-10 USCAN(1)