1USCAN(1)                                                              USCAN(1)
2
3
4

NAME

6       uscan - scan/watch upstream sources for new releases of software
7

SYNOPSIS

9       uscan [options] [path]
10

DESCRIPTION

12       For basic usage, uscan is executed without any arguments from the root
13       of the Debianized source tree where you see the debian/ directory, or a
14       directory containing multiple source trees.
15
16       Unless --watchfile is given, uscan looks recursively for valid source
17       trees starting from the current directory (see the below section
18       "Directory name checking" for details).
19
20       For each valid source tree found, typically the following happens:
21
22uscan reads the first entry in debian/changelog to determine the
23           source package name <spkg> and the last upstream version.
24
25uscan process the watch lines debian/watch from the top to the
26           bottom in a single pass.
27
28uscan downloads a web page from the specified URL in
29               debian/watch.
30
31uscan extracts hrefs pointing to the upstream tarball(s) from
32               the web page using the specified matching-pattern in
33               debian/watch.
34
35uscan downloads the upstream tarball with the highest version
36               newer than the last upstream version.
37
38uscan saves the downloaded tarball to the parent ../ directory:
39               ../<upkg>-<uversion>.tar.gz
40
41uscan invokes mk-origtargz to create the source tarball:
42               ../<spkg>_<oversion>.orig.tar.gz
43
44               •   For a multiple upstream tarball (MUT) package, the
45                   secondary upstream tarball will instead be named
46                   ../<spkg>_<oversion>.orig-<component>.tar.gz.
47
48           •   Repeat until all lines in debian/watch are processed.
49
50uscan invokes uupdate to create the Debianized source tree:
51           ../<spkg>-<oversion>/*
52
53       Please note the following.
54
55       •   For simplicity, the compression method used in examples is gzip
56           with .gz suffix.  Other methods such as xz, bzip2, and lzma with
57           corresponding xz, bz2, and lzma suffixes may also be used.
58
59       •   The new version=4 enables handling of multiple upstream tarball
60           (MUT) packages but this is a rare case for Debian packaging.  For a
61           single upstream tarball package, there is only one watch line and
62           no ../<spkg>_<oversion>.orig-<component>.tar.gz .
63
64uscan with the --verbose option produces a human readable report of
65           uscan's execution.
66
67uscan with the --debug option produces a human readable report of
68           uscan's execution including internal variable states.
69
70uscan with the --extra-debug option produces a human readable
71           report of uscan's execution including internal variable states and
72           remote content during "search" step.
73
74uscan with the --dehs option produces an upstream package status
75           report in XML format for other programs such as the Debian External
76           Health System.
77
78       •   The primary objective of uscan is to help identify if the latest
79           version upstream tarball is used or not; and to download the latest
80           upstream tarball.  The ordering of versions is decided by dpkg
81           --compare-versions.
82
83uscan with the --safe option limits the functionality of uscan to
84           its primary objective.  Both the repacking of downloaded files and
85           updating of the source tree are skipped to avoid running unsafe
86           scripts.  This also changes the default to --no-download and
87           --skip-signature.
88

FORMAT OF THE WATCH FILE

90       The current version 4 format of debian/watch can be summarized as
91       follows:
92
93       •   Leading spaces and tabs are dropped.
94
95       •   Empty lines are dropped.
96
97       •   A line started by # (hash) is a comment line and dropped.
98
99       •   A single \ (back slash) at the end of a line is dropped and the
100           next line is concatenated after removing leading spaces and tabs.
101           The concatenated line is parsed as a single line. (The existence or
102           non-existence of the space before the tailing single \ is
103           significant.)
104
105       •   The first non-comment line is:
106
107           version=4
108
109           This is a required line and the recommended version number.
110
111           If you use "version=3" instead here, some features may not work as
112           documented here.  See "HISTORY AND UPGRADING".
113
114       •   The following non-comment lines (watch lines) specify the rules for
115           the selection of the candidate upstream tarball URLs and are in one
116           of the following three formats:
117
118opts=" ... " http://URL matching-pattern [version [script]]
119
120http://URL matching-pattern [version [script]]
121
122opts=" ... "
123
124           Here,
125
126opts=" ... " specifies the behavior of uscan.  See "WATCH FILE
127               OPTIONS".
128
129http://URL specifies the web page where upstream publishes the
130               link to the latest source archive.
131
132https://URL may also be used, as may
133
134ftp://URL
135
136               •   Some parts of URL may be in the regex match pattern
137                   surrounded between ( and ) such as /foo/bar-([\.\d]+)/.
138                   (If multiple directories match, the highest version is
139                   picked.) Otherwise, the URL is taken as verbatim.
140
141matching-pattern specifies the full string matching pattern for
142               hrefs in the web page.  See "WATCH FILE EXAMPLES".
143
144               •   All matching parts in ( and ) are concatenated with .
145                   (period) to form the upstream version.
146
147               •   If the hrefs do not contain directories, you can combine
148                   this with the previous entry. I.e., http://URL/matching-
149                   pattern .
150
151version restricts the upstream tarball which may be downloaded.
152               The newest available version is chosen in each case.
153
154debian (default) requires the downloading upstream tarball
155                   to be newer than the version obtained from
156                   debian/changelog.
157
158version-number such as 12.5 requires the upstream tarball
159                   to be newer than the version-number.
160
161same requires the downloaded version of the secondary
162                   tarballs to be exactly the same as the one for the first
163                   upstream tarball downloaded. (Useful only for MUT)
164
165previous restricts the version of the signature file. (Used
166                   with pgpmode=previous)
167
168ignore does not restrict the version of the secondary
169                   tarballs. (Maybe useful for MUT)
170
171group requires the downloading upstream tarball to be newer
172                   than the version obtained from debian/changelog. Package
173                   version is the concatenation of all "group" upstream
174                   version.
175
176checksum requires the downloading upstream tarball to be
177                   newer than the version obtained from debian/changelog.
178                   Package version is the concatenation of the version of the
179                   main tarball, followed by a checksum of all the tarballs
180                   using the "checksum" version system.  At least the main
181                   upstream source has to be declared as "group".
182
183script is executed at the end of uscan execution with
184               appropriate arguments provided by uscan (default: no action).
185
186               •   The typical Debian package is a non-native package made
187                   from one upstream tarball.  Only a single line of the watch
188                   line in one of the first two formats is usually used with
189                   its version set to debian and script set to uupdate.
190
191               •   A native package should not specify script.
192
193               •   A multiple upstream tarball (MUT) package should specify
194                   uupdate as script in the last watch line and should skip
195                   specifying script in the rest of the watch lines.
196
197           •   The last format of the watch line is useful to set the
198               persistent parameters: user-agent, compression.  If this format
199               is used, this must be followed by the URL defining watch
200               line(s).
201
202           •   [ and ] in the above format are there to mark the optional
203               parts and should not be typed.
204
205       There are a few special strings which are substituted by uscan to make
206       it easy to write the watch file.
207
208       @PACKAGE@
209           This is substituted with the source package name found in the first
210           line of the debian/changelog file.
211
212       @ANY_VERSION@
213           This is substituted by the legal upstream version regex
214           (capturing).
215
216             [-_]?(\d[\-+\.:\~\da-zA-Z]*)
217
218       @ARCHIVE_EXT@
219           This is substituted by the typical archive file extension regex
220           (non-capturing).
221
222             (?i)\.(?:tar\.xz|tar\.bz2|tar\.gz|zip|tgz|tbz|txz)
223
224       @SIGNATURE_EXT@
225           This is substituted by the typical signature file extension regex
226           (non-capturing).
227
228             (?i)\.(?:tar\.xz|tar\.bz2|tar\.gz|zip|tgz|tbz|txz)\.(?:asc|pgp|gpg|sig|sign)
229
230       @DEB_EXT@
231           This is substituted by the typical Debian extension regexp
232           (capturing).
233
234             [\+~](debian|dfsg|ds|deb)(\.)?(\d+)?$
235
236       Some file extensions are not included in the above intentionally to
237       avoid false positives.  You can still set such file extension patterns
238       manually.
239

WATCH FILE OPTIONS

241       uscan reads the watch options specified in opts=" ... " to customize
242       its behavior. Multiple options option1, option2, option3, ... can be
243       set as opts="option1, option2, option3,  ...  " .  The double quotes
244       are necessary if options contain any spaces.
245
246       Unless otherwise noted as persistent, most options are valid only
247       within their containing watch line.
248
249       The available watch options are:
250
251       component=component
252           Set the name of the secondary source tarball as
253           <spkg>_<oversion>.orig-<component>.tar.gz for a MUT package.
254
255       ctype=component-type
256           Set the type of component (only "nodejs" and "perl" are available
257           for now).  This will help uscan to find current version if
258           component version is ignored.
259
260           When using ctype=nodejs, uscan tries to find a version in
261           "package.json", when using ctype=perl, uscan tries to find a
262           version in "META.json".  If a version is found, it is used as
263           current version for this component, regardless version found in
264           Debian version string. This permits a better change detection when
265           using ignore or checksum as Debian version.
266
267       compression=method
268           Set the compression method when the tarball is repacked
269           (persistent).
270
271           Available method values are what mk-origtargz supports, so xz, gzip
272           (alias gz), bzip2 (alias bz2), lzma, default. The default method is
273           currently xz.  When uscan is launched in a debian source repository
274           which format is "1.0" or undefined, the method switches to gzip.
275
276           Please note the repacking of the upstream tarballs by mk-origtargz
277           happens only if one of the following conditions is satisfied:
278
279USCAN_REPACK is set in the devscript configuration.  See
280               "DEVSCRIPT CONFIGURATION VARIABLES".
281
282--repack is set on the commandline.  See <COMMANDLINE OPTIONS>.
283
284repack is set in the watch line as opts="repack,...".
285
286           •   The upstream archive is of zip type including jar, xpi, ...
287
288Files-Excluded or Files-Excluded-component stanzas are set in
289               debian/copyright to make mk-origtargz invoked from uscan remove
290               files from the upstream tarball and repack it.  See "COPYRIGHT
291               FILE EXAMPLES" and mk-origtargz(1).
292
293       repack
294           Force repacking of the upstream tarball using the compression
295           method.
296
297       repacksuffix=suffix
298           Add suffix to the Debian package upstream version only when the
299           source tarball is repackaged.  This rule should be used only for a
300           single upstream tarball package.
301
302       mode=mode
303           Set the archive download mode.
304
305           LWP This mode is the default one which downloads the specified
306               tarball from the archive URL on the web.  Automatically
307               internal mode value is updated to either http or ftp by URL.
308
309           git This mode accesses the upstream git archive directly with the
310               git command and packs the source tree with the specified tag
311               via matching-pattern into spkg-version.tar.xz.
312
313               If the upstream publishes the released tarball via its web
314               interface, please use it instead of using this mode. This mode
315               is the last resort method.
316
317               For git mode, matching-pattern specifies the full string
318               matching pattern for tags instead of hrefs. If matching-pattern
319               is set to refs/tags/tag-matching-pattern, uscan downloads
320               source from the refs/tags/matched-tag of the git repository.
321               The upstream version is extracted from concatenating the
322               matched parts in ( ... ) with . .  See "WATCH FILE EXAMPLES".
323
324               If matching-pattern is set to HEAD, uscan downloads source from
325               the HEAD of the git repository and the pertinent version is
326               automatically generated with the date and hash of the HEAD of
327               the git repository.
328
329               If matching-pattern is set to refs/heads/branch, uscan
330               downloads source from the named branch of the git repository.
331
332               The local repository is temporarily created as a bare git
333               repository directory under the destination directory where the
334               downloaded archive is generated.  This is normally erased after
335               the uscan execution.  This local repository is kept if --debug
336               option is used.
337
338               If the current directory is a git repository and the searched
339               repository is listed among the registered "remotes", then uscan
340               will use it instead of cloning separately.  The only local
341               change is that uscan will run a "fetch" command to refresh the
342               repository.
343
344           svn This mode accesses the upstream Subversion archive directly
345               with the svn command and packs the source tree.
346
347               For svn mode, matching-pattern specifies the full string
348               matching pattern for directories under Subversion repository
349               directory, specified via URL.  The upstream version is
350               extracted from concatenating the matched parts in ( ...  ) with
351               . .
352
353               If matching-pattern is set to HEAD, uscan downloads the latest
354               source tree of the URL.  The upstream version is then
355               constructed by appending the last revision of the URL to
356               0.0~svn.
357
358               As commit signing is not possible with Subversion, the default
359               pgpmode is set to none when mode=svn. Settings of pgpmode other
360               than default and none are reported as errors.
361
362       pretty=rule
363           Set the upstream version string to an arbitrary format as an
364           optional opts argument when the matching-pattern is HEAD or
365           heads/branch for git mode.  For the exact syntax, see the git-log
366           manpage under tformat.  The default is pretty=0.0~git%cd.%h.  No
367           uversionmangle rules is applicable for this case.
368
369           When pretty=describe is used, the upstream version string is the
370           output of the "git describe --tags | sed s/-/./g" command instead.
371           For example, if the commit is the 5-th after the last tag v2.17.12
372           and its short hash is ged992511, then the string is
373           v2.17.12.5.ged992511 .  For this case, it is good idea to add
374           uversionmangle=s/^/0.0~/ or uversionmangle=s/^v// to make the
375           upstream version string compatible with Debian.
376           uversionmangle=s/^v// may work as well.  Please note that in order
377           for pretty=describe to function well, upstream need to avoid
378           tagging with random alphabetic tags.
379
380           The pretty=describe forces to set gitmode=full to make a full local
381           clone of the repository automatically.
382
383       date=rule
384           Set the date string used by the pretty option to an arbitrary
385           format as an optional opts argument when the matching-pattern is
386           HEAD or heads/branch for git mode.  For the exact syntax, see the
387           strftime manpage.  The default is date=%Y%m%d.
388
389       gitexport=mode
390           Set the git archive export operation mode. The default is
391           gitexport=default.  Set this to gitexport=all to include all files
392           in the .orig.tar archive, ignoring any export-ignore git attributes
393           defined by the upstream.
394
395           This option is valid only in git mode.
396
397       gitmode=mode
398           Set the git clone operation mode. The default is gitmode=shallow.
399           For some dumb git server, you may need to manually set gitmode=full
400           to force full clone operation.
401
402           If the current directory is a git repository and the searched
403           repository is listed among the registered "remotes", then uscan
404           will use it instead of cloning separately.
405
406       pgpmode=mode
407           Set the PGP/GPG signature verification mode.
408
409           auto
410               uscan checks possible URLs for the signature file and
411               autogenerates a pgpsigurlmangle rule to use it.
412
413           default
414               Use pgpsigurlmangle=rules to generate the candidate upstream
415               signature file URL string from the upstream tarball URL.
416               (default)
417
418               If the specified pgpsigurlmangle is missing, uscan checks
419               possible URLs for the signature file and suggests adding a
420               pgpsigurlmangle rule.
421
422           mangle
423               Use pgpsigurlmangle=rules to generate the candidate upstream
424               signature file URL string from the upstream tarball URL.
425
426           next
427               Verify this downloaded tarball file with the signature file
428               specified in the next watch line.  The next watch line must be
429               pgpmode=previous.  Otherwise, no verification occurs.
430
431           previous
432               Verify the downloaded tarball file specified in the previous
433               watch line with this signature file.  The previous watch line
434               must be pgpmode=next.
435
436           self
437               Verify the downloaded file foo.ext with its self signature and
438               extract its content tarball file as foo.
439
440           gittag
441               Verify tag signature if mode=git.
442
443           none
444               No signature available. (No warning.)
445
446       searchmode=mode
447           Set the parsing search mode.
448
449           html (default): search pattern in "href" parameter of <a> HTML tags
450           plain: search pattern in the full page
451               This is useful if page content is not HTML but JSON. Example
452               with npmjs.com:
453
454                 version=4
455                 opts="searchmode=plain" \
456                  https://registry.npmjs.org/aes-js \
457                  https://registry.npmjs.org/aes-js/-/aes-js-(\d[\d\.]*)@ARCHIVE_EXT@
458
459       decompress
460           Decompress compressed archive before the pgp/gpg signature
461           verification.
462
463       bare
464           Disable all site specific special case code such as URL redirector
465           uses and page content alterations. (persistent)
466
467       user-agent=user-agent-string
468           Set the user-agent string used to contact the HTTP(S) server as
469           user-agent-string. (persistent)
470
471           user-agent option should be specified by itself in the watch line
472           without URL, to allow using semicolons and commas in it.
473
474       pasv, passive
475           Use PASV mode for the FTP connection.
476
477           If PASV mode is required due to the client side network
478           environment, set uscan to use PASV mode via "COMMANDLINE OPTIONS"
479           or "DEVSCRIPT CONFIGURATION VARIABLES" instead.
480
481       active, nopasv
482           Don't use PASV mode for the FTP connection.
483
484       unzipopt=options
485           Add the extra options to use with the unzip command, such as -a,
486           -aa, and -b, when executed by mk-origtargz.
487
488       dversionmangle=rules
489           Normalize the last upstream version string found in
490           debian/changelog to compare it to the available upstream tarball
491           version.  Removal of the Debian specific suffix such as
492           s/@DEB_EXT@// is usually done here.
493
494           You can also use dversionmangle=auto, this is exactly the same than
495           dversionmangle=s/@DEB_EXT@//
496
497       dirversionmangle=rules
498           Normalize the directory path string matching the regex in a set of
499           parentheses of http://URL as the sortable version index string.
500           This is used as the directory path sorting index only.
501
502           Substitution such as s/PRE/~pre/; s/RC/~rc/ may help.
503
504       pagemangle=rules
505           Normalize the downloaded web page string.  (Don't use this unless
506           this is absolutely needed.  Generally, g flag is required for these
507           rules.)
508
509           This is handy if you wish to access Amazon AWS or Subversion
510           repositories in which <a href="..."> is not used.
511
512       uversionmangle=rules
513           Normalize the candidate upstream version strings extracted from
514           hrefs in the source of the web page.  This is used as the version
515           sorting index when selecting the latest upstream version.
516
517           Substitution such as s/PRE/~pre/; s/RC/~rc/ may help.
518
519       versionmangle=rules
520           Syntactic shorthand for uversionmangle=rules, dversionmangle=rules
521
522       hrefdecode=percent-encoding
523           Convert the selected upstream tarball href string from the percent-
524           encoded hexadecimal string to the decoded normal URL string for
525           obfuscated web sites.  Only percent-encoding is available and it is
526           decoded with s/%([A-Fa-f\d]{2})/chr hex $1/eg.
527
528       downloadurlmangle=rules
529           Convert the selected upstream tarball href string into the
530           accessible URL for obfuscated web sites.  This is run after
531           hrefdecode.
532
533       filenamemangle=rules
534           Generate the upstream tarball filename from the selected href
535           string if matching-pattern can extract the latest upstream version
536           <uversion> from the selected href string.  Otherwise, generate the
537           upstream tarball filename from its full URL string and set the
538           missing <uversion> from the generated upstream tarball filename.
539
540           Without this option, the default upstream tarball filename is
541           generated by taking the last component of the URL and removing
542           everything after any '?' or '#'.
543
544       pgpsigurlmangle=rules
545           Generate the candidate upstream signature file URL string from the
546           upstream tarball URL.
547
548       oversionmangle=rules
549           Generate the version string <oversion> of the source tarball
550           <spkg>_<oversion>.orig.tar.gz from <uversion>.  This should be used
551           to add a suffix such as +dfsg1 to a MUT package.
552
553       Here, the mangling rules apply the rules to the pertinent string.
554       Multiple rules can be specified in a mangling rule string by making a
555       concatenated string of each mangling rule separated by ; (semicolon).
556
557       Each mangling rule cannot contain ; (semicolon), , (comma), or "
558       (double quote).
559
560       Each mangling rule behaves as if a Perl command "$string =~ rule" is
561       executed.  There are some notable details.
562
563rule may only use the s, tr, and y operations.
564
565           s/regex/replacement/options
566               Regex pattern match and replace the target string.  Only the g,
567               i and x flags are available.  Use the $1 syntax for back
568               references (No \1 syntax).  Code execution is not allowed (i.e.
569               no (?{}) or (??{}) constructs).
570
571           y/source/dest/ or tr/source/dest/
572               Transliterate the characters in the target string.
573

EXAMPLE OF EXECUTION

575       uscan reads the first entry in debian/changelog to determine the source
576       package name and the last upstream version.
577
578       For example, if the first entry of debian/changelog is:
579
580bar (3:2.03+dfsg1-4) unstable; urgency=low
581
582       then, the source package name is bar and the last Debian package
583       version is 3:2.03+dfsg1-4.
584
585       The last upstream version is normalized to 2.03+dfsg1 by removing the
586       epoch and the Debian revision.
587
588       If the dversionmangle rule exists, the last upstream version is further
589       normalized by applying this rule to it.  For example, if the last
590       upstream version is 2.03+dfsg1 indicating the source tarball is
591       repackaged, the suffix +dfsg1 is removed by the string substitution
592       s/\+dfsg\d*$// to make the (dversionmangled) last upstream version 2.03
593       and it is compared to the candidate upstream tarball versions such as
594       2.03, 2.04, ... found in the remote site.  Thus, set this rule as:
595
596opts="dversionmangle=s/\+dfsg\d*$//"
597
598       uscan downloads a web page from http://URL specified in debian/watch.
599
600       •   If the directory name part of URL has no parentheses, ( and ), it
601           is taken as verbatim.
602
603       •   If the directory name part of URL has parentheses, ( and ), then
604           uscan recursively searches all possible directories to find a page
605           for the newest version.  If the dirversionmangle rule exists, the
606           generated sorting index is used to find the newest version.  If a
607           specific version is specified for the download, the matching
608           version string has priority over the newest version.
609
610       For example, this http://URL may be specified as:
611
612http://www.example.org/([\d\.]+)/
613
614       Please note the trailing / in the above to make ([\d\.]+) as the
615       directory.
616
617       If the pagemangle rule exists, the whole downloaded web page as a
618       string is normalized by applying this rule to it.  This is very
619       powerful tool and needs to be used with caution.  If other mangling
620       rules can be used to address your objective, do not use this rule.
621
622       The downloaded web page is scanned for hrefs defined in the <a href="
623       ... "> tag to locate the candidate upstream tarball hrefs.  These
624       candidate upstream tarball hrefs are matched by the Perl regex pattern
625       matching-pattern such as DL-(?:[\d\.]+?)/foo-(.+)\.tar\.gz to narrow
626       down the candidates.  This pattern match needs to be anchored at the
627       beginning and the end.  For example, candidate hrefs may be:
628
629DL-2.02/foo-2.02.tar.gz
630
631DL-2.03/foo-2.03.tar.gz
632
633DL-2.04/foo-2.04.tar.gz
634
635       Here the matching string of (.+) in matching-pattern is considered as
636       the candidate upstream version.  If there are multiple matching strings
637       of capturing patterns in matching-pattern, they are all concatenated
638       with .  (period) to form the candidate upstream version.  Make sure to
639       use the non-capturing regex such as (?:[\d\.]+?) instead for the
640       variable text matching part unrelated to the version.
641
642       Then, the candidate upstream versions are:
643
6442.02
645
6462.03
647
6482.04
649
650       The downloaded tarball filename is basically set to the same as the
651       filename in the remote URL of the selected href.
652
653       If the uversionmangle rule exists, the candidate upstream versions are
654       normalized by applying this rule to them. (This rule may be useful if
655       the upstream version scheme doesn't sort correctly to identify the
656       newest version.)
657
658       The upstream tarball href corresponding to the newest (uversionmangled)
659       candidate upstream version newer than the (dversionmangled) last
660       upstream version is selected.
661
662       If multiple upstream tarball hrefs corresponding to a single version
663       with different extensions exist, the highest compression one is chosen.
664       (Priority: tar.xz > tar.lzma > tar.bz2 > tar.gz.)
665
666       If the selected upstream tarball href is the relative URL, it is
667       converted to the absolute URL using the base URL of the web page.  If
668       the <base href="  ...  "> tag exists in the web page, the selected
669       upstream tarball href is converted to the absolute URL using the
670       specified base URL in the base tag, instead.
671
672       If the downloadurlmangle rule exists, the selected upstream tarball
673       href is normalized by applying this rule to it. (This is useful for
674       some sites with the obfuscated download URL.)
675
676       If the filenamemangle rule exists, the downloaded tarball filename is
677       generated by applying this rule to the selected href if matching-
678       pattern can extract the latest upstream version <uversion> from the
679       selected href string. Otherwise, generate the upstream tarball filename
680       from its full URL string and set the missing <uversion> from the
681       generated upstream tarball filename.
682
683       Without the filenamemangle rule, the default upstream tarball filename
684       is generated by taking the last component of the URL and removing
685       everything after any '?' or '#'.
686
687       uscan downloads the selected upstream tarball to the parent ../
688       directory.  For example, the downloaded file may be:
689
690../foo-2.04.tar.gz
691
692       Let's call this downloaded version 2.04 in the above example
693       generically as <uversion> in the following.
694
695       If the pgpsigurlmangle rule exists, the upstream signature file URL is
696       generated by applying this rule to the (downloadurlmangled) selected
697       upstream tarball href and the signature file is tried to be downloaded
698       from it.
699
700       If the pgpsigurlmangle rule doesn't exist, uscan warns user if the
701       matching upstream signature file is available from the same URL with
702       their filename being suffixed by the 5 common suffix asc, gpg, pgp, sig
703       and sign. (You can avoid this warning by setting pgpmode=none.)
704
705       If the signature file is downloaded, the downloaded upstream tarball is
706       checked for its authenticity against the downloaded signature file
707       using the armored keyring debian/upstream/signing-key.asc  (see
708       "KEYRING FILE EXAMPLES").  If its signature is not valid, or not made
709       by one of the listed keys, uscan will report an error.
710
711       If the oversionmangle rule exists, the source tarball version oversion
712       is generated from the downloaded upstream version uversion by applying
713       this rule. This rule is useful to add suffix such as +dfsg1 to the
714       version of all the source packages of the MUT package for which the
715       repacksuffix mechanism doesn't work.
716
717       uscan invokes mk-origtargz to create the source tarball properly named
718       for the source package with .orig. (or .orig-<component>. for the
719       secondary tarballs) in its filename.
720
721       case A: packaging of the upstream tarball as is
722           mk-origtargz creates a symlink ../bar_<oversion>.orig.tar.gz linked
723           to the downloaded local upstream tarball. Here, bar is the source
724           package name found in debian/changelog. The generated symlink may
725           be:
726
727../bar_2.04.orig.tar.gz -> foo-2.04.tar.gz (as is)
728
729           Usually, there is no need to set up opts="dversionmangle= ... " for
730           this case.
731
732       case B: packaging of the upstream tarball after removing non-DFSG files
733           mk-origtargz checks the filename glob of the Files-Excluded stanza
734           in the first section of debian/copyright, removes matching files to
735           create a repacked upstream tarball.  Normally, the repacked
736           upstream tarball is renamed with suffix to
737           ../bar_<oversion><suffix>.orig.tar.gz using the repacksuffix option
738           for the single upstream package.    Here <oversion> is updated to
739           be <oversion><suffix>.
740
741           The removal of files is required if files are not DFSG-compliant.
742           For such case, +dfsg1 is used as suffix.
743
744           So the combined options are set as
745           opts="dversionmangle=s/\+dfsg\d*$// ,repacksuffix=+dfsg1", instead.
746
747           For example, the repacked upstream tarball may be:
748
749../bar_2.04+dfsg1.orig.tar.gz (repackaged)
750
751       uscan normally invokes "uupdate --find --upstream-version oversion "
752       for the version=4 watch file.
753
754       Please note that --find option is used here since mk-origtargz has been
755       invoked to make *.orig.tar.gz file already.  uscan picks bar from
756       debian/changelog.
757
758       It creates the new upstream source tree under the ../bar-<oversion>
759       directory and Debianize it leveraging the last package contents.
760

WATCH FILE EXAMPLES

762       When writing the watch file, you should rely on the latest upstream
763       source announcement web page.  You should not try to second guess the
764       upstream archive structure if possible.  Here are the typical
765       debian/watch files.
766
767       Please note that executing uscan with -v or -vv reveals what exactly
768       happens internally.
769
770       The existence and non-existence of a space the before tailing \ (back
771       slash) are significant.
772
773       Some undocumented shorter configuration strings are used in the below
774       EXAMPLES to help you with typing.  These are intentional ones.  uscan
775       is written to accept such common sense abbreviations but don't push the
776       limit.
777
778   HTTP site (basic)
779       Here is an example for the basic single upstream tarball.
780
781         version=4
782         http://example.com/~user/release/foo.html \
783             files/foo-([\d\.]+)\.tar\.gz debian uupdate
784
785       Or using the special strings:
786
787         version=4
788         http://example.com/~user/release/@PACKAGE@.html \
789             files/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian uupdate
790
791       For the upstream source package foo-2.0.tar.gz, this watch file
792       downloads and creates the Debian orig.tar file foo_2.0.orig.tar.gz.
793
794   HTTP site (pgpsigurlmangle)
795       Here is an example for the basic single upstream tarball with the
796       matching signature file in the same file path.
797
798         version=4
799         opts="pgpsigurlmangle=s%$%.asc%" http://example.com/release/@PACKAGE@.html \
800             files/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian uupdate
801
802       For the upstream source package foo-2.0.tar.gz and the upstream
803       signature file foo-2.0.tar.gz.asc, this watch file downloads these
804       files, verifies the authenticity using the keyring
805       debian/upstream/signing-key.asc and creates the Debian orig.tar file
806       foo_2.0.orig.tar.gz.
807
808       Here is another example for the basic single upstream tarball with the
809       matching signature file on decompressed tarball in the same file path.
810
811         version=4
812         opts="pgpsigurlmangle=s%@ARCHIVE_EXT@$%.asc%,decompress" \
813             http://example.com/release/@PACKAGE@.html \
814             files/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian uupdate
815
816       For the upstream source package foo-2.0.tar.gz and the upstream
817       signature file foo-2.0.tar.asc, this watch file downloads these files,
818       verifies the authenticity using the keyring
819       debian/upstream/signing-key.asc and creates the Debian orig.tar file
820       foo_2.0.orig.tar.gz.
821
822   HTTP site (pgpmode=next/previous)
823       Here is an example for the basic single upstream tarball with the
824       matching signature file in the unrelated file path.
825
826         version=4
827         opts="pgpmode=next" http://example.com/release/@PACKAGE@.html \
828             files/(?:\d+)/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian
829         opts="pgpmode=previous" http://example.com/release/@PACKAGE@.html \
830             files/(?:\d+)/@PACKAGE@@ANY_VERSION@@SIGNATURE_EXT@ previous uupdate
831
832       (?:\d+) part can be any random value.  The tarball file can have 53,
833       while the signature file can have 33.
834
835       ([\d\.]+) part for the signature file has a strict requirement to match
836       that for the upstream tarball specified in the previous line by having
837       previous as version in the watch line.
838
839   HTTP site (flexible)
840       Here is an example for the maximum flexibility of upstream tarball and
841       signature file extensions.
842
843         version=4
844         opts="pgpmode=next" http://example.com/DL/ \
845             files/(?:\d+)/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian
846         opts="pgpmode=previous" http://example.com/DL/ \
847             files/(?:\d+)/@PACKAGE@@ANY_VERSION@@SIGNATURE_EXT@ \
848             previous uupdate
849
850   HTTP site (basic MUT)
851       Here is an example for the basic multiple upstream tarballs.
852
853         version=4
854         opts="pgpsigurlmangle=s%$%.sig%" \
855             http://example.com/release/foo.html \
856             files/foo-([\d\.]+)\.tar\.gz debian
857         opts="pgpsigurlmangle=s%$%.sig%, component=bar" \
858             http://example.com/release/foo.html \
859             files/foobar-([\d\.]+)\.tar\.gz same
860         opts="pgpsigurlmangle=s%$%.sig%, component=baz" \
861             http://example.com/release/foo.html \
862             files/foobaz-([\d\.]+)\.tar\.gz same uupdate
863
864       For the main upstream source package foo-2.0.tar.gz and the secondary
865       upstream source packages foobar-2.0.tar.gz and foobaz-2.0.tar.gz which
866       install under bar/ and baz/, this watch file downloads and creates the
867       Debian orig.tar file foo_2.0.orig.tar.gz, foo_2.0.orig-bar.tar.gz and
868       foo_2.0.orig-baz.tar.gz.  Also, these upstream tarballs are verified by
869       their signature files.
870
871   HTTP site (recursive directory scanning)
872       Here is an example with the recursive directory scanning for the
873       upstream tarball and its signature files released in a directory named
874       after their version.
875
876         version=4
877         opts="pgpsigurlmangle=s%$%.sig%, dirversionmangle=s/-PRE/~pre/;s/-RC/~rc/" \
878             http://tmrc.mit.edu/mirror/twisted/Twisted/([\d+\.]+)/ \
879             Twisted-([\d\.]+)\.tar\.xz debian uupdate
880
881       Here, the web site should be accessible at the following URL:
882
883         http://tmrc.mit.edu/mirror/twisted/Twisted/
884
885       Here, dirversionmangle option is used to normalize the sorting order of
886       the directory names.
887
888   HTTP site (alternative shorthand)
889       For the bare HTTP site where you can directly see archive filenames,
890       the normal watch file:
891
892         version=4
893         opts="pgpsigurlmangle=s%$%.sig%" \
894             http://www.cpan.org/modules/by-module/Text/ \
895             Text-CSV_XS-(.+)\.tar\.gz \
896             debian uupdate
897
898       can be rewritten in an alternative shorthand form only with a single
899       string covering URL and filename:
900
901         version=4
902         opts="pgpsigurlmangle=s%$%.sig%" \
903             http://www.cpan.org/modules/by-module/Text/Text-CSV_XS-(.+)\.tar\.gz \
904             debian uupdate
905
906       In version=4, initial white spaces are dropped.  Thus, this alternative
907       shorthand form can also be written as:
908
909         version=4
910         opts="pgpsigurlmangle=s%$%.sig%" \
911             http://www.cpan.org/modules/by-module/Text/\
912             Text-CSV_XS-(.+)\.tar\.gz \
913             debian uupdate
914
915       Please note the subtle difference of a space before the tailing \
916       between the first and the last examples.
917
918   HTTP site (funny version)
919       For a site which has funny version numbers, the parenthesized groups
920       will be joined with . (period) to make a sanitized version number.
921
922         version=4
923         http://www.site.com/pub/foobar/foobar_v(\d+)_(\d+)\.tar\.gz \
924         debian uupdate
925
926   HTTP site (DFSG)
927       The upstream part of the Debian version number can be mangled to
928       indicate the source package was repackaged to clean up non-DFSG files:
929
930         version=4
931         opts="dversionmangle=s/\+dfsg\d*$//,repacksuffix=+dfsg1" \
932         http://some.site.org/some/path/foobar-(.+)\.tar\.gz debian uupdate
933
934       See "COPYRIGHT FILE EXAMPLES".
935
936   HTTP site (filenamemangle)
937       The upstream tarball filename is found by taking the last component of
938       the URL and removing everything after any '?' or '#'.
939
940       If this does not fit to you, use filenamemangle.  For example, <A
941       href="http://foo.bar.org/dl/?path=&dl=foo-0.1.1.tar.gz"> could be
942       handled as:
943
944         version=4
945         opts=filenamemangle=s/.*=(.*)/$1/ \
946         http://foo.bar.org/dl/\?path=&dl=foo-(.+)\.tar\.gz \
947         debian uupdate
948
949       <A href="http://foo.bar.org/dl/?path=&dl_version=0.1.1"> could be
950       handled as:
951
952         version=4
953         opts=filenamemangle=s/.*=(.*)/foo-$1\.tar\.gz/ \
954         http://foo.bar.org/dl/\?path=&dl_version=(.+) \
955         debian uupdate
956
957       If the href string has no version using <I>matching-pattern>, the
958       version can be obtained from the full URL using filenamemangle.
959
960         version=4
961         opts=filenamemangle=s&.*/dl/(.*)/foo\.tar\.gz&foo-$1\.tar\.gz& \
962         http://foo.bar.org/dl/([\.\d]+)/ foo.tar.gz \
963         debian uupdate
964
965   HTTP site (downloadurlmangle)
966       The option downloadurlmangle can be used to mangle the URL of the file
967       to download.  This can only be used with http:// URLs.  This may be
968       necessary if the link given on the web page needs to be transformed in
969       some way into one which will work automatically, for example:
970
971         version=4
972         opts=downloadurlmangle=s/prdownload/download/ \
973         http://developer.berlios.de/project/showfiles.php?group_id=2051 \
974         http://prdownload.berlios.de/softdevice/vdr-softdevice-(.+).tgz \
975         debian uupdate
976
977   HTTP site (oversionmangle, MUT)
978       The option oversionmangle can be used to mangle the version of the
979       source tarball (.orig.tar.gz and .orig-bar.tar.gz).  For example,
980       +dfsg1 can be added to the upstream version as:
981
982         version=4
983         opts=oversionmangle=s/(.*)/$1+dfsg1/ \
984         http://example.com/~user/release/foo.html \
985         files/foo-([\d\.]*).tar.gz debian
986         opts="component=bar" \
987         http://example.com/~user/release/foo.html \
988         files/bar-([\d\.]*).tar.gz same uupdate
989
990       See "COPYRIGHT FILE EXAMPLES".
991
992   HTTP site (pagemangle)
993       The option pagemangle can be used to mangle the downloaded web page
994       before applying other rules.  The non-standard web page without proper
995       <a href=" << ... >> "> entries can be converted.  For example, if
996       foo.html uses <a bogus=" ... ">, this can be converted to the standard
997       page format with:
998
999         version=4
1000         opts=pagemangle="s/<a\s+bogus=/<a href=/g" \
1001         http://example.com/release/foo.html \
1002         files/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian uupdate
1003
1004       Please note the use of g here to replace all occurrences.
1005
1006       If foo.html uses <Key> ... </Key>, this can be converted to the
1007       standard page format with:
1008
1009         version=4
1010         opts="pagemangle=s%<Key>([^<]*)</Key>%<Key><a href="$1">$1</a></Key>%g" \
1011         http://example.com/release/foo.html \
1012         (?:.*)/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian uupdate
1013
1014   FTP site (basic):
1015         version=4
1016         ftp://ftp.tex.ac.uk/tex-archive/web/c_cpp/cweb/cweb-(.+)\.tar\.gz \
1017         debian uupdate
1018
1019   FTP site (regex special characters):
1020         version=4
1021         ftp://ftp.worldforge.org/pub/worldforge/libs/\
1022         Atlas-C++/transitional/Atlas-C\+\+-(.+)\.tar\.gz debian uupdate
1023
1024       Please note that this URL is connected to be  ... libs/Atlas-C++/ ...
1025       . For ++, the first one in the directory path is verbatim while the one
1026       in the filename is escaped by \.
1027
1028   FTP site (funny version)
1029       This is another way of handling site with funny version numbers, this
1030       time using mangling.  (Note that multiple groups will be concatenated
1031       before mangling is performed, and that mangling will only be performed
1032       on the basename version number, not any path version numbers.)
1033
1034         version=4
1035         opts="uversionmangle=s/^/0.0./" \
1036         ftp://ftp.ibiblio.org/pub/Linux/ALPHA/wine/\
1037         development/Wine-(.+)\.tar\.gz debian uupdate
1038
1039   sf.net
1040       For SourceForge based projects, qa.debian.org runs a redirector which
1041       allows a simpler form of URL. The format below will automatically be
1042       rewritten to use the redirector with the watch file:
1043
1044         version=4
1045         https://sf.net/<project>/ <tar-name>-(.+)\.tar\.gz debian uupdate
1046
1047       For audacity, set the watch file as:
1048
1049         version=4
1050         https://sf.net/audacity/ audacity-minsrc-(.+)\.tar\.gz debian uupdate
1051
1052       Please note, you can still use normal functionalities of uscan to set
1053       up a watch file for this site without using the redirector.
1054
1055         version=4
1056         opts="uversionmangle=s/-pre/~pre/, \
1057               filenamemangle=s%(?:.*)audacity-minsrc-(.+)\.tar\.xz/download%\
1058                                audacity-$1.tar.xz%" \
1059               http://sourceforge.net/projects/audacity/files/audacity/(\d[\d\.]+)/ \
1060               (?:.*)audacity-minsrc-([\d\.]+)\.tar\.xz/download debian uupdate
1061
1062       Here, % is used as the separator instead of the standard /.
1063
1064   github.com
1065       For GitHub based projects, you can use the tags or releases page.  The
1066       archive URL uses only the version as the filename.  You can rename the
1067       downloaded upstream tarball from into the standard
1068       <project>-<version>.tar.gz using filenamemangle:
1069
1070         version=4
1071         opts="filenamemangle=s%(?:.*?)?v?(\d[\d.]*)\.tar\.gz%@PACKAGE@-$1.tar.gz%" \
1072             https://github.com/<user>/<project>/tags \
1073             (?:.*?/)?v?(\d[\d.]*)\.tar\.gz debian uupdate
1074
1075   PyPI
1076       For PyPI based projects, pypi.debian.net runs a redirector which allows
1077       a simpler form of URL. The format below will automatically be rewritten
1078       to use the redirector with the watch file:
1079
1080         version=4
1081         https://pypi.python.org/packages/source/<initial>/<project>/ \
1082             <tar-name>-(.+)\.tar\.gz debian uupdate
1083
1084       For cfn-sphere, set the watch file as:
1085
1086         version=4
1087         https://pypi.python.org/packages/source/c/cfn-sphere/ \
1088             cfn-sphere-([\d\.]+).tar.gz debian uupdate
1089
1090       Please note, you can still use normal functionalities of uscan to set
1091       up a watch file for this site without using the redirector.
1092
1093         version=4
1094         opts="pgpmode=none" \
1095             https://pypi.python.org/pypi/cfn-sphere/ \
1096             https://pypi.python.org/packages/.*/.*/.*/\
1097             cfn-sphere-([\d\.]+).tar.gz#.* debian uupdate
1098
1099   code.google.com
1100       Sites which used to be hosted on the Google Code service should have
1101       migrated to elsewhere (github?).  Please look for the newer upstream
1102       site if available.
1103
1104   npmjs.org (node modules)
1105       npmjs.org modules are published in JSON files. Here is a way to read
1106       them:
1107
1108         version=4
1109         opts="searchmode=plain" \
1110          https://registry.npmjs.org/aes-js \
1111          https://registry.npmjs.org/aes-js/-/aes-js-(\d[\d\.]*)@ARCHIVE_EXT@
1112
1113   grouped package
1114       Some node modules are split into multiple little upstream package. Here
1115       is a way to group them:
1116
1117         version=4
1118         opts="searchmode=plain,pgpmode=none" \
1119           https://registry.npmjs.org/mongodb \
1120           https://registry.npmjs.org/mongodb/-/mongodb-(\d[\d\.]*)@ARCHIVE_EXT@ group
1121         opts="searchmode=plain,pgpmode=none,component=bson" \
1122           https://registry.npmjs.org/bson \
1123           https://registry.npmjs.org/bson/-/bson-(\d[\d\.]*)@ARCHIVE_EXT@ group
1124         opts="searchmode=plain,pgpmode=none,component=mongodb-core" \
1125           https://registry.npmjs.org/mongodb-core \
1126           https://registry.npmjs.org/mongodb-core/-/mongodb-core-(\d[\d\.]*)@ARCHIVE_EXT@ group
1127         opts="searchmode=plain,pgpmode=none,component=requireoptional" \
1128           https://registry.npmjs.org/require_optional \
1129           https://registry.npmjs.org/require_optional/-/require_optional-(\d[\d\.]*)@ARCHIVE_EXT@ group
1130
1131       Package version is then the concatenation of upstream versions
1132       separated by "+~".
1133
1134       To avoid having a too long version, the "checksum" method can be used.
1135       In this case, the main source has to be declared as "group":
1136
1137         version=4
1138         opts="searchmode=plain,pgpmode=none" \
1139           https://registry.npmjs.org/mongodb \
1140           https://registry.npmjs.org/mongodb/-/mongodb-(\d[\d\.]*)@ARCHIVE_EXT@ group
1141         opts="searchmode=plain,pgpmode=none,component=bson" \
1142           https://registry.npmjs.org/bson \
1143           https://registry.npmjs.org/bson/-/bson-(\d[\d\.]*)@ARCHIVE_EXT@ checksum
1144         opts="searchmode=plain,pgpmode=none,component=mongodb-core" \
1145           https://registry.npmjs.org/mongodb-core \
1146           https://registry.npmjs.org/mongodb-core/-/mongodb-core-(\d[\d\.]*)@ARCHIVE_EXT@ checksum
1147         opts="searchmode=plain,pgpmode=none,component=requireoptional" \
1148           https://registry.npmjs.org/require_optional \
1149           https://registry.npmjs.org/require_optional/-/require_optional-(\d[\d\.]*)@ARCHIVE_EXT@ checksum
1150
1151       The "checksum" is made up of the separate sum of each number composing
1152       the component versions.  Following is an example with 3 components
1153       whose versions are "1.2.4", "2.0.1" and "10.0", with the main tarball
1154       having version "2.0.6":
1155
1156         Main: 2.0.6
1157         Comp1:         1 .     2 .     4
1158         Comp2:         2 .     0 .     1
1159         Comp3:        10 .     0
1160         ================================
1161         Result  : 1+2+10 . 2+0+0 .   4+1
1162         Checksum:     13 .     2 .     5
1163         ================================
1164         Final Version:   2.0.6+~cs13.2.5
1165
1166       uscan will also display the original version string before being
1167       encoded into the checksum, which can for example be used in a
1168       debian/changelog entry to easily follow the changes:
1169
1170         2.0.6+~1.2.4+~2.0.1+~10.0
1171
1172       Note: This feature currently accepts only versions composed of digits
1173       and full stops (`.`).
1174
1175   direct access to the git repository (tags)
1176       If the upstream only publishes its code via the git repository and its
1177       code has no web interface to obtain the release tarball, you can use
1178       uscan with the tags of the git repository to track and package the new
1179       upstream release.
1180
1181         version=4
1182         opts="mode=git, gitmode=full, pgpmode=none" \
1183         http://git.ao2.it/tweeper.git \
1184         refs/tags/v([\d\.]+) debian uupdate
1185
1186       Please note "git ls-remote" is used to obtain references for tags.
1187
1188       If a tag v20.5 is the newest tag, the above example downloads
1189       spkg-20.5.tar.xz after making a full clone of the git repository which
1190       is needed for dumb git server.
1191
1192       If tags are signed, set pgpmode=gittag to verify them.
1193
1194   direct access to the git repository (HEAD)
1195       If the upstream only publishes its code via the git repository and its
1196       code has no web interface nor the tags to obtain the released tarball,
1197       you can use uscan with the HEAD of the git repository to track and
1198       package the new upstream release with an automatically generated
1199       version string.
1200
1201         version=4
1202         opts="mode=git, pgpmode=none" \
1203         https://github.com/Debian/dh-make-golang \
1204         HEAD debian uupdate
1205
1206       Please note that a local shallow copy of the git repository is made
1207       with "git clone --bare --depth=1 ..." normally in the target directory.
1208       uscan generates the new upstream version with "git log
1209       --date=format:%Y%m%d --pretty=0.0~git%cd.%h" on this local copy of
1210       repository as its default behavior.
1211
1212       The generation of the upstream version string may the adjusted to your
1213       taste by adding pretty and date options to the opts arguments.
1214
1215   direct access to the Subversion repository (tags)
1216       If the upstream only publishes its code via the Subversion repository
1217       and its code has no web interface to obtain the release tarball, you
1218       can use uscan with the tags of the Subversion repository to track and
1219       package the new upstream release.
1220
1221         version=4
1222         opts="mode=svn, pgpmode=none" \
1223         svn://svn.code.sf.net/p/jmol/code/tags/ \
1224         ([\d.]+)\/ debian uupdate
1225
1226   direct access to the Subversion repository (HEAD)
1227       If the upstream only publishes its code via the Subversion repository
1228       and its code has no web interface to obtain the release tarball, you
1229       can use uscan to get the most recent source of a subtree in the
1230       repository with an automatically generated version string.
1231
1232         version=4
1233         opts="mode=svn, pgpmode=none" \
1234         svn://svn.code.sf.net/p/jmol/code/trunk/ \
1235         HEAD debian uupdate
1236
1237       By default, uscan generates the new upstream version by appending the
1238       revision number to "0.0~svn". This can later be changed using
1239       uversionmangle.
1240
1242       Here is an example for the debian/copyright file which initiates
1243       automatic repackaging of the upstream tarball into
1244       <spkg>_<oversion>.orig.tar.gz (In debian/copyright, the Files-Excluded
1245       and Files-Excluded-component stanzas are a part of the first paragraph
1246       and there is a blank line before the following paragraphs which contain
1247       Files and other stanzas.):
1248
1249         Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
1250         Files-Excluded: exclude-this
1251          exclude-dir
1252          */exclude-dir
1253          .*
1254          */js/jquery.js
1255
1256          Files: *
1257          Copyright: ...
1258          ...
1259
1260       Here is another example for the debian/copyright file which initiates
1261       automatic repackaging of the multiple upstream tarballs into
1262       <spkg>_<oversion>.orig.tar.gz and <spkg>_<oversion>.orig-bar.tar.gz:
1263
1264         Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
1265         Files-Excluded: exclude-this
1266          exclude-dir
1267          */exclude-dir
1268          .*
1269          */js/jquery.js
1270         Files-Excluded-bar: exclude-this
1271          exclude-dir
1272          */exclude-dir
1273          .*
1274          */js/jquery.js
1275
1276          Files: *
1277          Copyright: ...
1278          ...
1279
1280       See mk-origtargz(1).
1281

KEYRING FILE EXAMPLES

1283       Let's assume that the upstream "uscan test key (no secret)
1284       <none@debian.org>" signs its package with a secret OpenPGP key and
1285       publishes the corresponding public OpenPGP key.  This public OpenPGP
1286       key can be identified in 3 ways using the hexadecimal form.
1287
1288       •   The fingerprint as the 20 byte data calculated from the public
1289           OpenPGP key. E.  g., 'CF21 8F0E 7EAB F584 B7E2 0402 C77E 2D68 7254
1290           3FAF'
1291
1292       •   The long keyid as the last 8 byte data of the fingerprint. E. g.,
1293           'C77E2D6872543FAF'
1294
1295       •   The short keyid is the last 4 byte data of the fingerprint. E. g.,
1296           '72543FAF'
1297
1298       Considering the existence of the collision attack on the short keyid,
1299       the use of the long keyid is recommended for receiving keys from the
1300       public key servers.  You must verify the downloaded OpenPGP key using
1301       its full fingerprint value which you know is the trusted one.
1302
1303       The armored keyring file debian/upstream/signing-key.asc can be created
1304       by using the gpg (or gpg2) command as follows.
1305
1306         $ gpg --recv-keys "C77E2D6872543FAF"
1307         ...
1308         $ gpg --finger "C77E2D6872543FAF"
1309         pub   4096R/72543FAF 2015-09-02
1310               Key fingerprint = CF21 8F0E 7EAB F584 B7E2  0402 C77E 2D68 7254 3FAF
1311         uid                  uscan test key (no secret) <none@debian.org>
1312         sub   4096R/52C6ED39 2015-09-02
1313         $ cd path/to/<upkg>-<uversion>
1314         $ mkdir -p debian/upstream
1315         $ gpg --export --export-options export-minimal --armor \
1316               'CF21 8F0E 7EAB F584 B7E2  0402 C77E 2D68 7254 3FAF' \
1317               >debian/upstream/signing-key.asc
1318
1319       The binary keyring files, debian/upstream/signing-key.pgp and
1320       debian/upstream-signing-key.pgp, are still supported but deprecated.
1321
1322       If a group of developers sign the package, you need to list
1323       fingerprints of all of them in the argument for gpg --export ... to
1324       make the keyring to contain all OpenPGP keys of them.
1325
1326       Sometimes you may wonder who made a signature file.  You can get the
1327       public keyid used to create the detached signature file
1328       foo-2.0.tar.gz.asc by running gpg as:
1329
1330         $ gpg -vv foo-2.0.tar.gz.asc
1331         gpg: armor: BEGIN PGP SIGNATURE
1332         gpg: armor header: Version: GnuPG v1
1333         :signature packet: algo 1, keyid C77E2D6872543FAF
1334               version 4, created 1445177469, md5len 0, sigclass 0x00
1335               digest algo 2, begin of digest 7a c7
1336               hashed subpkt 2 len 4 (sig created 2015-10-18)
1337               subpkt 16 len 8 (issuer key ID C77E2D6872543FAF)
1338               data: [4091 bits]
1339         gpg: assuming signed data in `foo-2.0.tar.gz'
1340         gpg: Signature made Sun 18 Oct 2015 11:11:09 PM JST using RSA key ID 72543FAF
1341         ...
1342

COMMANDLINE OPTIONS

1344       For the basic usage, uscan does not require to set these options.
1345
1346       --conffile, --conf-file
1347           Add or replace default configuration files ("/etc/devscripts.conf"
1348           and "~/.devscripts"). This can only be used as the first option
1349           given on the command-line.
1350
1351           replace:
1352                 uscan --conf-file test.conf --verbose
1353
1354           add:
1355                 uscan --conf-file +test.conf --verbose
1356
1357               If one --conf-file has no "+", default configuration files are
1358               ignored.
1359
1360       --no-conf, --noconf
1361           Don't read any configuration files. This can only be used as the
1362           first option given on the command-line.
1363
1364       --no-verbose
1365           Don't report verbose information. (default)
1366
1367       --verbose, -v
1368           Report verbose information.
1369
1370       --debug, -vv
1371           Report verbose information and some internal state values.
1372
1373       --extra-debug, -vvv
1374           Report verbose information including the downloaded web pages as
1375           processed to STDERR for debugging.
1376
1377       --dehs
1378           Send DEHS style output (XML-type) to STDOUT, while send all other
1379           uscan output to STDERR.
1380
1381       --no-dehs
1382           Use only traditional uscan output format. (default)
1383
1384       --download, -d
1385           Download the new upstream release. (default)
1386
1387       --force-download, -dd
1388           Download the new upstream release even if up-to-date. (may not
1389           overwrite the local file)
1390
1391       --overwrite-download, -ddd
1392           Download the new upstream release even if up-to-date. (may
1393           overwrite the local file)
1394
1395       --no-download, --nodownload
1396           Don't download and report information.
1397
1398           Previously downloaded tarballs may be used.
1399
1400           Change default to --skip-signature.
1401
1402       --signature
1403           Download signature. (default)
1404
1405       --no-signature
1406           Don't download signature but verify if already downloaded.
1407
1408       --skip-signature
1409           Don't bother download signature nor verifying signature.
1410
1411       --safe, --report
1412           Avoid running unsafe scripts by skipping both the repacking of the
1413           downloaded package and the updating of the new source tree.
1414
1415           Change default to --no-download and --skip-signature.
1416
1417           When the objective of running uscan is to gather the upstream
1418           package status under the security conscious environment, please
1419           make sure to use this option.
1420
1421       --report-status
1422           This is equivalent of setting "--verbose --safe".
1423
1424       --download-version version
1425           Specify the version which the upstream release must match in order
1426           to be considered, rather than using the release with the highest
1427           version.  (a best effort feature)
1428
1429       --download-debversion version
1430           Specify the Debian package version to download the corresponding
1431           upstream release version.  The dversionmangle and uversionmangle
1432           rules are considered.  (a best effort feature)
1433
1434       --download-current-version
1435           Download the currently packaged version.  (a best effort feature)
1436
1437       --check-dirname-level N
1438           See the below section "Directory name checking" for an explanation
1439           of this option.
1440
1441       --check-dirname-regex regex
1442           See the below section "Directory name checking" for an explanation
1443           of this option.
1444
1445       --destdir path Normally, uscan changes its internal current directory
1446       to the package's source directory where the debian/ is located.  Then
1447       the destination directory for the downloaded tarball and other files is
1448       set to the parent directory ../ from this internal current directory.
1449           This default destination directory can be overridden by setting
1450           --destdir option to a particular path.  If this path is a relative
1451           path, the destination directory is determined in relative to the
1452           internal current directory of uscan execution. If this path is a
1453           absolute path, the destination directory is set to path
1454           irrespective of the internal current directory of uscan execution.
1455
1456           The above is true not only for the simple uscan run in the single
1457           source tree but also for the advanced scanning uscan run with
1458           subdirectories holding multiple source trees.
1459
1460           One exception is when --watchfile and --package are used together.
1461           For this case, the internal current directory of uscan execution
1462           and the default destination directory are set to the current
1463           directory . where uscan is started.  The default destination
1464           directory can be overridden by setting --destdir option as well.
1465
1466       --package package
1467           Specify the name of the package to check for rather than examining
1468           debian/changelog; this requires the --upstream-version (unless a
1469           version is specified in the watch file) and --watchfile options as
1470           well.  Furthermore, no directory scanning will be done and nothing
1471           will be downloaded.  This option automatically sets --no-download
1472           and --skip-signature; and probably most useful in conjunction with
1473           the DEHS system (and --dehs).
1474
1475       --upstream-version upstream-version
1476           Specify the current upstream version rather than examine
1477           debian/watch or debian/changelog to determine it. This is ignored
1478           if a directory scan is being performed and more than one
1479           debian/watch file is found.
1480
1481       --watchfile watchfile
1482           Specify the watchfile rather than perform a directory scan to
1483           determine it.  If this option is used without --package, then uscan
1484           must be called from within the Debian package source tree (so that
1485           debian/changelog can be found simply by stepping up through the
1486           tree).
1487
1488           One exception is when --watchfile and --package are used together.
1489           uscan can be called from anywhare and the internal current
1490           directory of uscan execution and the default destination directory
1491           are set to the current directory . where uscan is started.
1492
1493           See more in the --destdir explanation.
1494
1495       --bare
1496           Disable all site specific special case codes to perform URL
1497           redirections and page content alterations.
1498
1499       --http-header
1500           Add specified header in HTTP requests for matching url. This option
1501           can be used more than one time, values must be in the form
1502           "baseUrl@Name=value. Example:
1503
1504             uscan --http-header https://example.org@My-Token=qwertyuiop
1505
1506           Security:
1507
1508           The given baseUrl must exactly match the base url before '/'.
1509           Examples:
1510                 |        --http-header value         |           Good for          | Never used |
1511                 +------------------------------------+-----------------------------+------------+
1512                 | https://example.org.com@Hdr=Value  | https://example.org.com/... |            |
1513                 | https://example.org.com/@Hdr=Value |                             |     X      |
1514                 | https://e.com:1879@Hdr=Value       | https://e.com:1879/...      |            |
1515                 | https://e.com:1879/dir@Hdr=Value   | https://e.com:1879/dir/...  |            |
1516                 | https://e.com:1879/dir/@Hdr=Value  |                             |     X      |
1517
1518           It is strongly recommended to not use this feature to pass a secret
1519           token over unciphered connection (http://)
1520           You can use "USCAN_HTTP_HEADER" variable (in "~/.devscripts") to
1521           hide secret token from scripts
1522       --no-exclusion
1523           Don't automatically exclude files mentioned in debian/copyright
1524           field Files-Excluded.
1525
1526       --pasv
1527           Force PASV mode for FTP connections.
1528
1529       --no-pasv
1530           Don't use PASV mode for FTP connections.
1531
1532       --no-symlink
1533           Don't rename nor repack upstream tarball.
1534
1535       --timeout N
1536           Set timeout to N seconds (default 20 seconds).
1537
1538       --user-agent, --useragent
1539           Override the default user agent header.
1540
1541       --help
1542           Give brief usage information.
1543
1544       --version
1545           Display version information.
1546
1547       uscan also accepts following options and passes them to mk-origtargz:
1548
1549       --symlink
1550           Make orig.tar.gz (with the appropriate extension) symlink to the
1551           downloaded files. (This is the default behavior.)
1552
1553       --copy
1554           Instead of symlinking as described above, copy the downloaded
1555           files.
1556
1557       --rename
1558           Instead of symlinking as described above, rename the downloaded
1559           files.
1560
1561       --repack
1562           After having downloaded an lzma tar, xz tar, bzip tar, gz tar, zip,
1563           jar, xpi archive, repack it to the specified compression (see
1564           --compression).
1565
1566           The unzip package must be installed in order to repack zip and jar
1567           archives, the mozilla-devscripts package must be installed to
1568           repack xpi archives, and the xz-utils package must be installed to
1569           repack lzma or xz tar archives.
1570
1571       --compression [ gzip | bzip2 | lzma | xz ]
1572           In the case where the upstream sources are repacked (either because
1573           --repack option is given or debian/copyright contains the field
1574           Files-Excluded), it is possible to control the compression method
1575           via the parameter.  The default is gzip for normal tarballs, and xz
1576           for tarballs generated directly from the git repository.
1577
1578       --copyright-file copyright-file
1579           Exclude files mentioned in Files-Excluded in the given copyright-
1580           file.  This is useful when running uscan not within a source
1581           package directory.
1582

DEVSCRIPT CONFIGURATION VARIABLES

1584       For the basic usage, uscan does not require to set these configuration
1585       variables.
1586
1587       The two configuration files /etc/devscripts.conf and ~/.devscripts are
1588       sourced by a shell in that order to set configuration variables. These
1589       may be overridden by command line options. Environment variable
1590       settings are ignored for this purpose. If the first command line option
1591       given is --noconf, then these files will not be read. The currently
1592       recognized variables are:
1593
1594       USCAN_DOWNLOAD
1595           Download or report only:
1596
1597           no: equivalent to --no-download, newer upstream files will not be
1598           downloaded.
1599           yes: equivalent to --download, newer upstream files will be
1600           downloaded. This is the default behavior.
1601               See also --force-download and --overwrite-download.
1602
1603       USCAN_SAFE
1604           If this is set to yes, then uscan avoids running unsafe scripts by
1605           skipping both the repacking of the downloaded package and the
1606           updating of the new source tree; this is equivalent to the --safe
1607           options; this also sets the default to --no-download and
1608           --skip-signature.
1609
1610       USCAN_PASV
1611           If this is set to yes or no, this will force FTP connections to use
1612           PASV mode or not to, respectively. If this is set to default, then
1613           Net::FTP(3) makes the choice (primarily based on the FTP_PASSIVE
1614           environment variable).
1615
1616       USCAN_TIMEOUT
1617           If set to a number N, then set the timeout to N seconds. This is
1618           equivalent to the --timeout option.
1619
1620       USCAN_SYMLINK
1621           If this is set to no, then a pkg_version.orig.tar.{gz|bz2|lzma|xz}
1622           symlink will not be made (equivalent to the --no-symlink option).
1623           If it is set to yes or symlink, then the symlinks will be made. If
1624           it is set to rename, then the files are renamed (equivalent to the
1625           --rename option).
1626
1627       USCAN_DEHS_OUTPUT
1628           If this is set to yes, then DEHS-style output will be used. This is
1629           equivalent to the --dehs option.
1630
1631       USCAN_VERBOSE
1632           If this is set to yes, then verbose output will be given.  This is
1633           equivalent to the --verbose option.
1634
1635       USCAN_USER_AGENT
1636           If set, the specified user agent string will be used in place of
1637           the default.  This is equivalent to the --user-agent option.
1638
1639       USCAN_DESTDIR
1640           If set, the downloaded files will be placed in this  directory.
1641           This is equivalent to the --destdir option.
1642
1643       USCAN_REPACK
1644           If this is set to yes, then after having downloaded a bzip tar,
1645           lzma tar, xz tar, or zip archive, uscan will repack it to the
1646           specified compression (see --compression). This is equivalent to
1647           the --repack option.
1648
1649       USCAN_EXCLUSION
1650           If this is set to no, files mentioned in the field Files-Excluded
1651           of debian/copyright will be ignored and no exclusion of files will
1652           be tried.  This is equivalent to the --no-exclusion option.
1653
1654       USCAN_HTTP_HEADER
1655           If set, the specified http header will be used if URL match. This
1656           is equivalent to --http-header option.
1657

EXIT STATUS

1659       The exit status gives some indication of whether a newer version was
1660       found or not; one is advised to read the output to determine exactly
1661       what happened and whether there were any warnings to be noted.
1662
1663       0   Either --help or --version was used, or for some watch file which
1664           was examined, a newer upstream version was located.
1665
1666       1   No newer upstream versions were located for any of the watch files
1667           examined.
1668

ADVANCED FEATURES

1670       uscan has many other enhanced features which are skipped in the above
1671       section for the simplicity.  Let's check their highlights.
1672
1673       uscan can be executed with path as its argument to change the starting
1674       directory of search from the current directory to path .
1675
1676       If you are not sure what exactly is happening behind the scene, please
1677       enable the --verbose option.  If this is not enough, enable the --debug
1678       option too see all the internal activities.
1679
1680       See "COMMANDLINE OPTIONS" and "DEVSCRIPT CONFIGURATION VARIABLES" for
1681       other variations.
1682
1683   Custom script
1684       The optional script parameter in debian/watch means to execute script
1685       with options after processing this line if specified.
1686
1687       See "HISTORY AND UPGRADING" for how uscan invokes the custom script.
1688
1689       For compatibility with other tools such as git-buildpackage, it may not
1690       be wise to create custom scripts with random behavior.  In general,
1691       uupdate is the best choice for the non-native package and custom
1692       scripts, if created, should behave as if uupdate.  For possible use
1693       case, see <http://bugs.debian.org/748474> as an example.
1694
1695   URL diversion
1696       Some popular web sites changed their web page structure causing
1697       maintenance problems to the watch file.  There are some redirection
1698       services created to ease maintenance of the watch file.  Currently,
1699       uscan makes automatic diversion of URL requests to the following URLs
1700       to cope with this situation.
1701
1702       •   <http://sf.net>
1703
1704       •   <http://pypi.python.org>
1705
1706   Directory name checking
1707       Similarly to several other scripts in the devscripts package, uscan
1708       explores the requested directory trees looking for debian/changelog and
1709       debian/watch files. As a safeguard against stray files causing
1710       potential problems, and in order to promote efficiency, it will examine
1711       the name of the parent directory once it finds the debian/changelog
1712       file, and check that the directory name corresponds to the package
1713       name. It will only attempt to download newer versions of the package
1714       and then perform any requested action if the directory name matches the
1715       package name. Precisely how it does this is controlled by two
1716       configuration file variables DEVSCRIPTS_CHECK_DIRNAME_LEVEL and
1717       DEVSCRIPTS_CHECK_DIRNAME_REGEX, and their corresponding command-line
1718       options --check-dirname-level and --check-dirname-regex.
1719
1720       DEVSCRIPTS_CHECK_DIRNAME_LEVEL can take the following values:
1721
1722       0   Never check the directory name.
1723
1724       1   Only check the directory name if we have had to change directory in
1725           our search for debian/changelog, that is, the directory containing
1726           debian/changelog is not the directory from which uscan was invoked.
1727           This is the default behavior.
1728
1729       2   Always check the directory name.
1730
1731       The directory name is checked by testing whether the current directory
1732       name (as determined by pwd(1)) matches the regex given by the
1733       configuration file option DEVSCRIPTS_CHECK_DIRNAME_REGEX or by the
1734       command line option --check-dirname-regex regex. Here regex is a Perl
1735       regex (see perlre(3perl)), which will be anchored at the beginning and
1736       the end. If regex contains a /, then it must match the full directory
1737       path. If not, then it must match the full directory name. If regex
1738       contains the string package, this will be replaced by the source
1739       package name, as determined from the debian/changelog. The default
1740       value for the regex is: package(-.+)?, thus matching directory names
1741       such as package and package-version.
1742

HISTORY AND UPGRADING

1744       This section briefly describes the backwards-incompatible watch file
1745       features which have been added in each watch file version, and the
1746       first version of the devscripts package which understood them.
1747
1748       Pre-version 2
1749           The watch file syntax was significantly different in those days.
1750           Don't use it.  If you are upgrading from a pre-version 2 watch
1751           file, you are advised to read this manpage and to start from
1752           scratch.
1753
1754       Version 2
1755           devscripts version 2.6.90: The first incarnation of the current
1756           style of watch files. This version is also deprecated and will be
1757           rejected after the Debian 11 release.
1758
1759       Version 3
1760           devscripts version 2.8.12: Introduced the following: correct
1761           handling of regex special characters in the path part,
1762           directory/path pattern matching, version number in several parts,
1763           version number mangling. Later versions have also introduced URL
1764           mangling.
1765
1766           If you are upgrading from version 2, the key incompatibility is if
1767           you have multiple groups in the pattern part; whereas only the
1768           first one would be used in version 2, they will all be used in
1769           version 3. To avoid this behavior, change the non-version-number
1770           groups to be (?:  ... ) instead of a plain (  ...  ) group.
1771
1772uscan invokes the custom script as "script --upstream-version
1773               version ../spkg_version.orig.tar.gz".
1774
1775uscan invokes the standard uupdate as "uupdate --no-symlink
1776               --upstream-version version ../spkg_version.orig.tar.gz".
1777
1778       Version 4
1779           devscripts version 2.15.10: The first incarnation of watch files
1780           supporting multiple upstream tarballs.
1781
1782           The syntax of the watch file is relaxed to allow more spaces for
1783           readability.
1784
1785           If you have a custom script in place of uupdate, you may also
1786           encounter problems updating from Version 3.
1787
1788uscan invokes the custom script as "script --upstream-version
1789               version".
1790
1791uscan invokes the standard uupdate as "uupdate --find
1792               --upstream-version version".
1793
1794           Restriction for --dehs is lifted by redirecting other output to
1795           STDERR when it is activated.
1796

SEE ALSO

1798       dpkg(1), mk-origtargz(1), perlre(1), uupdate(1), devscripts.conf(5)
1799

AUTHOR

1801       The original version of uscan was written by Christoph Lameter
1802       <clameter@debian.org>. Significant improvements, changes and bugfixes
1803       were made by Julian Gilbey <jdg@debian.org>. HTTP support was added by
1804       Piotr Roszatycki <dexter@debian.org>. The program was rewritten in Perl
1805       by Julian Gilbey. Xavier Guimard converted it in object-oriented Perl
1806       using Moo.
1807
1808
1809
1810Debian Utilities                  2021-08-19                          USCAN(1)
Impressum