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

EXAMPLE OF EXECUTION

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

WATCH FILE EXAMPLES

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

KEYRING FILE EXAMPLES

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

COMMANDLINE OPTIONS

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

DEVSCRIPT CONFIGURATION VARIABLES

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

EXIT STATUS

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

ADVANCED FEATURES

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

HISTORY AND UPGRADING

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

SEE ALSO

1792       dpkg(1), mk-origtargz(1), perlre(1), uupdate(1), devscripts.conf(5)
1793

AUTHOR

1795       The original version of uscan was written by Christoph Lameter
1796       <clameter@debian.org>. Significant improvements, changes and bugfixes
1797       were made by Julian Gilbey <jdg@debian.org>. HTTP support was added by
1798       Piotr Roszatycki <dexter@debian.org>. The program was rewritten in Perl
1799       by Julian Gilbey. Xavier Guimard converted it in object-oriented Perl
1800       using Moo.
1801
1802
1803
1804Debian Utilities                  2023-07-19                          USCAN(1)
Impressum