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

FORMAT OF THE WATCH FILE

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

WATCH FILE OPTIONS

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

EXAMPLE OF EXECUTION

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

WATCH FILE EXAMPLES

707       When writing the watch file, you should rely on the latest upstream
708       source announcement web page.  You should not try to second guess the
709       upstream archive structure if possible.  Here are the typical
710       debian/watch files.
711
712       Please note that executing uscan with -v or -vv reveals what exactly
713       happens internally.
714
715       The existence and non-existence of a space the before tailing \ (back
716       slash) are significant.
717
718       Some undocumented shorter configuration strings are used in the below
719       EXAMPLES to help you with typing.  These are intentional ones.  uscan
720       is written to accept such common sense abbreviations but don't push the
721       limit.
722
723   HTTP site (basic)
724       Here is an example for the basic single upstream tarball.
725
726         version=4
727         http://example.com/~user/release/foo.html \
728             files/foo-([\d\.]+)\.tar\.gz debian uupdate
729
730       Or using the special strings:
731
732         version=4
733         http://example.com/~user/release/@PACKAGE@.html \
734             files/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian uupdate
735
736       For the upstream source package foo-2.0.tar.gz, this watch file
737       downloads and creates the Debian orig.tar file foo_2.0.orig.tar.gz.
738
739   HTTP site (pgpsigurlmangle)
740       Here is an example for the basic single upstream tarball with the
741       matching signature file in the same file path.
742
743         version=4
744         opts="pgpsigurlmangle=s%$%.asc%" http://example.com/release/@PACKAGE@.html \
745             files/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian uupdate
746
747       For the upstream source package foo-2.0.tar.gz and the upstream
748       signature file foo-2.0.tar.gz.asc, this watch file downloads these
749       files, verifies the authenticity using the keyring
750       debian/upstream/signing-key.asc and creates the Debian orig.tar file
751       foo_2.0.orig.tar.gz.
752
753       Here is another example for the basic single upstream tarball with the
754       matching signature file on decompressed tarball in the same file path.
755
756         version=4
757         opts="pgpsigurlmangle=s%@ARCHIVE_EXT@$%.asc%,decompress" \
758             http://example.com/release/@PACKAGE@.html \
759             files/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian uupdate
760
761       For the upstream source package foo-2.0.tar.gz and the upstream
762       signature file foo-2.0.tar.asc, this watch file downloads these files,
763       verifies the authenticity using the keyring
764       debian/upstream/signing-key.asc and creates the Debian orig.tar file
765       foo_2.0.orig.tar.gz.
766
767   HTTP site (pgpmode=next/previous)
768       Here is an example for the basic single upstream tarball with the
769       matching signature file in the unrelated file path.
770
771         version=4
772         opts="pgpmode=next" http://example.com/release/@PACKAGE@.html \
773             files/(?:\d+)/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian
774         opts="pgpmode=previous" http://example.com/release/@PACKAGE@.html \
775             files/(?:\d+)/@PACKAGE@@ANY_VERSION@@SIGNATURE_EXT@ previous uupdate
776
777       (?:\d+) part can be any random value.  The tarball file can have 53,
778       while the signature file can have 33.
779
780       ([\d\.]+) part for the signature file has a strict requirement to match
781       that for the upstream tarball specified in the previous line by having
782       previous as version in the watch line.
783
784   HTTP site (flexible)
785       Here is an example for the maximum flexibility of upstream tarball and
786       signature file extensions.
787
788         version=4
789         opts="pgpmode=next" http://example.com/DL/ \
790             files/(?:\d+)/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian
791         opts="pgpmode=previous" http://example.com/DL/ \
792             files/(?:\d+)/@PACKAGE@@ANY_VERSION@@SIGNATURE_EXT@ \
793             previous uupdate
794
795   HTTP site (basic MUT)
796       Here is an example for the basic multiple upstream tarballs.
797
798         version=4
799         opts="pgpsigurlmangle=s%$%.sig%" \
800             http://example.com/release/foo.html \
801             files/foo-([\d\.]+)\.tar\.gz debian
802         opts="pgpsigurlmangle=s%$%.sig%, component=bar" \
803             http://example.com/release/foo.html \
804             files/foobar-([\d\.]+)\.tar\.gz same
805         opts="pgpsigurlmangle=s%$%.sig%, component=baz" \
806             http://example.com/release/foo.html \
807             files/foobaz-([\d\.]+)\.tar\.gz same uupdate
808
809       For the main upstream source package foo-2.0.tar.gz and the secondary
810       upstream source packages foobar-2.0.tar.gz and foobaz-2.0.tar.gz which
811       install under bar/ and baz/, this watch file downloads and creates the
812       Debian orig.tar file foo_2.0.orig.tar.gz, foo_2.0.orig-bar.tar.gz and
813       foo_2.0.orig-baz.tar.gz.  Also, these upstream tarballs are verified by
814       their signature files.
815
816   HTTP site (recursive directory scanning)
817       Here is an example with the recursive directory scanning for the
818       upstream tarball and its signature files released in a directory named
819       after their version.
820
821         version=4
822         opts="pgpsigurlmangle=s%$%.sig%, dirversionmangle=s/-PRE/~pre/;s/-RC/~rc/" \
823             http://tmrc.mit.edu/mirror/twisted/Twisted/([\d+\.]+)/ \
824             Twisted-([\d\.]+)\.tar\.xz debian uupdate
825
826       Here, the web site should be accessible at the following URL:
827
828         http://tmrc.mit.edu/mirror/twisted/Twisted/
829
830       Here, dirversionmangle option is used to normalize the sorting order of
831       the directory names.
832
833   HTTP site (alternative shorthand)
834       For the bare HTTP site where you can directly see archive filenames,
835       the normal watch file:
836
837         version=4
838         opts="pgpsigurlmangle=s%$%.sig%" \
839             http://www.cpan.org/modules/by-module/Text/ \
840             Text-CSV_XS-(.+)\.tar\.gz \
841             debian uupdate
842
843       can be rewritten in an alternative shorthand form only with a single
844       string covering URL and filename:
845
846         version=4
847         opts="pgpsigurlmangle=s%$%.sig%" \
848             http://www.cpan.org/modules/by-module/Text/Text-CSV_XS-(.+)\.tar\.gz \
849             debian uupdate
850
851       In version=4, initial white spaces are dropped.  Thus, this alternative
852       shorthand form can also be written as:
853
854         version=4
855         opts="pgpsigurlmangle=s%$%.sig%" \
856             http://www.cpan.org/modules/by-module/Text/\
857             Text-CSV_XS-(.+)\.tar\.gz \
858             debian uupdate
859
860       Please note the subtle difference of a space before the tailing \
861       between the first and the last examples.
862
863   HTTP site (funny version)
864       For a site which has funny version numbers, the parenthesized groups
865       will be joined with . (period) to make a sanitized version number.
866
867         version=4
868         http://www.site.com/pub/foobar/foobar_v(\d+)_(\d+)\.tar\.gz \
869         debian uupdate
870
871   HTTP site (DFSG)
872       The upstream part of the Debian version number can be mangled to
873       indicate the source package was repackaged to clean up non-DFSG files:
874
875         version=4
876         opts="dversionmangle=s/\+dfsg\d*$//,repacksuffix=+dfsg1" \
877         http://some.site.org/some/path/foobar-(.+)\.tar\.gz debian uupdate
878
879       See "COPYRIGHT FILE EXAMPLES".
880
881   HTTP site (filenamemangle)
882       The upstream tarball filename is found by taking the last component of
883       the URL and removing everything after any '?' or '#'.
884
885       If this does not fit to you, use filenamemangle.  For example, <A
886       href="http://foo.bar.org/dl/?path=&dl=foo-0.1.1.tar.gz"> could be
887       handled as:
888
889         version=4
890         opts=filenamemangle=s/.*=(.*)/$1/ \
891         http://foo.bar.org/dl/\?path=&dl=foo-(.+)\.tar\.gz \
892         debian uupdate
893
894       <A href="http://foo.bar.org/dl/?path=&dl_version=0.1.1"> could be
895       handled as:
896
897         version=4
898         opts=filenamemangle=s/.*=(.*)/foo-$1\.tar\.gz/ \
899         http://foo.bar.org/dl/\?path=&dl_version=(.+) \
900         debian uupdate
901
902       If the href string has no version using <I>matching-pattern>, the
903       version can be obtained from the full URL using filenamemangle.
904
905         version=4
906         opts=filenamemangle=s&.*/dl/(.*)/foo\.tar\.gz&foo-$1\.tar\.gz& \
907         http://foo.bar.org/dl/([\.\d]+)/ foo.tar.gz \
908         debian uupdate
909
910   HTTP site (downloadurlmangle)
911       The option downloadurlmangle can be used to mangle the URL of the file
912       to download.  This can only be used with http:// URLs.  This may be
913       necessary if the link given on the web page needs to be transformed in
914       some way into one which will work automatically, for example:
915
916         version=4
917         opts=downloadurlmangle=s/prdownload/download/ \
918         http://developer.berlios.de/project/showfiles.php?group_id=2051 \
919         http://prdownload.berlios.de/softdevice/vdr-softdevice-(.+).tgz \
920         debian uupdate
921
922   HTTP site (oversionmangle, MUT)
923       The option oversionmangle can be used to mangle the version of the
924       source tarball (.orig.tar.gz and .orig-bar.tar.gz).  For example,
925       +dfsg1 can be added to the upstream version as:
926
927         version=4
928         opts=oversionmangle=s/(.*)/$1+dfsg1/ \
929         http://example.com/~user/release/foo.html \
930         files/foo-([\d\.]*).tar.gz debian
931         opts="component=bar" \
932         http://example.com/~user/release/foo.html \
933         files/bar-([\d\.]*).tar.gz same uupdate
934
935       See "COPYRIGHT FILE EXAMPLES".
936
937   HTTP site (pagemangle)
938       The option pagemangle can be used to mangle the downloaded web page
939       before applying other rules.  The non-standard web page without proper
940       <a href=" << ... >> "> entries can be converted.  For example, if
941       foo.html uses <a bogus=" ... ">, this can be converted to the standard
942       page format with:
943
944         version=4
945         opts=pagemangle="s/<a\s+bogus=/<a href=/g" \
946         http://example.com/release/foo.html \
947         files/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian uupdate
948
949       Please note the use of g here to replace all occurrences.
950
951       If foo.html uses <Key> ... </Key>, this can be converted to the
952       standard page format with:
953
954         version=4
955         opts="pagemangle=s%<Key>([^<]*)</Key>%<Key><a href="$1">$1</a></Key>%g" \
956         http://example.com/release/foo.html \
957         (?:.*)/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian uupdate
958
959   FTP site (basic):
960         version=4
961         ftp://ftp.tex.ac.uk/tex-archive/web/c_cpp/cweb/cweb-(.+)\.tar\.gz \
962         debian uupdate
963
964   FTP site (regex special characters):
965         version=4
966         ftp://ftp.worldforge.org/pub/worldforge/libs/\
967         Atlas-C++/transitional/Atlas-C\+\+-(.+)\.tar\.gz debian uupdate
968
969       Please note that this URL is connected to be  ... libs/Atlas-C++/ ...
970       . For ++, the first one in the directory path is verbatim while the one
971       in the filename is escaped by \.
972
973   FTP site (funny version)
974       This is another way of handling site with funny version numbers, this
975       time using mangling.  (Note that multiple groups will be concatenated
976       before mangling is performed, and that mangling will only be performed
977       on the basename version number, not any path version numbers.)
978
979         version=4
980         opts="uversionmangle=s/^/0.0./" \
981         ftp://ftp.ibiblio.org/pub/Linux/ALPHA/wine/\
982         development/Wine-(.+)\.tar\.gz debian uupdate
983
984   sf.net
985       For SourceForge based projects, qa.debian.org runs a redirector which
986       allows a simpler form of URL. The format below will automatically be
987       rewritten to use the redirector with the watch file:
988
989         version=4
990         https://sf.net/<project>/ <tar-name>-(.+)\.tar\.gz debian uupdate
991
992       For audacity, set the watch file as:
993
994         version=4
995         https://sf.net/audacity/ audacity-minsrc-(.+)\.tar\.gz debian uupdate
996
997       Please note, you can still use normal functionalities of uscan to set
998       up a watch file for this site without using the redirector.
999
1000         version=4
1001         opts="uversionmangle=s/-pre/~pre/, \
1002               filenamemangle=s%(?:.*)audacity-minsrc-(.+)\.tar\.xz/download%\
1003                                audacity-$1.tar.xz%" \
1004               http://sourceforge.net/projects/audacity/files/audacity/(\d[\d\.]+)/ \
1005               (?:.*)audacity-minsrc-([\d\.]+)\.tar\.xz/download debian uupdate
1006
1007       Here, % is used as the separator instead of the standard /.
1008
1009   github.com
1010       For GitHub based projects, you can use the tags or releases page.  The
1011       archive URL uses only the version as the filename.  You can rename the
1012       downloaded upstream tarball from into the standard
1013       <project>-<version>.tar.gz using filenamemangle:
1014
1015         version=4
1016         opts="filenamemangle=s%(?:.*?)?v?(\d[\d.]*)\.tar\.gz%<project>-$1.tar.gz%" \
1017             https://github.com/<user>/<project>/tags \
1018             (?:.*?/)?v?(\d[\d.]*)\.tar\.gz debian uupdate
1019
1020   PyPI
1021       For PyPI based projects, pypi.debian.net runs a redirector which allows
1022       a simpler form of URL. The format below will automatically be rewritten
1023       to use the redirector with the watch file:
1024
1025         version=4
1026         https://pypi.python.org/packages/source/<initial>/<project>/ \
1027             <tar-name>-(.+)\.tar\.gz debian uupdate
1028
1029       For cfn-sphere, set the watch file as:
1030
1031         version=4
1032         https://pypi.python.org/packages/source/c/cfn-sphere/ \
1033             cfn-sphere-([\d\.]+).tar.gz debian uupdate
1034
1035       Please note, you can still use normal functionalities of uscan to set
1036       up a watch file for this site without using the redirector.
1037
1038         version=4
1039         opts="pgpmode=none" \
1040             https://pypi.python.org/pypi/cfn-sphere/ \
1041             https://pypi.python.org/packages/.*/.*/.*/\
1042             cfn-sphere-([\d\.]+).tar.gz#.* debian uupdate
1043
1044   code.google.com
1045       Sites which used to be hosted on the Google Code service should have
1046       migrated to elsewhere (github?).  Please look for the newer upstream
1047       site if available.
1048
1049   npmjs.org (node modules)
1050       npmjs.org modules are published in JSON files. Here is a way to read
1051       them:
1052
1053         version=4
1054         opts="searchmode=plain" \
1055          https://registry.npmjs.org/aes-js \
1056          https://registry.npmjs.org/aes-js/-/aes-js-(\d[\d\.]*)@ARCHIVE_EXT@
1057
1058   grouped package
1059       Some node modules are split into multiple little upstream package. Here
1060       is a way to group them:
1061
1062         version=4
1063         opts="searchmode=plain,pgpmode=none" \
1064           https://registry.npmjs.org/mongodb \
1065           https://registry.npmjs.org/mongodb/-/mongodb-(\d[\d\.]*)@ARCHIVE_EXT@ group
1066         opts="searchmode=plain,pgpmode=none,component=bson" \
1067           https://registry.npmjs.org/bson \
1068           https://registry.npmjs.org/bson/-/bson-(\d[\d\.]*)@ARCHIVE_EXT@ group
1069         opts="searchmode=plain,pgpmode=none,component=mongodb-core" \
1070           https://registry.npmjs.org/mongodb-core \
1071           https://registry.npmjs.org/mongodb-core/-/mongodb-core-(\d[\d\.]*)@ARCHIVE_EXT@ group
1072         opts="searchmode=plain,pgpmode=none,component=requireoptional" \
1073           https://registry.npmjs.org/require_optional \
1074           https://registry.npmjs.org/require_optional/-/require_optional-(\d[\d\.]*)@ARCHIVE_EXT@ group
1075
1076       Package version is then the concatenation of upstream versions
1077       separated by "+~".
1078
1079   direct access to the git repository (tags)
1080       If the upstream only publishes its code via the git repository and its
1081       code has no web interface to obtain the release tarball, you can use
1082       uscan with the tags of the git repository to track and package the new
1083       upstream release.
1084
1085         version=4
1086         opts="mode=git, gitmode=full, pgpmode=none" \
1087         http://git.ao2.it/tweeper.git \
1088         refs/tags/v([\d\.]+) debian uupdate
1089
1090       Please note "git ls-remote" is used to obtain references for tags.
1091
1092       If a tag v20.5 is the newest tag, the above example downloads
1093       spkg-20.5.tar.xz after making a full clone of the git repository which
1094       is needed for dumb git server.
1095
1096       If tags are signed, set pgpmode=gittag to verify them.
1097
1098   direct access to the git repository (HEAD)
1099       If the upstream only publishes its code via the git repository and its
1100       code has no web interface nor the tags to obtain the released tarball,
1101       you can use uscan with the HEAD of the git repository to track and
1102       package the new upstream release with an automatically generated
1103       version string.
1104
1105         version=4
1106         opts="mode=git, pgpmode=none" \
1107         https://github.com/Debian/dh-make-golang \
1108         HEAD debian uupdate
1109
1110       Please note that a local shallow copy of the git repository is made
1111       with "git clone --bare --depth=1 ..." normally in the target directory.
1112       uscan generates the new upstream version with "git log
1113       --date=format:%Y%m%d --pretty=0.0~git%cd.%h" on this local copy of
1114       repository as its default behavior.
1115
1116       The generation of the upstream version string may the adjusted to your
1117       taste by adding pretty and date options to the opts arguments.
1118
1120       Here is an example for the debian/copyright file which initiates
1121       automatic repackaging of the upstream tarball into
1122       <spkg>_<oversion>.orig.tar.gz (In debian/copyright, the Files-Excluded
1123       and Files-Excluded-component stanzas are a part of the first paragraph
1124       and there is a blank line before the following paragraphs which contain
1125       Files and other stanzas.):
1126
1127         Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
1128         Files-Excluded: exclude-this
1129          exclude-dir
1130          */exclude-dir
1131          .*
1132          */js/jquery.js
1133
1134          Files: *
1135          Copyright: ...
1136          ...
1137
1138       Here is another example for the debian/copyright file which initiates
1139       automatic repackaging of the multiple upstream tarballs into
1140       <spkg>_<oversion>.orig.tar.gz and <spkg>_<oversion>.orig-bar.tar.gz:
1141
1142         Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
1143         Files-Excluded: exclude-this
1144          exclude-dir
1145          */exclude-dir
1146          .*
1147          */js/jquery.js
1148         Files-Excluded-bar: exclude-this
1149          exclude-dir
1150          */exclude-dir
1151          .*
1152          */js/jquery.js
1153
1154          Files: *
1155          Copyright: ...
1156          ...
1157
1158       See mk-origtargz(1).
1159

KEYRING FILE EXAMPLES

1161       Let's assume that the upstream "uscan test key (no secret)
1162       <none@debian.org>" signs its package with a secret OpenPGP key and
1163       publishes the corresponding public OpenPGP key.  This public OpenPGP
1164       key can be identified in 3 ways using the hexadecimal form.
1165
1166       ·   The fingerprint as the 20 byte data calculated from the public
1167           OpenPGP key. E.  g., 'CF21 8F0E 7EAB F584 B7E2 0402 C77E 2D68 7254
1168           3FAF'
1169
1170       ·   The long keyid as the last 8 byte data of the fingerprint. E. g.,
1171           'C77E2D6872543FAF'
1172
1173       ·   The short keyid is the last 4 byte data of the fingerprint. E. g.,
1174           '72543FAF'
1175
1176       Considering the existence of the collision attack on the short keyid,
1177       the use of the long keyid is recommended for receiving keys from the
1178       public key servers.  You must verify the downloaded OpenPGP key using
1179       its full fingerprint value which you know is the trusted one.
1180
1181       The armored keyring file debian/upstream/signing-key.asc can be created
1182       by using the gpg (or gpg2) command as follows.
1183
1184         $ gpg --recv-keys "C77E2D6872543FAF"
1185         ...
1186         $ gpg --finger "C77E2D6872543FAF"
1187         pub   4096R/72543FAF 2015-09-02
1188               Key fingerprint = CF21 8F0E 7EAB F584 B7E2  0402 C77E 2D68 7254 3FAF
1189         uid                  uscan test key (no secret) <none@debian.org>
1190         sub   4096R/52C6ED39 2015-09-02
1191         $ cd path/to/<upkg>-<uversion>
1192         $ mkdir -p debian/upstream
1193         $ gpg --export --export-options export-minimal --armor \
1194               'CF21 8F0E 7EAB F584 B7E2  0402 C77E 2D68 7254 3FAF' \
1195               >debian/upstream/signing-key.asc
1196
1197       The binary keyring files, debian/upstream/signing-key.pgp and
1198       debian/upstream-signing-key.pgp, are still supported but deprecated.
1199
1200       If a group of developers sign the package, you need to list
1201       fingerprints of all of them in the argument for gpg --export ... to
1202       make the keyring to contain all OpenPGP keys of them.
1203
1204       Sometimes you may wonder who made a signature file.  You can get the
1205       public keyid used to create the detached signature file
1206       foo-2.0.tar.gz.asc by running gpg as:
1207
1208         $ gpg -vv foo-2.0.tar.gz.asc
1209         gpg: armor: BEGIN PGP SIGNATURE
1210         gpg: armor header: Version: GnuPG v1
1211         :signature packet: algo 1, keyid C77E2D6872543FAF
1212               version 4, created 1445177469, md5len 0, sigclass 0x00
1213               digest algo 2, begin of digest 7a c7
1214               hashed subpkt 2 len 4 (sig created 2015-10-18)
1215               subpkt 16 len 8 (issuer key ID C77E2D6872543FAF)
1216               data: [4091 bits]
1217         gpg: assuming signed data in `foo-2.0.tar.gz'
1218         gpg: Signature made Sun 18 Oct 2015 11:11:09 PM JST using RSA key ID 72543FAF
1219         ...
1220

COMMANDLINE OPTIONS

1222       For the basic usage, uscan does not require to set these options.
1223
1224       --conffile, --conf-file
1225           Add or replace default configuration files ("/etc/devscripts.conf"
1226           and "~/.devscripts"). This can only be used as the first option
1227           given on the command-line.
1228
1229           replace:
1230                 uscan --conf-file test.conf --verbose
1231
1232           add:
1233                 uscan --conf-file +test.conf --verbose
1234
1235               If one --conf-file has no "+", default configuration files are
1236               ignored.
1237
1238       --no-conf, --noconf
1239           Don't read any configuration files. This can only be used as the
1240           first option given on the command-line.
1241
1242       --no-verbose
1243           Don't report verbose information. (default)
1244
1245       --verbose, -v
1246           Report verbose information.
1247
1248       --debug, -vv
1249           Report verbose information including the downloaded web pages as
1250           processed to STDERR for debugging.
1251
1252       --dehs
1253           Send DEHS style output (XML-type) to STDOUT, while send all other
1254           uscan output to STDERR.
1255
1256       --no-dehs
1257           Use only traditional uscan output format. (default)
1258
1259       --download, -d
1260           Download the new upstream release. (default)
1261
1262       --force-download, -dd
1263           Download the new upstream release even if up-to-date. (may not
1264           overwrite the local file)
1265
1266       --overwrite-download, -ddd
1267           Download the new upstream release even if up-to-date. (may
1268           overwrite the local file)
1269
1270       --no-download, --nodownload
1271           Don't download and report information.
1272
1273           Previously downloaded tarballs may be used.
1274
1275           Change default to --skip-signature.
1276
1277       --signature
1278           Download signature. (default)
1279
1280       --no-signature
1281           Don't download signature but verify if already downloaded.
1282
1283       --skip-signature
1284           Don't bother download signature nor verifying signature.
1285
1286       --safe, --report
1287           Avoid running unsafe scripts by skipping both the repacking of the
1288           downloaded package and the updating of the new source tree.
1289
1290           Change default to --no-download and --skip-signature.
1291
1292           When the objective of running uscan is to gather the upstream
1293           package status under the security conscious environment, please
1294           make sure to use this option.
1295
1296       --report-status
1297           This is equivalent of setting "--verbose --safe".
1298
1299       --download-version version
1300           Specify the version which the upstream release must match in order
1301           to be considered, rather than using the release with the highest
1302           version.  (a best effort feature)
1303
1304       --download-debversion version
1305           Specify the Debian package version to download the corresponding
1306           upstream release version.  The dversionmangle and uversionmangle
1307           rules are considered.  (a best effort feature)
1308
1309       --download-current-version
1310           Download the currently packaged version.  (a best effort feature)
1311
1312       --check-dirname-level N
1313           See the below section "Directory name checking" for an explanation
1314           of this option.
1315
1316       --check-dirname-regex regex
1317           See the below section "Directory name checking" for an explanation
1318           of this option.
1319
1320       --destdir path Normally, uscan changes its internal current directory
1321       to the package's source directory where the debian/ is located.  Then
1322       the destination directory for the downloaded tarball and other files is
1323       set to the parent directory ../ from this internal current directory.
1324           This default destination directory can be overridden by setting
1325           --destdir option to a particular path.  If this path is a relative
1326           path, the destination directory is determined in relative to the
1327           internal current directory of uscan execution. If this path is a
1328           absolute path, the destination directory is set to path
1329           irrespective of the internal current directory of uscan execution.
1330
1331           The above is true not only for the sinple uscan run in the single
1332           source tree but also for the advanced scanning uscan run with
1333           subdirectories holding multiple source trees.
1334
1335           One exception is when --watchfile and --package are used together.
1336           For this case, the internal current directory of uscan execution
1337           and the default destination directory are set to the current
1338           directory . where uscan is started.  The default destination
1339           directory can be overridden by setting --destdir option as well.
1340
1341       --package package
1342           Specify the name of the package to check for rather than examining
1343           debian/changelog; this requires the --upstream-version (unless a
1344           version is specified in the watch file) and --watchfile options as
1345           well.  Furthermore, no directory scanning will be done and nothing
1346           will be downloaded.  This option automatically sets --no-download
1347           and --skip-signature; and probably most useful in conjunction with
1348           the DEHS system (and --dehs).
1349
1350       --upstream-version upstream-version
1351           Specify the current upstream version rather than examine
1352           debian/watch or debian/changelog to determine it. This is ignored
1353           if a directory scan is being performed and more than one
1354           debian/watch file is found.
1355
1356       --watchfile watchfile
1357           Specify the watchfile rather than perform a directory scan to
1358           determine it.  If this option is used without --package, then uscan
1359           must be called from within the Debian package source tree (so that
1360           debian/changelog can be found simply by stepping up through the
1361           tree).
1362
1363           One exception is when --watchfile and --package are used together.
1364           uscan can be called from anywhare and the internal current
1365           directory of uscan execution and the default destination directory
1366           are set to the current directory . where uscan is started.
1367
1368           See more in the --destdir explanation.
1369
1370       --bare
1371           Disable all site specific special case codes to perform URL
1372           redirections and page content alterations.
1373
1374       --no-exclusion
1375           Don't automatically exclude files mentioned in debian/copyright
1376           field Files-Excluded.
1377
1378       --pasv
1379           Force PASV mode for FTP connections.
1380
1381       --no-pasv
1382           Don't use PASV mode for FTP connections.
1383
1384       --no-symlink
1385           Don't rename nor repack upstream tarball.
1386
1387       --timeout N
1388           Set timeout to N seconds (default 20 seconds).
1389
1390       --user-agent, --useragent
1391           Override the default user agent header.
1392
1393       --help
1394           Give brief usage information.
1395
1396       --version
1397           Display version information.
1398
1399       uscan also accepts following options and passes them to mk-origtargz:
1400
1401       --symlink
1402           Make orig.tar.gz (with the appropriate extension) symlink to the
1403           downloaded files. (This is the default behavior.)
1404
1405       --copy
1406           Instead of symlinking as described above, copy the downloaded
1407           files.
1408
1409       --rename
1410           Instead of symlinking as described above, rename the downloaded
1411           files.
1412
1413       --repack
1414           After having downloaded an lzma tar, xz tar, bzip tar, gz tar, zip,
1415           jar, xpi archive, repack it to the specified compression (see
1416           --compression).
1417
1418           The unzip package must be installed in order to repack zip and jar
1419           archives, the mozilla-devscripts package must be installed to
1420           repack xpi archives, and the xz-utils package must be installed to
1421           repack lzma or xz tar archives.
1422
1423       --compression [ gzip | bzip2 | lzma | xz ]
1424           In the case where the upstream sources are repacked (either because
1425           --repack option is given or debian/copyright contains the field
1426           Files-Excluded), it is possible to control the compression method
1427           via the parameter.  The default is gzip for normal tarballs, and xz
1428           for tarballs generated directly from the git repository.
1429
1430       --copyright-file copyright-file
1431           Exclude files mentioned in Files-Excluded in the given copyright-
1432           file.  This is useful when running uscan not within a source
1433           package directory.
1434

DEVSCRIPT CONFIGURATION VARIABLES

1436       For the basic usage, uscan does not require to set these configuration
1437       variables.
1438
1439       The two configuration files /etc/devscripts.conf and ~/.devscripts are
1440       sourced by a shell in that order to set configuration variables. These
1441       may be overridden by command line options. Environment variable
1442       settings are ignored for this purpose. If the first command line option
1443       given is --noconf, then these files will not be read. The currently
1444       recognized variables are:
1445
1446       USCAN_DOWNLOAD
1447           Download or report only:
1448
1449           no: equivalent to --no-download, newer upstream files will not be
1450           downloaded.
1451           yes: equivalent to --download, newer upstream files will be
1452           downloaded. This is the default behavior.
1453               See also --force-download and --overwrite-download.
1454
1455       USCAN_SAFE
1456           If this is set to yes, then uscan avoids running unsafe scripts by
1457           skipping both the repacking of the downloaded package and the
1458           updating of the new source tree; this is equivalent to the --safe
1459           options; this also sets the default to --no-download and
1460           --skip-signature.
1461
1462       USCAN_PASV
1463           If this is set to yes or no, this will force FTP connections to use
1464           PASV mode or not to, respectively. If this is set to default, then
1465           Net::FTP(3) makes the choice (primarily based on the FTP_PASSIVE
1466           environment variable).
1467
1468       USCAN_TIMEOUT
1469           If set to a number N, then set the timeout to N seconds. This is
1470           equivalent to the --timeout option.
1471
1472       USCAN_SYMLINK
1473           If this is set to no, then a pkg_version.orig.tar.{gz|bz2|lzma|xz}
1474           symlink will not be made (equivalent to the --no-symlink option).
1475           If it is set to yes or symlink, then the symlinks will be made. If
1476           it is set to rename, then the files are renamed (equivalent to the
1477           --rename option).
1478
1479       USCAN_DEHS_OUTPUT
1480           If this is set to yes, then DEHS-style output will be used. This is
1481           equivalent to the --dehs option.
1482
1483       USCAN_VERBOSE
1484           If this is set to yes, then verbose output will be given.  This is
1485           equivalent to the --verbose option.
1486
1487       USCAN_USER_AGENT
1488           If set, the specified user agent string will be used in place of
1489           the default.  This is equivalent to the --user-agent option.
1490
1491       USCAN_DESTDIR
1492           If set, the downloaded files will be placed in this  directory.
1493           This is equivalent to the --destdir option.
1494
1495       USCAN_REPACK
1496           If this is set to yes, then after having downloaded a bzip tar,
1497           lzma tar, xz tar, or zip archive, uscan will repack it to the
1498           specified compression (see --compression). This is equivalent to
1499           the --repack option.
1500
1501       USCAN_EXCLUSION
1502           If this is set to no, files mentioned in the field Files-Excluded
1503           of debian/copyright will be ignored and no exclusion of files will
1504           be tried.  This is equivalent to the --no-exclusion option.
1505

EXIT STATUS

1507       The exit status gives some indication of whether a newer version was
1508       found or not; one is advised to read the output to determine exactly
1509       what happened and whether there were any warnings to be noted.
1510
1511       0   Either --help or --version was used, or for some watch file which
1512           was examined, a newer upstream version was located.
1513
1514       1   No newer upstream versions were located for any of the watch files
1515           examined.
1516

ADVANCED FEATURES

1518       uscan has many other enhanced features which are skipped in the above
1519       section for the simplicity.  Let's check their highlights.
1520
1521       uscan actually scans not just the current directory but all its
1522       subdirectories looking for debian/watch to process them all.  See
1523       "Directory name checking".
1524
1525       uscan can be executed with path as its argument to change the starting
1526       directory of search from the current directory to path .
1527
1528       If you are not sure what exactly is happening behind the scene, please
1529       enable the --verbose option.  If this is not enough, enable the --debug
1530       option too see all the internal activities.
1531
1532       See "COMMANDLINE OPTIONS" and "DEVSCRIPT CONFIGURATION VARIABLES" for
1533       other variations.
1534
1535   Custom script
1536       The optional script parameter in debian/watch means to execute script
1537       with options after processing this line if specified.
1538
1539       See "HISTORY AND UPGRADING" for how uscan invokes the custom script.
1540
1541       For compatibility with other tools such as git-buildpackage, it may not
1542       be wise to create custom scripts with random behavior.  In general,
1543       uupdate is the best choice for the non-native package and custom
1544       scripts, if created, should behave as if uupdate.  For possible use
1545       case, see <http://bugs.debian.org/748474> as an example.
1546
1547   URL diversion
1548       Some popular web sites changed their web page structure causing
1549       maintenance problems to the watch file.  There are some redirection
1550       services created to ease maintenance of the watch file.  Currently,
1551       uscan makes automatic diversion of URL requests to the following URLs
1552       to cope with this situation.
1553
1554       ·   <http://sf.net>
1555
1556       ·   <http://pypi.python.org>
1557
1558   Directory name checking
1559       Similarly to several other scripts in the devscripts package, uscan
1560       explores the requested directory trees looking for debian/changelog and
1561       debian/watch files. As a safeguard against stray files causing
1562       potential problems, and in order to promote efficiency, it will examine
1563       the name of the parent directory once it finds the debian/changelog
1564       file, and check that the directory name corresponds to the package
1565       name. It will only attempt to download newer versions of the package
1566       and then perform any requested action if the directory name matches the
1567       package name. Precisely how it does this is controlled by two
1568       configuration file variables DEVSCRIPTS_CHECK_DIRNAME_LEVEL and
1569       DEVSCRIPTS_CHECK_DIRNAME_REGEX, and their corresponding command-line
1570       options --check-dirname-level and --check-dirname-regex.
1571
1572       DEVSCRIPTS_CHECK_DIRNAME_LEVEL can take the following values:
1573
1574       0   Never check the directory name.
1575
1576       1   Only check the directory name if we have had to change directory in
1577           our search for debian/changelog, that is, the directory containing
1578           debian/changelog is not the directory from which uscan was invoked.
1579           This is the default behavior.
1580
1581       2   Always check the directory name.
1582
1583       The directory name is checked by testing whether the current directory
1584       name (as determined by pwd(1)) matches the regex given by the
1585       configuration file option DEVSCRIPTS_CHECK_DIRNAME_REGEX or by the
1586       command line option --check-dirname-regex regex. Here regex is a Perl
1587       regex (see perlre(3perl)), which will be anchored at the beginning and
1588       the end. If regex contains a /, then it must match the full directory
1589       path. If not, then it must match the full directory name. If regex
1590       contains the string package, this will be replaced by the source
1591       package name, as determined from the debian/changelog. The default
1592       value for the regex is: package(-.+)?, thus matching directory names
1593       such as package and package-version.
1594

HISTORY AND UPGRADING

1596       This section briefly describes the backwards-incompatible watch file
1597       features which have been added in each watch file version, and the
1598       first version of the devscripts package which understood them.
1599
1600       Pre-version 2
1601           The watch file syntax was significantly different in those days.
1602           Don't use it.  If you are upgrading from a pre-version 2 watch
1603           file, you are advised to read this manpage and to start from
1604           scratch.
1605
1606       Version 2
1607           devscripts version 2.6.90: The first incarnation of the current
1608           style of watch files.
1609
1610       Version 3
1611           devscripts version 2.8.12: Introduced the following: correct
1612           handling of regex special characters in the path part,
1613           directory/path pattern matching, version number in several parts,
1614           version number mangling. Later versions have also introduced URL
1615           mangling.
1616
1617           If you are upgrading from version 2, the key incompatibility is if
1618           you have multiple groups in the pattern part; whereas only the
1619           first one would be used in version 2, they will all be used in
1620           version 3. To avoid this behavior, change the non-version-number
1621           groups to be (?:  ... ) instead of a plain (  ...  ) group.
1622
1623           ·   uscan invokes the custom script as "script --upstream-version
1624               version ../spkg_version.orig.tar.gz".
1625
1626           ·   uscan invokes the standard uupdate as "uupdate --no-symlink
1627               --upstream-version version ../spkg_version.orig.tar.gz".
1628
1629       Version 4
1630           devscripts version 2.15.10: The first incarnation of watch files
1631           supporting multiple upstream tarballs.
1632
1633           The syntax of the watch file is relaxed to allow more spaces for
1634           readability.
1635
1636           If you have a custom script in place of uupdate, you may also
1637           encounter problems updating from Version 3.
1638
1639           ·   uscan invokes the custom script as "script --upstream-version
1640               version".
1641
1642           ·   uscan invokes the standard uupdate as "uupdate --find
1643               --upstream-version version".
1644
1645           Restriction for --dehs is lifted by redirecting other output to
1646           STDERR when it is activated.
1647

SEE ALSO

1649       dpkg(1), mk-origtargz(1), perlre(1), uupdate(1), devscripts.conf(5)
1650

AUTHOR

1652       The original version of uscan was written by Christoph Lameter
1653       <clameter@debian.org>. Significant improvements, changes and bugfixes
1654       were made by Julian Gilbey <jdg@debian.org>. HTTP support was added by
1655       Piotr Roszatycki <dexter@debian.org>. The program was rewritten in Perl
1656       by Julian Gilbey. Xavier Guimard converted it in object-oriented Perl
1657       using Moo.
1658
1659
1660
1661Debian Utilities                  2019-02-12                          USCAN(1)
Impressum