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 · checksum requires the downloading upstream tarball to be
167 newer than the version obtained from debian/changelog.
168 Package version is the concatenation of the version of the
169 main tarball, followed by a checksum of all the tarballs
170 using the "checksum" version system. At least the main
171 upstream source has to be declared as "group".
172 · script is executed at the end of uscan execution with
174 appropriate arguments provided by uscan (default: no action).
175 · The typical Debian package is a non-native package made
177 from one upstream tarball. Only a single line of the watch
178 line in one of the first two formats is usually used with
179 its version set to debian and script set to uupdate.
180 · A native package should not specify script.
182 · A multiple upstream tarball (MUT) package should specify
184 uupdate as script in the last watch line and should skip
185 specifying script in the rest of the watch lines.
186 · The last format of the watch line is useful to set the
188 persistent parameters: user-agent, compression. If this format
189 is used, this must be followed by the URL defining watch
190 line(s).
191 · [ and ] in the above format are there to mark the optional
193 parts and should not be typed.
194 There are a few special strings which are substituted by uscan to make
196 it easy to write the watch file.
197 @PACKAGE@
199 This is substituted with the source package name found in the first
200 line of the debian/changelog file.
201 @ANY_VERSION@
203 This is substituted by the legal upstream version regex
204 (capturing).
205 [-_]?(\d[\-+\.:\~\da-zA-Z]*)
207 @ARCHIVE_EXT@
209 This is substituted by the typical archive file extension regex
210 (non-capturing).
211 (?i)\.(?:tar\.xz|tar\.bz2|tar\.gz|zip|tgz|tbz|txz)
213 @SIGNATURE_EXT@
215 This is substituted by the typical signature file extension regex
216 (non-capturing).
217 (?i)\.(?:tar\.xz|tar\.bz2|tar\.gz|zip|tgz|tbz|txz)\.(?:asc|pgp|gpg|sig|sign)
219 @DEB_EXT@
221 This is substituted by the typical Debian extension regexp
222 (capturing).
223 [\+~](debian|dfsg|ds|deb)(\.)?(\d+)?$
225 Some file extensions are not included in the above intentionally to
227 avoid false positives. You can still set such file extension patterns
228 manually.
229
231 uscan reads the watch options specified in opts=" ... " to customize
232 its behavior. Multiple options option1, option2, option3, ... can be
233 set as opts="option1, option2, option3, ... " . The double quotes
234 are necessary if options contain any spaces.
235 Unless otherwise noted as persistent, most options are valid only
237 within their containing watch line.
238 The available watch options are:
240 component=component
242 Set the name of the secondary source tarball as
243 <spkg>_<oversion>.orig-<component>.tar.gz for a MUT package.
244 compression=method
246 Set the compression method when the tarball is repacked
247 (persistent).
248 Available method values are what mk-origtargz supports, so xz, gzip
250 (alias gz), bzip2 (alias bz2), lzma, default. The default method is
251 currently xz. When uscan is launched in a debian source repository
252 which format is "1.0" or undefined, the method switches to gzip.
253 Please note the repacking of the upstream tarballs by mk-origtargz
255 happens only if one of the following conditions is satisfied:
256 · USCAN_REPACK is set in the devscript configuration. See
258 "DEVSCRIPT CONFIGURATION VARIABLES".
259 · --repack is set on the commandline. See <COMMANDLINE OPTIONS>.
261 · repack is set in the watch line as opts="repack,...".
263 · The upstream archive is of zip type including jar, xpi, ...
265 · Files-Excluded or Files-Excluded-component stanzas are set in
267 debian/copyright to make mk-origtargz invoked from uscan remove
268 files from the upstream tarball and repack it. See "COPYRIGHT
269 FILE EXAMPLES" and mk-origtargz(1).
270 repack
272 Force repacking of the upstream tarball using the compression
273 method.
274 repacksuffix=suffix
276 Add suffix to the Debian package upstream version only when the
277 source tarball is repackaged. This rule should be used only for a
278 single upstream tarball package.
279 mode=mode
281 Set the archive download mode.
282 LWP This mode is the default one which downloads the specified
284 tarball from the archive URL on the web. Automatically
285 internal mode value is updated to either http or ftp by URL.
286 git This mode accesses the upstream git archive directly with the
288 git command and packs the source tree with the specified tag
289 via matching-pattern into spkg-version.tar.xz.
290 If the upstream publishes the released tarball via its web
292 interface, please use it instead of using this mode. This mode
293 is the last resort method.
294 For git mode, matching-pattern specifies the full string
296 matching pattern for tags instead of hrefs. If matching-pattern
297 is set to refs/tags/tag-matching-pattern, uscan downloads
298 source from the refs/tags/matched-tag of the git repository.
299 The upstream version is extracted from concatenating the
300 matched parts in ( ... ) with . . See "WATCH FILE EXAMPLES".
301 If matching-pattern is set to HEAD, uscan downloads source from
303 the HEAD of the git repository and the pertinent version is
304 automatically generated with the date and hash of the HEAD of
305 the git repository.
306 If matching-pattern is set to refs/heads/branch, uscan
308 downloads source from the named branch of the git repository.
309 The local repository is temporarily created as a bare git
311 repository directory under the destination directory where the
312 downloaded archive is generated. This is normally erased after
313 the uscan execution. This local repository is kept if --debug
314 option is used.
315 If the current directory is a git repository and the searched
317 repository is listed among the registered "remotes", then uscan
318 will use it instead of cloning separately. The only local
319 change is that uscan will run a "fetch" command to refresh the
320 repository.
321 svn This mode accesses the upstream Subversion archive directly
323 with the svn command and packs the source tree.
324 For svn mode, matching-pattern specifies the full string
326 matching pattern for directories under Subversion repository
327 directory, specified via URL. The upstream version is
328 extracted from concatenating the matched parts in ( ... ) with
329 . .
330 If matching-pattern is set to HEAD, uscan downloads the latest
332 source tree of the URL. The upstream version is then
333 constructed by appending the last revision of the URL to
334 0.0~svn.
335 As commit signing is not possible with Subversion, the default
337 pgpmode is set to none when mode=svn. Settings of pgpmode other
338 than default and none are reported as errors.
339 pretty=rule
341 Set the upstream version string to an arbitrary format as an
342 optional opts argument when the matching-pattern is HEAD or
343 heads/branch for git mode. For the exact syntax, see the git-log
344 manpage under tformat. The default is pretty=0.0~git%cd.%h. No
345 uversionmangle rules is applicable for this case.
346 When pretty=describe is used, the upstream version string is the
348 output of the "git describe --tags | sed s/-/./g" command instead.
349 For example, if the commit is the 5-th after the last tag v2.17.12
350 and its short hash is ged992511, then the string is
351 v2.17.12.5.ged992511 . For this case, it is good idea to add
352 uversionmangle=s/^/0.0~/ or uversionmangle=s/^v// to make the
353 upstream version string compatible with Debian.
354 uversionmangle=s/^v// may work as well. Please note that in order
355 for pretty=describe to function well, upstream need to avoid
356 tagging with random alphabetic tags.
357 The pretty=describe forces to set gitmode=full to make a full local
359 clone of the repository automatically.
360 date=rule
362 Set the date string used by the pretty option to an arbitrary
363 format as an optional opts argument when the matching-pattern is
364 HEAD or heads/branch for git mode. For the exact syntax, see the
365 strftime manpage. The default is date=%Y%m%d.
366 gitmode=mode
368 Set the git clone operation mode. The default is gitmode=shallow.
369 For some dumb git server, you may need to manually set gitmode=full
370 to force full clone operation.
371 If the current directory is a git repository and the searched
373 repository is listed among the registered "remotes", then uscan
374 will use it instead of cloning separately.
375 pgpmode=mode
377 Set the PGP/GPG signature verification mode.
378 auto
380 uscan checks possible URLs for the signature file and
381 autogenerates a pgpsigurlmangle rule to use it.
382 default
384 Use pgpsigurlmangle=rules to generate the candidate upstream
385 signature file URL string from the upstream tarball URL.
386 (default)
387 If the specified pgpsigurlmangle is missing, uscan checks
389 possible URLs for the signature file and suggests adding a
390 pgpsigurlmangle rule.
391 mangle
393 Use pgpsigurlmangle=rules to generate the candidate upstream
394 signature file URL string from the upstream tarball URL.
395 next
397 Verify this downloaded tarball file with the signature file
398 specified in the next watch line. The next watch line must be
399 pgpmode=previous. Otherwise, no verification occurs.
400 previous
402 Verify the downloaded tarball file specified in the previous
403 watch line with this signature file. The previous watch line
404 must be pgpmode=next.
405 self
407 Verify the downloaded file foo.ext with its self signature and
408 extract its content tarball file as foo.
409 gittag
411 Verify tag signature if mode=git.
412 none
414 No signature available. (No warning.)
415 searchmode=mode
417 Set the parsing search mode.
418 html (default): search pattern in "href" parameter of <a> HTML tags
420 plain: search pattern in the full page
421 This is useful is page content is not HTML but in JSON. Example
422 with npmjs.com:
423 version=4
425 opts="searchmode=plain" \
426 https://registry.npmjs.org/aes-js \
427 https://registry.npmjs.org/aes-js/-/aes-js-(\d[\d\.]*)@ARCHIVE_EXT@
428 decompress
430 Decompress compressed archive before the pgp/gpg signature
431 verification.
432 bare
434 Disable all site specific special case code such as URL redirector
435 uses and page content alterations. (persistent)
436 user-agent=user-agent-string
438 Set the user-agent string used to contact the HTTP(S) server as
439 user-agent-string. (persistent)
440 user-agent option should be specified by itself in the watch line
442 without URL, to allow using semicolons and commas in it.
443 pasv, passive
445 Use PASV mode for the FTP connection.
446 If PASV mode is required due to the client side network
448 environment, set uscan to use PASV mode via "COMMANDLINE OPTIONS"
449 or "DEVSCRIPT CONFIGURATION VARIABLES" instead.
450 active, nopasv
452 Don't use PASV mode for the FTP connection.
453 unzipopt=options
455 Add the extra options to use with the unzip command, such as -a,
456 -aa, and -b, when executed by mk-origtargz.
457 dversionmangle=rules
459 Normalize the last upstream version string found in
460 debian/changelog to compare it to the available upstream tarball
461 version. Removal of the Debian specific suffix such as
462 s/@DEB_EXT@// is usually done here.
463 You can also use dversionmangle=auto, this is exactly the same than
465 dversionmangle=s/@DEB_EXT@//
466 dirversionmangle=rules
468 Normalize the directory path string matching the regex in a set of
469 parentheses of http://URL as the sortable version index string.
470 This is used as the directory path sorting index only.
471 Substitution such as s/PRE/~pre/; s/RC/~rc/ may help.
473 pagemangle=rules
475 Normalize the downloaded web page string. (Don't use this unless
476 this is absolutely needed. Generally, g flag is required for these
477 rules.)
478 This is handy if you wish to access Amazon AWS or Subversion
480 repositories in which <a href="..."> is not used.
481 uversionmangle=rules
483 Normalize the candidate upstream version strings extracted from
484 hrefs in the source of the web page. This is used as the version
485 sorting index when selecting the latest upstream version.
486 Substitution such as s/PRE/~pre/; s/RC/~rc/ may help.
488 versionmangle=rules
490 Syntactic shorthand for uversionmangle=rules, dversionmangle=rules
491 hrefdecode=percent-encoding
493 Convert the selected upstream tarball href string from the percent-
494 encoded hexadecimal string to the decoded normal URL string for
495 obfuscated web sites. Only percent-encoding is available and it is
496 decoded with s/%([A-Fa-f\d]{2})/chr hex $1/eg.
497 downloadurlmangle=rules
499 Convert the selected upstream tarball href string into the
500 accessible URL for obfuscated web sites. This is run after
501 hrefdecode.
502 filenamemangle=rules
504 Generate the upstream tarball filename from the selected href
505 string if matching-pattern can extract the latest upstream version
506 <uversion> from the selected href string. Otherwise, generate the
507 upstream tarball filename from its full URL string and set the
508 missing <uversion> from the generated upstream tarball filename.
509 Without this option, the default upstream tarball filename is
511 generated by taking the last component of the URL and removing
512 everything after any '?' or '#'.
513 pgpsigurlmangle=rules
515 Generate the candidate upstream signature file URL string from the
516 upstream tarball URL.
517 oversionmangle=rules
519 Generate the version string <oversion> of the source tarball
520 <spkg>_<oversion>.orig.tar.gz from <uversion>. This should be used
521 to add a suffix such as +dfsg1 to a MUT package.
522 Here, the mangling rules apply the rules to the pertinent string.
524 Multiple rules can be specified in a mangling rule string by making a
525 concatenated string of each mangling rule separated by ; (semicolon).
526 Each mangling rule cannot contain ; (semicolon), , (comma), or "
528 (double quote).
529 Each mangling rule behaves as if a Perl command "$string =~ rule" is
531 executed. There are some notable details.
532 · rule may only use the s, tr, and y operations.
534 s/regex/replacement/options
536 Regex pattern match and replace the target string. Only the g,
537 i and x flags are available. Use the $1 syntax for back
538 references (No \1 syntax). Code execution is not allowed (i.e.
539 no (?{}) or (??{}) constructs).
540 y/source/dest/ or tr/source/dest/
542 Transliterate the characters in the target string.
543
545 uscan reads the first entry in debian/changelog to determine the source
546 package name and the last upstream version.
547 For example, if the first entry of debian/changelog is:
549 · bar (3:2.03+dfsg1-4) unstable; urgency=low
551 then, the source package name is bar and the last Debian package
553 version is 3:2.03+dfsg1-4.
554 The last upstream version is normalized to 2.03+dfsg1 by removing the
556 epoch and the Debian revision.
557 If the dversionmangle rule exists, the last upstream version is further
559 normalized by applying this rule to it. For example, if the last
560 upstream version is 2.03+dfsg1 indicating the source tarball is
561 repackaged, the suffix +dfsg1 is removed by the string substitution
562 s/\+dfsg\d*$// to make the (dversionmangled) last upstream version 2.03
563 and it is compared to the candidate upstream tarball versions such as
564 2.03, 2.04, ... found in the remote site. Thus, set this rule as:
565 · opts="dversionmangle=s/\+dfsg\d*$//"
567 uscan downloads a web page from http://URL specified in debian/watch.
569 · If the directory name part of URL has no parentheses, ( and ), it
571 is taken as verbatim.
572 · If the directory name part of URL has parentheses, ( and ), then
574 uscan recursively searches all possible directories to find a page
575 for the newest version. If the dirversionmangle rule exists, the
576 generated sorting index is used to find the newest version. If a
577 specific version is specified for the download, the matching
578 version string has priority over the newest version.
579 For example, this http://URL may be specified as:
581 · http://www.example.org/([\d\.]+)/
583 Please note the trailing / in the above to make ([\d\.]+) as the
585 directory.
586 If the pagemangle rule exists, the whole downloaded web page as a
588 string is normalized by applying this rule to it. This is very
589 powerful tool and needs to be used with caution. If other mangling
590 rules can be used to address your objective, do not use this rule.
591 The downloaded web page is scanned for hrefs defined in the <a href="
593 ... "> tag to locate the candidate upstream tarball hrefs. These
594 candidate upstream tarball hrefs are matched by the Perl regex pattern
595 matching-pattern such as DL-(?:[\d\.]+?)/foo-(.+)\.tar\.gz to narrow
596 down the candidates. This pattern match needs to be anchored at the
597 beginning and the end. For example, candidate hrefs may be:
598 · DL-2.02/foo-2.02.tar.gz
600 · DL-2.03/foo-2.03.tar.gz
602 · DL-2.04/foo-2.04.tar.gz
604 Here the matching string of (.+) in matching-pattern is considered as
606 the candidate upstream version. If there are multiple matching strings
607 of capturing patterns in matching-pattern, they are all concatenated
608 with . (period) to form the candidate upstream version. Make sure to
609 use the non-capturing regex such as (?:[\d\.]+?) instead for the
610 variable text matching part unrelated to the version.
611 Then, the candidate upstream versions are:
613 · 2.02
615 · 2.03
617 · 2.04
619 The downloaded tarball filename is basically set to the same as the
621 filename in the remote URL of the selected href.
622 If the uversionmangle rule exists, the candidate upstream versions are
624 normalized by applying this rule to them. (This rule may be useful if
625 the upstream version scheme doesn't sort correctly to identify the
626 newest version.)
627 The upstream tarball href corresponding to the newest (uversionmangled)
629 candidate upstream version newer than the (dversionmangled) last
630 upstream version is selected.
631 If multiple upstream tarball hrefs corresponding to a single version
633 with different extensions exist, the highest compression one is chosen.
634 (Priority: tar.xz > tar.lzma > tar.bz2 > tar.gz.)
635 If the selected upstream tarball href is the relative URL, it is
637 converted to the absolute URL using the base URL of the web page. If
638 the <base href=" ... "> tag exists in the web page, the selected
639 upstream tarball href is converted to the absolute URL using the
640 specified base URL in the base tag, instead.
641 If the downloadurlmangle rule exists, the selected upstream tarball
643 href is normalized by applying this rule to it. (This is useful for
644 some sites with the obfuscated download URL.)
645 If the filenamemangle rule exists, the downloaded tarball filename is
647 generated by applying this rule to the selected href if matching-
648 pattern can extract the latest upstream version <uversion> from the
649 selected href string. Otherwise, generate the upstream tarball filename
650 from its full URL string and set the missing <uversion> from the
651 generated upstream tarball filename.
652 Without the filenamemangle rule, the default upstream tarball filename
654 is generated by taking the last component of the URL and removing
655 everything after any '?' or '#'.
656 uscan downloads the selected upstream tarball to the parent ../
658 directory. For example, the downloaded file may be:
659 · ../foo-2.04.tar.gz
661 Let's call this downloaded version 2.04 in the above example
663 generically as <uversion> in the following.
664 If the pgpsigurlmangle rule exists, the upstream signature file URL is
666 generated by applying this rule to the (downloadurlmangled) selected
667 upstream tarball href and the signature file is tried to be downloaded
668 from it.
669 If the pgpsigurlmangle rule doesn't exist, uscan warns user if the
671 matching upstream signature file is available from the same URL with
672 their filename being suffixed by the 5 common suffix asc, gpg, pgp, sig
673 and sign. (You can avoid this warning by setting pgpmode=none.)
674 If the signature file is downloaded, the downloaded upstream tarball is
676 checked for its authenticity against the downloaded signature file
677 using the armored keyring debian/upstream/signing-key.asc (see
678 "KEYRING FILE EXAMPLES"). If its signature is not valid, or not made
679 by one of the listed keys, uscan will report an error.
680 If the oversionmangle rule exists, the source tarball version oversion
682 is generated from the downloaded upstream version uversion by applying
683 this rule. This rule is useful to add suffix such as +dfsg1 to the
684 version of all the source packages of the MUT package for which the
685 repacksuffix mechanism doesn't work.
686 uscan invokes mk-origtargz to create the source tarball properly named
688 for the source package with .orig. (or .orig-<component>. for the
689 secondary tarballs) in its filename.
690 case A: packaging of the upstream tarball as is
692 mk-origtargz creates a symlink ../bar_<oversion>.orig.tar.gz linked
693 to the downloaded local upstream tarball. Here, bar is the source
694 package name found in debian/changelog. The generated symlink may
695 be:
696 · ../bar_2.04.orig.tar.gz -> foo-2.04.tar.gz (as is)
698 Usually, there is no need to set up opts="dversionmangle= ... " for
700 this case.
701 case B: packaging of the upstream tarball after removing non-DFSG files
703 mk-origtargz checks the filename glob of the Files-Excluded stanza
704 in the first section of debian/copyright, removes matching files to
705 create a repacked upstream tarball. Normally, the repacked
706 upstream tarball is renamed with suffix to
707 ../bar_<oversion><suffix>.orig.tar.gz using the repacksuffix option
708 for the single upstream package. Here <oversion> is updated to
709 be <oversion><suffix>.
710 The removal of files is required if files are not DFSG-compliant.
712 For such case, +dfsg1 is used as suffix.
713 So the combined options are set as
715 opts="dversionmangle=s/\+dfsg\d*$// ,repacksuffix=+dfsg1", instead.
716 For example, the repacked upstream tarball may be:
718 · ../bar_2.04+dfsg1.orig.tar.gz (repackaged)
720 uscan normally invokes "uupdate --find --upstream-version oversion "
722 for the version=4 watch file.
723 Please note that --find option is used here since mk-origtargz has been
725 invoked to make *.orig.tar.gz file already. uscan picks bar from
726 debian/changelog.
727 It creates the new upstream source tree under the ../bar-<oversion>
729 directory and Debianize it leveraging the last package contents.
730
732 When writing the watch file, you should rely on the latest upstream
733 source announcement web page. You should not try to second guess the
734 upstream archive structure if possible. Here are the typical
735 debian/watch files.
736 Please note that executing uscan with -v or -vv reveals what exactly
738 happens internally.
739 The existence and non-existence of a space the before tailing \ (back
741 slash) are significant.
742 Some undocumented shorter configuration strings are used in the below
744 EXAMPLES to help you with typing. These are intentional ones. uscan
745 is written to accept such common sense abbreviations but don't push the
746 limit.
747 HTTP site (basic)
749 Here is an example for the basic single upstream tarball.
750 version=4
752 http://example.com/~user/release/foo.html \
753 files/foo-([\d\.]+)\.tar\.gz debian uupdate
754 Or using the special strings:
756 version=4
758 http://example.com/~user/release/@PACKAGE@.html \
759 files/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian uupdate
760 For the upstream source package foo-2.0.tar.gz, this watch file
762 downloads and creates the Debian orig.tar file foo_2.0.orig.tar.gz.
763 HTTP site (pgpsigurlmangle)
765 Here is an example for the basic single upstream tarball with the
766 matching signature file in the same file path.
767 version=4
769 opts="pgpsigurlmangle=s%$%.asc%" http://example.com/release/@PACKAGE@.html \
770 files/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian uupdate
771 For the upstream source package foo-2.0.tar.gz and the upstream
773 signature file foo-2.0.tar.gz.asc, this watch file downloads these
774 files, verifies the authenticity using the keyring
775 debian/upstream/signing-key.asc and creates the Debian orig.tar file
776 foo_2.0.orig.tar.gz.
777 Here is another example for the basic single upstream tarball with the
779 matching signature file on decompressed tarball in the same file path.
780 version=4
782 opts="pgpsigurlmangle=s%@ARCHIVE_EXT@$%.asc%,decompress" \
783 http://example.com/release/@PACKAGE@.html \
784 files/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian uupdate
785 For the upstream source package foo-2.0.tar.gz and the upstream
787 signature file foo-2.0.tar.asc, this watch file downloads these files,
788 verifies the authenticity using the keyring
789 debian/upstream/signing-key.asc and creates the Debian orig.tar file
790 foo_2.0.orig.tar.gz.
791 HTTP site (pgpmode=next/previous)
793 Here is an example for the basic single upstream tarball with the
794 matching signature file in the unrelated file path.
795 version=4
797 opts="pgpmode=next" http://example.com/release/@PACKAGE@.html \
798 files/(?:\d+)/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian
799 opts="pgpmode=previous" http://example.com/release/@PACKAGE@.html \
800 files/(?:\d+)/@PACKAGE@@ANY_VERSION@@SIGNATURE_EXT@ previous uupdate
801 (?:\d+) part can be any random value. The tarball file can have 53,
803 while the signature file can have 33.
804 ([\d\.]+) part for the signature file has a strict requirement to match
806 that for the upstream tarball specified in the previous line by having
807 previous as version in the watch line.
808 HTTP site (flexible)
810 Here is an example for the maximum flexibility of upstream tarball and
811 signature file extensions.
812 version=4
814 opts="pgpmode=next" http://example.com/DL/ \
815 files/(?:\d+)/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian
816 opts="pgpmode=previous" http://example.com/DL/ \
817 files/(?:\d+)/@PACKAGE@@ANY_VERSION@@SIGNATURE_EXT@ \
818 previous uupdate
819 HTTP site (basic MUT)
821 Here is an example for the basic multiple upstream tarballs.
822 version=4
824 opts="pgpsigurlmangle=s%$%.sig%" \
825 http://example.com/release/foo.html \
826 files/foo-([\d\.]+)\.tar\.gz debian
827 opts="pgpsigurlmangle=s%$%.sig%, component=bar" \
828 http://example.com/release/foo.html \
829 files/foobar-([\d\.]+)\.tar\.gz same
830 opts="pgpsigurlmangle=s%$%.sig%, component=baz" \
831 http://example.com/release/foo.html \
832 files/foobaz-([\d\.]+)\.tar\.gz same uupdate
833 For the main upstream source package foo-2.0.tar.gz and the secondary
835 upstream source packages foobar-2.0.tar.gz and foobaz-2.0.tar.gz which
836 install under bar/ and baz/, this watch file downloads and creates the
837 Debian orig.tar file foo_2.0.orig.tar.gz, foo_2.0.orig-bar.tar.gz and
838 foo_2.0.orig-baz.tar.gz. Also, these upstream tarballs are verified by
839 their signature files.
840 HTTP site (recursive directory scanning)
842 Here is an example with the recursive directory scanning for the
843 upstream tarball and its signature files released in a directory named
844 after their version.
845 version=4
847 opts="pgpsigurlmangle=s%$%.sig%, dirversionmangle=s/-PRE/~pre/;s/-RC/~rc/" \
848 http://tmrc.mit.edu/mirror/twisted/Twisted/([\d+\.]+)/ \
849 Twisted-([\d\.]+)\.tar\.xz debian uupdate
850 Here, the web site should be accessible at the following URL:
852 http://tmrc.mit.edu/mirror/twisted/Twisted/
854 Here, dirversionmangle option is used to normalize the sorting order of
856 the directory names.
857 HTTP site (alternative shorthand)
859 For the bare HTTP site where you can directly see archive filenames,
860 the normal watch file:
861 version=4
863 opts="pgpsigurlmangle=s%$%.sig%" \
864 http://www.cpan.org/modules/by-module/Text/ \
865 Text-CSV_XS-(.+)\.tar\.gz \
866 debian uupdate
867 can be rewritten in an alternative shorthand form only with a single
869 string covering URL and filename:
870 version=4
872 opts="pgpsigurlmangle=s%$%.sig%" \
873 http://www.cpan.org/modules/by-module/Text/Text-CSV_XS-(.+)\.tar\.gz \
874 debian uupdate
875 In version=4, initial white spaces are dropped. Thus, this alternative
877 shorthand form can also be written as:
878 version=4
880 opts="pgpsigurlmangle=s%$%.sig%" \
881 http://www.cpan.org/modules/by-module/Text/\
882 Text-CSV_XS-(.+)\.tar\.gz \
883 debian uupdate
884 Please note the subtle difference of a space before the tailing \
886 between the first and the last examples.
887 HTTP site (funny version)
889 For a site which has funny version numbers, the parenthesized groups
890 will be joined with . (period) to make a sanitized version number.
891 version=4
893 http://www.site.com/pub/foobar/foobar_v(\d+)_(\d+)\.tar\.gz \
894 debian uupdate
895 HTTP site (DFSG)
897 The upstream part of the Debian version number can be mangled to
898 indicate the source package was repackaged to clean up non-DFSG files:
899 version=4
901 opts="dversionmangle=s/\+dfsg\d*$//,repacksuffix=+dfsg1" \
902 http://some.site.org/some/path/foobar-(.+)\.tar\.gz debian uupdate
903 See "COPYRIGHT FILE EXAMPLES".
905 HTTP site (filenamemangle)
907 The upstream tarball filename is found by taking the last component of
908 the URL and removing everything after any '?' or '#'.
909 If this does not fit to you, use filenamemangle. For example, <A
911 href="http://foo.bar.org/dl/?path=&dl=foo-0.1.1.tar.gz"> could be
912 handled as:
913 version=4
915 opts=filenamemangle=s/.*=(.*)/$1/ \
916 http://foo.bar.org/dl/\?path=&dl=foo-(.+)\.tar\.gz \
917 debian uupdate
918 <A href="http://foo.bar.org/dl/?path=&dl_version=0.1.1"> could be
920 handled as:
921 version=4
923 opts=filenamemangle=s/.*=(.*)/foo-$1\.tar\.gz/ \
924 http://foo.bar.org/dl/\?path=&dl_version=(.+) \
925 debian uupdate
926 If the href string has no version using <I>matching-pattern>, the
928 version can be obtained from the full URL using filenamemangle.
929 version=4
931 opts=filenamemangle=s&.*/dl/(.*)/foo\.tar\.gz&foo-$1\.tar\.gz& \
932 http://foo.bar.org/dl/([\.\d]+)/ foo.tar.gz \
933 debian uupdate
934 HTTP site (downloadurlmangle)
936 The option downloadurlmangle can be used to mangle the URL of the file
937 to download. This can only be used with http:// URLs. This may be
938 necessary if the link given on the web page needs to be transformed in
939 some way into one which will work automatically, for example:
940 version=4
942 opts=downloadurlmangle=s/prdownload/download/ \
943 http://developer.berlios.de/project/showfiles.php?group_id=2051 \
944 http://prdownload.berlios.de/softdevice/vdr-softdevice-(.+).tgz \
945 debian uupdate
946 HTTP site (oversionmangle, MUT)
948 The option oversionmangle can be used to mangle the version of the
949 source tarball (.orig.tar.gz and .orig-bar.tar.gz). For example,
950 +dfsg1 can be added to the upstream version as:
951 version=4
953 opts=oversionmangle=s/(.*)/$1+dfsg1/ \
954 http://example.com/~user/release/foo.html \
955 files/foo-([\d\.]*).tar.gz debian
956 opts="component=bar" \
957 http://example.com/~user/release/foo.html \
958 files/bar-([\d\.]*).tar.gz same uupdate
959 See "COPYRIGHT FILE EXAMPLES".
961 HTTP site (pagemangle)
963 The option pagemangle can be used to mangle the downloaded web page
964 before applying other rules. The non-standard web page without proper
965 <a href=" << ... >> "> entries can be converted. For example, if
966 foo.html uses <a bogus=" ... ">, this can be converted to the standard
967 page format with:
968 version=4
970 opts=pagemangle="s/<a\s+bogus=/<a href=/g" \
971 http://example.com/release/foo.html \
972 files/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian uupdate
973 Please note the use of g here to replace all occurrences.
975 If foo.html uses <Key> ... </Key>, this can be converted to the
977 standard page format with:
978 version=4
980 opts="pagemangle=s%<Key>([^<]*)</Key>%<Key><a href="$1">$1</a></Key>%g" \
981 http://example.com/release/foo.html \
982 (?:.*)/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian uupdate
983 FTP site (basic):
985 version=4
986 ftp://ftp.tex.ac.uk/tex-archive/web/c_cpp/cweb/cweb-(.+)\.tar\.gz \
987 debian uupdate
988 FTP site (regex special characters):
990 version=4
991 ftp://ftp.worldforge.org/pub/worldforge/libs/\
992 Atlas-C++/transitional/Atlas-C\+\+-(.+)\.tar\.gz debian uupdate
993 Please note that this URL is connected to be ... libs/Atlas-C++/ ...
995 . For ++, the first one in the directory path is verbatim while the one
996 in the filename is escaped by \.
997 FTP site (funny version)
999 This is another way of handling site with funny version numbers, this
1000 time using mangling. (Note that multiple groups will be concatenated
1001 before mangling is performed, and that mangling will only be performed
1002 on the basename version number, not any path version numbers.)
1003 version=4
1005 opts="uversionmangle=s/^/0.0./" \
1006 ftp://ftp.ibiblio.org/pub/Linux/ALPHA/wine/\
1007 development/Wine-(.+)\.tar\.gz debian uupdate
1008 sf.net
1010 For SourceForge based projects, qa.debian.org runs a redirector which
1011 allows a simpler form of URL. The format below will automatically be
1012 rewritten to use the redirector with the watch file:
1013 version=4
1015 https://sf.net/<project>/ <tar-name>-(.+)\.tar\.gz debian uupdate
1016 For audacity, set the watch file as:
1018 version=4
1020 https://sf.net/audacity/ audacity-minsrc-(.+)\.tar\.gz debian uupdate
1021 Please note, you can still use normal functionalities of uscan to set
1023 up a watch file for this site without using the redirector.
1024 version=4
1026 opts="uversionmangle=s/-pre/~pre/, \
1027 filenamemangle=s%(?:.*)audacity-minsrc-(.+)\.tar\.xz/download%\
1028 audacity-$1.tar.xz%" \
1029 http://sourceforge.net/projects/audacity/files/audacity/(\d[\d\.]+)/ \
1030 (?:.*)audacity-minsrc-([\d\.]+)\.tar\.xz/download debian uupdate
1031 Here, % is used as the separator instead of the standard /.
1033 github.com
1035 For GitHub based projects, you can use the tags or releases page. The
1036 archive URL uses only the version as the filename. You can rename the
1037 downloaded upstream tarball from into the standard
1038 <project>-<version>.tar.gz using filenamemangle:
1039 version=4
1041 opts="filenamemangle=s%(?:.*?)?v?(\d[\d.]*)\.tar\.gz%<project>-$1.tar.gz%" \
1042 https://github.com/<user>/<project>/tags \
1043 (?:.*?/)?v?(\d[\d.]*)\.tar\.gz debian uupdate
1044 PyPI
1046 For PyPI based projects, pypi.debian.net runs a redirector which allows
1047 a simpler form of URL. The format below will automatically be rewritten
1048 to use the redirector with the watch file:
1049 version=4
1051 https://pypi.python.org/packages/source/<initial>/<project>/ \
1052 <tar-name>-(.+)\.tar\.gz debian uupdate
1053 For cfn-sphere, set the watch file as:
1055 version=4
1057 https://pypi.python.org/packages/source/c/cfn-sphere/ \
1058 cfn-sphere-([\d\.]+).tar.gz debian uupdate
1059 Please note, you can still use normal functionalities of uscan to set
1061 up a watch file for this site without using the redirector.
1062 version=4
1064 opts="pgpmode=none" \
1065 https://pypi.python.org/pypi/cfn-sphere/ \
1066 https://pypi.python.org/packages/.*/.*/.*/\
1067 cfn-sphere-([\d\.]+).tar.gz#.* debian uupdate
1068 code.google.com
1070 Sites which used to be hosted on the Google Code service should have
1071 migrated to elsewhere (github?). Please look for the newer upstream
1072 site if available.
1073 npmjs.org (node modules)
1075 npmjs.org modules are published in JSON files. Here is a way to read
1076 them:
1077 version=4
1079 opts="searchmode=plain" \
1080 https://registry.npmjs.org/aes-js \
1081 https://registry.npmjs.org/aes-js/-/aes-js-(\d[\d\.]*)@ARCHIVE_EXT@
1082 grouped package
1084 Some node modules are split into multiple little upstream package. Here
1085 is a way to group them:
1086 version=4
1088 opts="searchmode=plain,pgpmode=none" \
1089 https://registry.npmjs.org/mongodb \
1090 https://registry.npmjs.org/mongodb/-/mongodb-(\d[\d\.]*)@ARCHIVE_EXT@ group
1091 opts="searchmode=plain,pgpmode=none,component=bson" \
1092 https://registry.npmjs.org/bson \
1093 https://registry.npmjs.org/bson/-/bson-(\d[\d\.]*)@ARCHIVE_EXT@ group
1094 opts="searchmode=plain,pgpmode=none,component=mongodb-core" \
1095 https://registry.npmjs.org/mongodb-core \
1096 https://registry.npmjs.org/mongodb-core/-/mongodb-core-(\d[\d\.]*)@ARCHIVE_EXT@ group
1097 opts="searchmode=plain,pgpmode=none,component=requireoptional" \
1098 https://registry.npmjs.org/require_optional \
1099 https://registry.npmjs.org/require_optional/-/require_optional-(\d[\d\.]*)@ARCHIVE_EXT@ group
1100 Package version is then the concatenation of upstream versions
1102 separated by "+~".
1103 To avoid having a too long version, the "checksum" method can be used.
1105 In this case, the main source has to be declared as "group":
1106 version=4
1108 opts="searchmode=plain,pgpmode=none" \
1109 https://registry.npmjs.org/mongodb \
1110 https://registry.npmjs.org/mongodb/-/mongodb-(\d[\d\.]*)@ARCHIVE_EXT@ group
1111 opts="searchmode=plain,pgpmode=none,component=bson" \
1112 https://registry.npmjs.org/bson \
1113 https://registry.npmjs.org/bson/-/bson-(\d[\d\.]*)@ARCHIVE_EXT@ checksum
1114 opts="searchmode=plain,pgpmode=none,component=mongodb-core" \
1115 https://registry.npmjs.org/mongodb-core \
1116 https://registry.npmjs.org/mongodb-core/-/mongodb-core-(\d[\d\.]*)@ARCHIVE_EXT@ checksum
1117 opts="searchmode=plain,pgpmode=none,component=requireoptional" \
1118 https://registry.npmjs.org/require_optional \
1119 https://registry.npmjs.org/require_optional/-/require_optional-(\d[\d\.]*)@ARCHIVE_EXT@ checksum
1120 The "checksum" is made up of the separate sum of each number composing
1122 the component versions. Following is an example with 3 components
1123 whose versions are "1.2.4", "2.0.1" and "10.0", with the main tarball
1124 having version "2.0.6":
1125 Main: 2.0.6
1127 Comp1: 1 . 2 . 4
1128 Comp2: 2 . 0 . 1
1129 Comp3: 10 . 0
1130 ================================
1131 Result : 1+2.10 . 2+0+0 . 4+1
1132 Checksum: 13 . 2 . 5
1133 ================================
1134 Final Version: 2.0.6+~cs13.2.5
1135 uscan will also display the original version string before being
1137 encoded into the checksum, which can for example be used in a
1138 debian/changelog entry to easily follow the changes:
1139 2.0.6+~1.2.4+~2.0.1+~10.0
1141 Note: This feature currently accepts only versions composed of digits
1143 and full stops (`.`).
1144 direct access to the git repository (tags)
1146 If the upstream only publishes its code via the git repository and its
1147 code has no web interface to obtain the release tarball, you can use
1148 uscan with the tags of the git repository to track and package the new
1149 upstream release.
1150 version=4
1152 opts="mode=git, gitmode=full, pgpmode=none" \
1153 http://git.ao2.it/tweeper.git \
1154 refs/tags/v([\d\.]+) debian uupdate
1155 Please note "git ls-remote" is used to obtain references for tags.
1157 If a tag v20.5 is the newest tag, the above example downloads
1159 spkg-20.5.tar.xz after making a full clone of the git repository which
1160 is needed for dumb git server.
1161 If tags are signed, set pgpmode=gittag to verify them.
1163 direct access to the git repository (HEAD)
1165 If the upstream only publishes its code via the git repository and its
1166 code has no web interface nor the tags to obtain the released tarball,
1167 you can use uscan with the HEAD of the git repository to track and
1168 package the new upstream release with an automatically generated
1169 version string.
1170 version=4
1172 opts="mode=git, pgpmode=none" \
1173 https://github.com/Debian/dh-make-golang \
1174 HEAD debian uupdate
1175 Please note that a local shallow copy of the git repository is made
1177 with "git clone --bare --depth=1 ..." normally in the target directory.
1178 uscan generates the new upstream version with "git log
1179 --date=format:%Y%m%d --pretty=0.0~git%cd.%h" on this local copy of
1180 repository as its default behavior.
1181 The generation of the upstream version string may the adjusted to your
1183 taste by adding pretty and date options to the opts arguments.
1184 direct access to the Subversion repository (tags)
1186 If the upstream only publishes its code via the Subversion repository
1187 and its code has no web interface to obtain the release tarball, you
1188 can use uscan with the tags of the Subversion repository to track and
1189 package the new upstream release.
1190 version=4
1192 opts="mode=svn, pgpmode=none" \
1193 svn://svn.code.sf.net/p/jmol/code/tags/ \
1194 ([\d.]+)\/ debian uupdate
1195 direct access to the Subversion repository (HEAD)
1197 If the upstream only publishes its code via the Subversion repository
1198 and its code has no web interface to obtain the release tarball, you
1199 can use uscan to get the most recent source of a subtree in the
1200 repository with an automatically generated version string.
1201 version=4
1203 opts="mode=svn, pgpmode=none" \
1204 svn://svn.code.sf.net/p/jmol/code/trunk/ \
1205 HEAD debian uupdate
1206 By default, uscan generates the new upstream version by appending the
1208 revision number to "0.0~svn". This can later be changed using
1209 uversionmangle.
1210
1212 Here is an example for the debian/copyright file which initiates
1213 automatic repackaging of the upstream tarball into
1214 <spkg>_<oversion>.orig.tar.gz (In debian/copyright, the Files-Excluded
1215 and Files-Excluded-component stanzas are a part of the first paragraph
1216 and there is a blank line before the following paragraphs which contain
1217 Files and other stanzas.):
1218 Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
1220 Files-Excluded: exclude-this
1221 exclude-dir
1222 */exclude-dir
1223 .*
1224 */js/jquery.js
1225 Files: *
1227 Copyright: ...
1228 ...
1229 Here is another example for the debian/copyright file which initiates
1231 automatic repackaging of the multiple upstream tarballs into
1232 <spkg>_<oversion>.orig.tar.gz and <spkg>_<oversion>.orig-bar.tar.gz:
1233 Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
1235 Files-Excluded: exclude-this
1236 exclude-dir
1237 */exclude-dir
1238 .*
1239 */js/jquery.js
1240 Files-Excluded-bar: exclude-this
1241 exclude-dir
1242 */exclude-dir
1243 .*
1244 */js/jquery.js
1245 Files: *
1247 Copyright: ...
1248 ...
1249 See mk-origtargz(1).
1251
1253 Let's assume that the upstream "uscan test key (no secret)
1254 <none@debian.org>" signs its package with a secret OpenPGP key and
1255 publishes the corresponding public OpenPGP key. This public OpenPGP
1256 key can be identified in 3 ways using the hexadecimal form.
1257 · The fingerprint as the 20 byte data calculated from the public
1259 OpenPGP key. E. g., 'CF21 8F0E 7EAB F584 B7E2 0402 C77E 2D68 7254
1260 3FAF'
1261 · The long keyid as the last 8 byte data of the fingerprint. E. g.,
1263 'C77E2D6872543FAF'
1264 · The short keyid is the last 4 byte data of the fingerprint. E. g.,
1266 '72543FAF'
1267 Considering the existence of the collision attack on the short keyid,
1269 the use of the long keyid is recommended for receiving keys from the
1270 public key servers. You must verify the downloaded OpenPGP key using
1271 its full fingerprint value which you know is the trusted one.
1272 The armored keyring file debian/upstream/signing-key.asc can be created
1274 by using the gpg (or gpg2) command as follows.
1275 $ gpg --recv-keys "C77E2D6872543FAF"
1277 ...
1278 $ gpg --finger "C77E2D6872543FAF"
1279 pub 4096R/72543FAF 2015-09-02
1280 Key fingerprint = CF21 8F0E 7EAB F584 B7E2 0402 C77E 2D68 7254 3FAF
1281 uid uscan test key (no secret) <none@debian.org>
1282 sub 4096R/52C6ED39 2015-09-02
1283 $ cd path/to/<upkg>-<uversion>
1284 $ mkdir -p debian/upstream
1285 $ gpg --export --export-options export-minimal --armor \
1286 'CF21 8F0E 7EAB F584 B7E2 0402 C77E 2D68 7254 3FAF' \
1287 >debian/upstream/signing-key.asc
1288 The binary keyring files, debian/upstream/signing-key.pgp and
1290 debian/upstream-signing-key.pgp, are still supported but deprecated.
1291 If a group of developers sign the package, you need to list
1293 fingerprints of all of them in the argument for gpg --export ... to
1294 make the keyring to contain all OpenPGP keys of them.
1295 Sometimes you may wonder who made a signature file. You can get the
1297 public keyid used to create the detached signature file
1298 foo-2.0.tar.gz.asc by running gpg as:
1299 $ gpg -vv foo-2.0.tar.gz.asc
1301 gpg: armor: BEGIN PGP SIGNATURE
1302 gpg: armor header: Version: GnuPG v1
1303 :signature packet: algo 1, keyid C77E2D6872543FAF
1304 version 4, created 1445177469, md5len 0, sigclass 0x00
1305 digest algo 2, begin of digest 7a c7
1306 hashed subpkt 2 len 4 (sig created 2015-10-18)
1307 subpkt 16 len 8 (issuer key ID C77E2D6872543FAF)
1308 data: [4091 bits]
1309 gpg: assuming signed data in `foo-2.0.tar.gz'
1310 gpg: Signature made Sun 18 Oct 2015 11:11:09 PM JST using RSA key ID 72543FAF
1311 ...
1312
1314 For the basic usage, uscan does not require to set these options.
1315 --conffile, --conf-file
1317 Add or replace default configuration files ("/etc/devscripts.conf"
1318 and "~/.devscripts"). This can only be used as the first option
1319 given on the command-line.
1320 replace:
1322 uscan --conf-file test.conf --verbose
1323 add:
1325 uscan --conf-file +test.conf --verbose
1326 If one --conf-file has no "+", default configuration files are
1328 ignored.
1329 --no-conf, --noconf
1331 Don't read any configuration files. This can only be used as the
1332 first option given on the command-line.
1333 --no-verbose
1335 Don't report verbose information. (default)
1336 --verbose, -v
1338 Report verbose information.
1339 --debug, -vv
1341 Report verbose information including the downloaded web pages as
1342 processed to STDERR for debugging.
1343 --dehs
1345 Send DEHS style output (XML-type) to STDOUT, while send all other
1346 uscan output to STDERR.
1347 --no-dehs
1349 Use only traditional uscan output format. (default)
1350 --download, -d
1352 Download the new upstream release. (default)
1353 --force-download, -dd
1355 Download the new upstream release even if up-to-date. (may not
1356 overwrite the local file)
1357 --overwrite-download, -ddd
1359 Download the new upstream release even if up-to-date. (may
1360 overwrite the local file)
1361 --no-download, --nodownload
1363 Don't download and report information.
1364 Previously downloaded tarballs may be used.
1366 Change default to --skip-signature.
1368 --signature
1370 Download signature. (default)
1371 --no-signature
1373 Don't download signature but verify if already downloaded.
1374 --skip-signature
1376 Don't bother download signature nor verifying signature.
1377 --safe, --report
1379 Avoid running unsafe scripts by skipping both the repacking of the
1380 downloaded package and the updating of the new source tree.
1381 Change default to --no-download and --skip-signature.
1383 When the objective of running uscan is to gather the upstream
1385 package status under the security conscious environment, please
1386 make sure to use this option.
1387 --report-status
1389 This is equivalent of setting "--verbose --safe".
1390 --download-version version
1392 Specify the version which the upstream release must match in order
1393 to be considered, rather than using the release with the highest
1394 version. (a best effort feature)
1395 --download-debversion version
1397 Specify the Debian package version to download the corresponding
1398 upstream release version. The dversionmangle and uversionmangle
1399 rules are considered. (a best effort feature)
1400 --download-current-version
1402 Download the currently packaged version. (a best effort feature)
1403 --check-dirname-level N
1405 See the below section "Directory name checking" for an explanation
1406 of this option.
1407 --check-dirname-regex regex
1409 See the below section "Directory name checking" for an explanation
1410 of this option.
1411 --destdir path Normally, uscan changes its internal current directory
1413 to the package's source directory where the debian/ is located. Then
1414 the destination directory for the downloaded tarball and other files is
1415 set to the parent directory ../ from this internal current directory.
1416 This default destination directory can be overridden by setting
1417 --destdir option to a particular path. If this path is a relative
1418 path, the destination directory is determined in relative to the
1419 internal current directory of uscan execution. If this path is a
1420 absolute path, the destination directory is set to path
1421 irrespective of the internal current directory of uscan execution.
1422 The above is true not only for the sinple uscan run in the single
1424 source tree but also for the advanced scanning uscan run with
1425 subdirectories holding multiple source trees.
1426 One exception is when --watchfile and --package are used together.
1428 For this case, the internal current directory of uscan execution
1429 and the default destination directory are set to the current
1430 directory . where uscan is started. The default destination
1431 directory can be overridden by setting --destdir option as well.
1432 --package package
1434 Specify the name of the package to check for rather than examining
1435 debian/changelog; this requires the --upstream-version (unless a
1436 version is specified in the watch file) and --watchfile options as
1437 well. Furthermore, no directory scanning will be done and nothing
1438 will be downloaded. This option automatically sets --no-download
1439 and --skip-signature; and probably most useful in conjunction with
1440 the DEHS system (and --dehs).
1441 --upstream-version upstream-version
1443 Specify the current upstream version rather than examine
1444 debian/watch or debian/changelog to determine it. This is ignored
1445 if a directory scan is being performed and more than one
1446 debian/watch file is found.
1447 --watchfile watchfile
1449 Specify the watchfile rather than perform a directory scan to
1450 determine it. If this option is used without --package, then uscan
1451 must be called from within the Debian package source tree (so that
1452 debian/changelog can be found simply by stepping up through the
1453 tree).
1454 One exception is when --watchfile and --package are used together.
1456 uscan can be called from anywhare and the internal current
1457 directory of uscan execution and the default destination directory
1458 are set to the current directory . where uscan is started.
1459 See more in the --destdir explanation.
1461 --bare
1463 Disable all site specific special case codes to perform URL
1464 redirections and page content alterations.
1465 --http-header
1467 Add specified header in HTTP requests for matching url. This option
1468 can be used more than one time, values must be in the form
1469 "baseUrl@Name=value. Example:
1470 uscan --http-header https://example.org@My-Token=qwertyuiop
1472 Security:
1474 The given baseUrl must exactly match the base url before '/'.
1476 Examples:
1477 | --http-header value | Good for | Never used |
1478 +------------------------------------+-----------------------------+------------+
1479 | https://example.org.com@Hdr=Value | https://example.org.com/... | |
1480 | https://example.org.com/@Hdr=Value | | X |
1481 | https://e.com:1879@Hdr=Value | https://e.com:1879/... | |
1482 | https://e.com:1879/dir@Hdr=Value | https://e.com:1879/dir/... | |
1483 | https://e.com:1879/dir/@Hdr=Value | | X |
1484 It is strongly recommended to not use this feature to pass a secret
1486 token over unciphered connection (http://)
1487 You can use "USCAN_HTTP_HEADER" variable (in "~/.devscripts") to
1488 hide secret token from scripts
1489 --no-exclusion
1490 Don't automatically exclude files mentioned in debian/copyright
1491 field Files-Excluded.
1492 --pasv
1494 Force PASV mode for FTP connections.
1495 --no-pasv
1497 Don't use PASV mode for FTP connections.
1498 --no-symlink
1500 Don't rename nor repack upstream tarball.
1501 --timeout N
1503 Set timeout to N seconds (default 20 seconds).
1504 --user-agent, --useragent
1506 Override the default user agent header.
1507 --help
1509 Give brief usage information.
1510 --version
1512 Display version information.
1513 uscan also accepts following options and passes them to mk-origtargz:
1515 --symlink
1517 Make orig.tar.gz (with the appropriate extension) symlink to the
1518 downloaded files. (This is the default behavior.)
1519 --copy
1521 Instead of symlinking as described above, copy the downloaded
1522 files.
1523 --rename
1525 Instead of symlinking as described above, rename the downloaded
1526 files.
1527 --repack
1529 After having downloaded an lzma tar, xz tar, bzip tar, gz tar, zip,
1530 jar, xpi archive, repack it to the specified compression (see
1531 --compression).
1532 The unzip package must be installed in order to repack zip and jar
1534 archives, the mozilla-devscripts package must be installed to
1535 repack xpi archives, and the xz-utils package must be installed to
1536 repack lzma or xz tar archives.
1537 --compression [ gzip | bzip2 | lzma | xz ]
1539 In the case where the upstream sources are repacked (either because
1540 --repack option is given or debian/copyright contains the field
1541 Files-Excluded), it is possible to control the compression method
1542 via the parameter. The default is gzip for normal tarballs, and xz
1543 for tarballs generated directly from the git repository.
1544 --copyright-file copyright-file
1546 Exclude files mentioned in Files-Excluded in the given copyright-
1547 file. This is useful when running uscan not within a source
1548 package directory.
1549
1551 For the basic usage, uscan does not require to set these configuration
1552 variables.
1553 The two configuration files /etc/devscripts.conf and ~/.devscripts are
1555 sourced by a shell in that order to set configuration variables. These
1556 may be overridden by command line options. Environment variable
1557 settings are ignored for this purpose. If the first command line option
1558 given is --noconf, then these files will not be read. The currently
1559 recognized variables are:
1560 USCAN_DOWNLOAD
1562 Download or report only:
1563 no: equivalent to --no-download, newer upstream files will not be
1565 downloaded.
1566 yes: equivalent to --download, newer upstream files will be
1567 downloaded. This is the default behavior.
1568 See also --force-download and --overwrite-download.
1569 USCAN_SAFE
1571 If this is set to yes, then uscan avoids running unsafe scripts by
1572 skipping both the repacking of the downloaded package and the
1573 updating of the new source tree; this is equivalent to the --safe
1574 options; this also sets the default to --no-download and
1575 --skip-signature.
1576 USCAN_PASV
1578 If this is set to yes or no, this will force FTP connections to use
1579 PASV mode or not to, respectively. If this is set to default, then
1580 Net::FTP(3) makes the choice (primarily based on the FTP_PASSIVE
1581 environment variable).
1582 USCAN_TIMEOUT
1584 If set to a number N, then set the timeout to N seconds. This is
1585 equivalent to the --timeout option.
1586 USCAN_SYMLINK
1588 If this is set to no, then a pkg_version.orig.tar.{gz|bz2|lzma|xz}
1589 symlink will not be made (equivalent to the --no-symlink option).
1590 If it is set to yes or symlink, then the symlinks will be made. If
1591 it is set to rename, then the files are renamed (equivalent to the
1592 --rename option).
1593 USCAN_DEHS_OUTPUT
1595 If this is set to yes, then DEHS-style output will be used. This is
1596 equivalent to the --dehs option.
1597 USCAN_VERBOSE
1599 If this is set to yes, then verbose output will be given. This is
1600 equivalent to the --verbose option.
1601 USCAN_USER_AGENT
1603 If set, the specified user agent string will be used in place of
1604 the default. This is equivalent to the --user-agent option.
1605 USCAN_DESTDIR
1607 If set, the downloaded files will be placed in this directory.
1608 This is equivalent to the --destdir option.
1609 USCAN_REPACK
1611 If this is set to yes, then after having downloaded a bzip tar,
1612 lzma tar, xz tar, or zip archive, uscan will repack it to the
1613 specified compression (see --compression). This is equivalent to
1614 the --repack option.
1615 USCAN_EXCLUSION
1617 If this is set to no, files mentioned in the field Files-Excluded
1618 of debian/copyright will be ignored and no exclusion of files will
1619 be tried. This is equivalent to the --no-exclusion option.
1620 USCAN_HTTP_HEADER
1622 If set, the specified http header will be used if URL match. This
1623 is equivalent to --http-header option.
1624
1626 The exit status gives some indication of whether a newer version was
1627 found or not; one is advised to read the output to determine exactly
1628 what happened and whether there were any warnings to be noted.
1629 0 Either --help or --version was used, or for some watch file which
1631 was examined, a newer upstream version was located.
1632 1 No newer upstream versions were located for any of the watch files
1634 examined.
1635
1637 uscan has many other enhanced features which are skipped in the above
1638 section for the simplicity. Let's check their highlights.
1639 uscan actually scans not just the current directory but all its
1641 subdirectories looking for debian/watch to process them all. See
1642 "Directory name checking".
1643 uscan can be executed with path as its argument to change the starting
1645 directory of search from the current directory to path .
1646 If you are not sure what exactly is happening behind the scene, please
1648 enable the --verbose option. If this is not enough, enable the --debug
1649 option too see all the internal activities.
1650 See "COMMANDLINE OPTIONS" and "DEVSCRIPT CONFIGURATION VARIABLES" for
1652 other variations.
1653 Custom script
1655 The optional script parameter in debian/watch means to execute script
1656 with options after processing this line if specified.
1657 See "HISTORY AND UPGRADING" for how uscan invokes the custom script.
1659 For compatibility with other tools such as git-buildpackage, it may not
1661 be wise to create custom scripts with random behavior. In general,
1662 uupdate is the best choice for the non-native package and custom
1663 scripts, if created, should behave as if uupdate. For possible use
1664 case, see <http://bugs.debian.org/748474> as an example.
1665 URL diversion
1667 Some popular web sites changed their web page structure causing
1668 maintenance problems to the watch file. There are some redirection
1669 services created to ease maintenance of the watch file. Currently,
1670 uscan makes automatic diversion of URL requests to the following URLs
1671 to cope with this situation.
1672 · <http://sf.net>
1674 · <http://pypi.python.org>
1676 Directory name checking
1678 Similarly to several other scripts in the devscripts package, uscan
1679 explores the requested directory trees looking for debian/changelog and
1680 debian/watch files. As a safeguard against stray files causing
1681 potential problems, and in order to promote efficiency, it will examine
1682 the name of the parent directory once it finds the debian/changelog
1683 file, and check that the directory name corresponds to the package
1684 name. It will only attempt to download newer versions of the package
1685 and then perform any requested action if the directory name matches the
1686 package name. Precisely how it does this is controlled by two
1687 configuration file variables DEVSCRIPTS_CHECK_DIRNAME_LEVEL and
1688 DEVSCRIPTS_CHECK_DIRNAME_REGEX, and their corresponding command-line
1689 options --check-dirname-level and --check-dirname-regex.
1690 DEVSCRIPTS_CHECK_DIRNAME_LEVEL can take the following values:
1692 0 Never check the directory name.
1694 1 Only check the directory name if we have had to change directory in
1696 our search for debian/changelog, that is, the directory containing
1697 debian/changelog is not the directory from which uscan was invoked.
1698 This is the default behavior.
1699 2 Always check the directory name.
1701 The directory name is checked by testing whether the current directory
1703 name (as determined by pwd(1)) matches the regex given by the
1704 configuration file option DEVSCRIPTS_CHECK_DIRNAME_REGEX or by the
1705 command line option --check-dirname-regex regex. Here regex is a Perl
1706 regex (see perlre(3perl)), which will be anchored at the beginning and
1707 the end. If regex contains a /, then it must match the full directory
1708 path. If not, then it must match the full directory name. If regex
1709 contains the string package, this will be replaced by the source
1710 package name, as determined from the debian/changelog. The default
1711 value for the regex is: package(-.+)?, thus matching directory names
1712 such as package and package-version.
1713
1715 This section briefly describes the backwards-incompatible watch file
1716 features which have been added in each watch file version, and the
1717 first version of the devscripts package which understood them.
1718 Pre-version 2
1720 The watch file syntax was significantly different in those days.
1721 Don't use it. If you are upgrading from a pre-version 2 watch
1722 file, you are advised to read this manpage and to start from
1723 scratch.
1724 Version 2
1726 devscripts version 2.6.90: The first incarnation of the current
1727 style of watch files.
1728 Version 3
1730 devscripts version 2.8.12: Introduced the following: correct
1731 handling of regex special characters in the path part,
1732 directory/path pattern matching, version number in several parts,
1733 version number mangling. Later versions have also introduced URL
1734 mangling.
1735 If you are upgrading from version 2, the key incompatibility is if
1737 you have multiple groups in the pattern part; whereas only the
1738 first one would be used in version 2, they will all be used in
1739 version 3. To avoid this behavior, change the non-version-number
1740 groups to be (?: ... ) instead of a plain ( ... ) group.
1741 · uscan invokes the custom script as "script --upstream-version
1743 version ../spkg_version.orig.tar.gz".
1744 · uscan invokes the standard uupdate as "uupdate --no-symlink
1746 --upstream-version version ../spkg_version.orig.tar.gz".
1747 Version 4
1749 devscripts version 2.15.10: The first incarnation of watch files
1750 supporting multiple upstream tarballs.
1751 The syntax of the watch file is relaxed to allow more spaces for
1753 readability.
1754 If you have a custom script in place of uupdate, you may also
1756 encounter problems updating from Version 3.
1757 · uscan invokes the custom script as "script --upstream-version
1759 version".
1760 · uscan invokes the standard uupdate as "uupdate --find
1762 --upstream-version version".
1763 Restriction for --dehs is lifted by redirecting other output to
1765 STDERR when it is activated.
1766
1768 dpkg(1), mk-origtargz(1), perlre(1), uupdate(1), devscripts.conf(5)
1769
1771 The original version of uscan was written by Christoph Lameter
1772 <clameter@debian.org>. Significant improvements, changes and bugfixes
1773 were made by Julian Gilbey <jdg@debian.org>. HTTP support was added by
1774 Piotr Roszatycki <dexter@debian.org>. The program was rewritten in Perl
1775 by Julian Gilbey. Xavier Guimard converted it in object-oriented Perl
1776 using Moo.
1777Debian Utilities 2020-07-27 USCAN(1)