1#!/usr/bin/perl 2# -*- tab-width: 8; indent-tabs-mode: t; cperl-indent-level: 4 -*- 3# vim: set ai shiftwidth=4 tabstop=4 expandtab: 4 5# uscan: This program looks for watch files and checks upstream ftp sites 6# for later versions of the software. 7# 8# Originally written by Christoph Lameter <clameter@debian.org> (I believe) 9# Modified by Julian Gilbey <jdg@debian.org> 10# HTTP support added by Piotr Roszatycki <dexter@debian.org> 11# Rewritten in Perl, Copyright 2002-2006, Julian Gilbey 12# Rewritten in Object Oriented Perl, copyright 2018, Xavier Guimard 13# <yadd@debian.org> 14# 15# This program is free software; you can redistribute it and/or modify 16# it under the terms of the GNU General Public License as published by 17# the Free Software Foundation; either version 2 of the License, or 18# (at your option) any later version. 19# 20# This program is distributed in the hope that it will be useful, 21# but WITHOUT ANY WARRANTY; without even the implied warranty of 22# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 23# GNU General Public License for more details. 24# 25# You should have received a copy of the GNU General Public License 26# along with this program. If not, see <https://www.gnu.org/licenses/>. 27 28####################################################################### 29# {{{ code 0: POD for manpage 30####################################################################### 31 32=pod 33 34=head1 NAME 35 36uscan - scan/watch upstream sources for new releases of software 37 38=head1 SYNOPSIS 39 40B<uscan> [I<options>] [I<path>] 41 42=head1 DESCRIPTION 43 44For basic usage, B<uscan> is executed without any arguments from the root 45of the Debianized source tree where you see the F<debian/> directory, or 46a directory containing multiple source trees. 47 48Unless --watchfile is given, B<uscan> looks recursively for valid source 49trees starting from the current directory (see the below section 50L<Directory name checking> for details). 51 52For each valid source tree found, typically the following happens: 53 54=over 55 56=item * B<uscan> reads the first entry in F<debian/changelog> to determine the 57source package name I<< <spkg> >> and the last upstream version. 58 59=item * B<uscan> process the watch lines F<debian/watch> from the top to the 60bottom in a single pass. 61 62=over 63 64=item * B<uscan> downloads a web page from the specified I<URL> in 65F<debian/watch>. 66 67=item * B<uscan> extracts hrefs pointing to the upstream tarball(s) from the 68web page using the specified I<matching-pattern> in F<debian/watch>. 69 70=item * B<uscan> downloads the upstream tarball with the highest version newer 71than the last upstream version. 72 73=item * B<uscan> saves the downloaded tarball to the parent B<../> directory: 74I<< ../<upkg>-<uversion>.tar.gz >> 75 76=item * B<uscan> invokes B<mk-origtargz> to create the source tarball: I<< 77../<spkg>_<oversion>.orig.tar.gz >> 78 79=over 80 81=item * For a multiple upstream tarball (MUT) package, the secondary upstream 82tarball will instead be named I<< ../<spkg>_<oversion>.orig-<component>.tar.gz >>. 83 84=back 85 86=item * Repeat until all lines in F<debian/watch> are processed. 87 88=back 89 90=item * B<uscan> invokes B<uupdate> to create the Debianized source tree: I<< 91../<spkg>-<oversion>/* >> 92 93=back 94 95Please note the following. 96 97=over 98 99=item * For simplicity, the compression method used in examples is B<gzip> with 100B<.gz> suffix. Other methods such as B<xz>, B<bzip2>, and B<lzma> with 101corresponding B<xz>, B<bz2>, and B<lzma> suffixes may also be used. 102 103=item * The new B<version=4> enables handling of multiple upstream tarball 104(MUT) packages but this is a rare case for Debian packaging. For a single 105upstream tarball package, there is only one watch line and no I<< 106../<spkg>_<oversion>.orig-<component>.tar.gz >> . 107 108=item * B<uscan> with the B<--verbose> option produces a human readable report 109of B<uscan>'s execution. 110 111=item * B<uscan> with the B<--debug> option produces a human readable report of 112B<uscan>'s execution including internal variable states. 113 114=item * B<uscan> with the B<--extra-debug> option produces a human readable 115report of B<uscan>'s execution including internal variable states and remote 116content during "search" step. 117 118=item * B<uscan> with the B<--dehs> option produces an upstream package status 119report in XML format for other programs such as the Debian External Health 120System. 121 122=item * The primary objective of B<uscan> is to help identify if the latest 123version upstream tarball is used or not; and to download the latest upstream 124tarball. The ordering of versions is decided by B<dpkg --compare-versions>. 125 126=item * B<uscan> with the B<--safe> option limits the functionality of B<uscan> 127to its primary objective. Both the repacking of downloaded files and 128updating of the source tree are skipped to avoid running unsafe scripts. 129This also changes the default to B<--no-download> and B<--skip-signature>. 130 131=back 132 133=head1 FORMAT OF THE WATCH FILE 134 135The current version 4 format of F<debian/watch> can be summarized as follows: 136 137=over 138 139=item * Leading spaces and tabs are dropped. 140 141=item * Empty lines are dropped. 142 143=item * A line started by B<#> (hash) is a comment line and dropped. 144 145=item * A single B<\> (back slash) at the end of a line is dropped and the 146next line is concatenated after removing leading spaces and tabs. The 147concatenated line is parsed as a single line. (The existence or non-existence 148of the space before the tailing single B<\> is significant.) 149 150=item * The first non-comment line is: 151 152=over 153 154=item B<version=4> 155 156=back 157 158This is a required line and the recommended version number. 159 160If you use "B<version=3>" instead here, some features may not work as 161documented here. See L<HISTORY AND UPGRADING>. 162 163=item * The following non-comment lines (watch lines) specify the rules for the 164selection of the candidate upstream tarball URLs and are in one of the 165following three formats: 166 167=over 168 169=item * B<opts="> I<...> B<"> B<http://>I<URL> I<matching-pattern> [I<version> [I<script>]] 170 171=item * B<http://>I<URL> I<matching-pattern> [I<version> [I<script>]] 172 173=item * B<opts="> I<...> B<"> 174 175=back 176 177Here, 178 179=over 180 181=item * B<opts="> I<...> B<"> specifies the behavior of B<uscan>. See L<WATCH 182FILE OPTIONS>. 183 184=item * B<http://>I<URL> specifies the web page where upstream publishes 185the link to the latest source archive. 186 187=over 188 189=item * B<https://>I<URL> may also be used, as may 190 191=item * B<ftp://>I<URL> 192 193=item * Some parts of I<URL> may be in the regex match pattern surrounded 194between B<(> and B<)> such as B</foo/bar-([\.\d]+)/>. (If multiple 195directories match, the highest version is picked.) Otherwise, the I<URL> 196is taken as verbatim. 197 198=back 199 200=item * I<matching-pattern> specifies the full string matching pattern for 201hrefs in the web page. See L<WATCH FILE EXAMPLES>. 202 203=over 204 205=item * All matching parts in B<(> and B<)> are concatenated with B<.> (period) 206to form the upstream version. 207 208=item * If the hrefs do not contain directories, you can combine this with the 209previous entry. I.e., B<http://>I<URL>B</>I<matching-pattern> . 210 211=back 212 213=item * I<version> restricts the upstream tarball which may be downloaded. 214The newest available version is chosen in each case. 215 216=over 217 218=item * B<debian> I<(default)> requires the downloading upstream tarball to be 219newer than the version obtained from F<debian/changelog>. 220 221=item * I<version-number> such as B<12.5> requires the upstream 222tarball to be newer than the I<version-number>. 223 224=item * B<same> requires the downloaded version of the secondary tarballs to be 225exactly the same as the one for the first upstream tarball downloaded. (Useful 226only for MUT) 227 228=item * B<previous> restricts the version of the signature 229file. (Used with pgpmode=previous) 230 231=item * B<ignore> does not restrict the version of the secondary 232tarballs. (Maybe useful for MUT) 233 234=item * B<group> requires the downloading upstream tarball to be newer than 235the version obtained from F<debian/changelog>. Package version is the 236concatenation of all "group" upstream version. 237 238=item * B<checksum> requires the downloading upstream tarball to be newer than 239the version obtained from F<debian/changelog>. Package version is the 240concatenation of the version of the main tarball, followed by a checksum of all 241the tarballs using the "checksum" version system. 242At least the main upstream source has to be declared as "group". 243 244=back 245 246=item * I<script> is executed at the end of B<uscan> execution with appropriate 247arguments provided by B<uscan> I<(default: no action)>. 248 249=over 250 251=item * The typical Debian package is a non-native package made from one 252upstream tarball. Only a single line of the watch line in one of the first two 253formats is usually used with its I<version> set to B<debian> and I<script> 254set to B<uupdate>. 255 256=item * A native package should not specify I<script>. 257 258=item * A multiple upstream tarball (MUT) package should specify B<uupdate> 259as I<script> in the last watch line and should skip specifying I<script> in the 260rest of the watch lines. 261 262=back 263 264=item * The last format of the watch line is useful to set the persistent 265parameters: B<user-agent>, B<compression>. If this format is used, this must 266be followed by the I<URL> defining watch line(s). 267 268=item * [ and ] in the above format are there to mark the optional parts and 269should not be typed. 270 271=back 272 273=back 274 275There are a few special strings which are substituted by B<uscan> to make it easy 276to write the watch file. 277 278=over 279 280=item B<@PACKAGE@> 281 282This is substituted with the source package name found in the first line of the 283F<debian/changelog> file. 284 285=item B<@ANY_VERSION@> 286 287This is substituted by the legal upstream version regex (capturing). 288 289 [-_]?(\d[\-+\.:\~\da-zA-Z]*) 290 291=item B<@ARCHIVE_EXT@> 292 293This is substituted by the typical archive file extension regex (non-capturing). 294 295 (?i)\.(?:tar\.xz|tar\.bz2|tar\.gz|zip|tgz|tbz|txz) 296 297=item B<@SIGNATURE_EXT@> 298 299This is substituted by the typical signature file extension regex (non-capturing). 300 301 (?i)\.(?:tar\.xz|tar\.bz2|tar\.gz|zip|tgz|tbz|txz)\.(?:asc|pgp|gpg|sig|sign) 302 303=item B<@DEB_EXT@> 304 305This is substituted by the typical Debian extension regexp (capturing). 306 307 [\+~](debian|dfsg|ds|deb)(\.)?(\d+)?$ 308 309=back 310 311Some file extensions are not included in the above intentionally to avoid false 312positives. You can still set such file extension patterns manually. 313 314=head1 WATCH FILE OPTIONS 315 316B<uscan> reads the watch options specified in B<opts="> I<...> B<"> to 317customize its behavior. Multiple options I<option1>, I<option2>, I<option3>, 318... can be set as B<opts=">I<option1>B<,> I<option2>B<,> I<option3>B<,> I< ... 319>B<"> . The double quotes are necessary if options contain any spaces. 320 321Unless otherwise noted as persistent, most options are valid only within their 322containing watch line. 323 324The available watch options are: 325 326=over 327 328=item B<component=>I<component> 329 330Set the name of the secondary source tarball as I<< 331<spkg>_<oversion>.orig-<component>.tar.gz >> for a MUT package. 332 333=item B<ctype=>I<component-type> 334 335Set the type of component I<(only "nodejs" and "perl" are available for now)>. 336This will help uscan to find current version if component version is ignored. 337 338When using B<ctype=nodejs>, uscan tries to find a version in C<package.json>, 339when using B<ctype=perl>, uscan tries to find a version in C<META.json>. 340If a version is found, it is used as current version for this component, 341regardless version found in Debian version string. This permits a better 342change detection when using I<ignore> or I<checksum> as Debian version. 343 344=item B<compression=>I<method> 345 346Set the compression I<method> when the tarball is repacked (persistent). 347 348Available I<method> values are what mk-origtargz supports, so B<xz>, B<gzip> 349(alias B<gz>), B<bzip2> (alias B<bz2>), B<lzma>, B<default>. The default method 350is currently B<xz>. 351When uscan is launched in a debian source repository which format is "1.0" or 352undefined, the method switches to B<gzip>. 353 354Please note the repacking of the upstream tarballs by B<mk-origtargz> happens 355only if one of the following conditions is satisfied: 356 357=over 358 359=item * B<USCAN_REPACK> is set in the devscript configuration. See L<DEVSCRIPT 360CONFIGURATION VARIABLES>. 361 362=item * B<--repack> is set on the commandline. See <COMMANDLINE OPTIONS>. 363 364=item * B<repack> is set in the watch line as B<opts="repack,>I<...>B<">. 365 366=item * The upstream archive is of B<zip> type including B<jar>, B<xpi>, ... 367 368=item * B<Files-Excluded> or B<Files-Excluded->I<component> stanzas are set in 369F<debian/copyright> to make B<mk-origtargz> invoked from B<uscan> remove 370files from the upstream tarball and repack it. See L<COPYRIGHT FILE 371EXAMPLES> and mk-origtargz(1). 372 373=back 374 375=item B<repack> 376 377Force repacking of the upstream tarball using the compression I<method>. 378 379=item B<repacksuffix=>I<suffix> 380 381Add I<suffix> to the Debian package upstream version only when the 382source tarball is repackaged. This rule should be used only for a single 383upstream tarball package. 384 385=item B<mode=>I<mode> 386 387Set the archive download I<mode>. 388 389=over 390 391=item B<LWP> 392 393This mode is the default one which downloads the specified tarball from the 394archive URL on the web. Automatically internal B<mode> value is updated to 395either B<http> or B<ftp> by URL. 396 397=item B<git> 398 399This mode accesses the upstream git archive directly with the B<git> command 400and packs the source tree with the specified tag via I<matching-pattern> into 401I<spkg-version>B<.tar.xz>. 402 403If the upstream publishes the released tarball via its web interface, please 404use it instead of using this mode. This mode is the last resort method. 405 406For git mode, I<matching-pattern> specifies the full string matching pattern for 407tags instead of hrefs. If I<matching-pattern> is set to 408B<refs/tags/>I<tag-matching-pattern>, B<uscan> downloads source from the 409B<refs/tags/>I<matched-tag> of the git repository. The upstream version is 410extracted from concatenating the matched parts in B<(> ... B<)> with B<.> . See 411L<WATCH FILE EXAMPLES>. 412 413If I<matching-pattern> is set to B<HEAD>, B<uscan> downloads source from the 414B<HEAD> of the git repository and the pertinent I<version> is automatically 415generated with the date and hash of the B<HEAD> of the git repository. 416 417If I<matching-pattern> is set to B<refs/heads/>I<branch>, B<uscan> downloads source 418from the named I<branch> of the git repository. 419 420The local repository is temporarily created as a bare git repository directory 421under the destination directory where the downloaded archive is generated. This 422is normally erased after the B<uscan> execution. This local repository is kept 423if B<--debug> option is used. 424 425If the current directory is a git repository and the searched repository is 426listed among the registered "remotes", then uscan will use it instead of cloning 427separately. The only local change is that uscan will run a "fetch" command to 428refresh the repository. 429 430=item B<svn> 431 432This mode accesses the upstream Subversion archive directly with the B<svn> 433command and packs the source tree. 434 435For svn mode, I<matching-pattern> specifies the full string matching pattern for 436directories under Subversion repository directory, specified via URL. The 437upstream version is extracted from concatenating the matched parts in B<(> ... 438B<)> with B<.> . 439 440If I<matching-pattern> is set to B<HEAD>, B<uscan> downloads the latest source 441tree of the URL. The upstream version is then constructed by appending the last 442revision of the URL to B<0.0~svn>. 443 444As commit signing is not possible with Subversion, the default B<pgpmode> is set 445to B<none> when B<mode=svn>. Settings of B<pgpmode> other than B<default> and 446B<none> are reported as errors. 447 448=back 449 450=item B<pretty=>I<rule> 451 452Set the upstream version string to an arbitrary format as an optional B<opts> 453argument when the I<matching-pattern> is B<HEAD> or B<heads/>I<branch> for 454B<git> mode. For the exact syntax, see the B<git-log> manpage under B<tformat>. 455The default is B<pretty=0.0~git%cd.%h>. No B<uversionmangle> rules is 456applicable for this case. 457 458When B<pretty=describe> is used, the upstream version string is the output of 459the "B<git describe --tags | sed s/-/./g>" command instead. For example, if the 460commit is the B<5>-th after the last tag B<v2.17.12> and its short hash is 461B<ged992511>, then the string is B<v2.17.12.5.ged992511> . For this case, it is 462good idea to add B<uversionmangle=s/^/0.0~/> or B<uversionmangle=s/^v//> to make 463the upstream version string compatible with Debian. B<uversionmangle=s/^v//> 464may work as well. Please note that in order for B<pretty=describe> to function 465well, upstream need to avoid tagging with random alphabetic tags. 466 467The B<pretty=describe> forces to set B<gitmode=full> to make a full local clone 468of the repository automatically. 469 470=item B<date=>I<rule> 471 472Set the date string used by the B<pretty> option to an arbitrary format as an 473optional B<opts> argument when the I<matching-pattern> is B<HEAD> or 474B<heads/>I<branch> for B<git> mode. For the exact syntax, see the 475B<strftime> manpage. The default is B<date=%Y%m%d>. 476 477=item B<gitexport=>I<mode> 478 479Set the git archive export operation I<mode>. The default is 480B<gitexport=default>. Set this to B<gitexport=all> to include all files in the 481.orig.tar archive, ignoring any I<export-ignore> git attributes defined by the 482upstream. 483 484This option is valid only in git mode. 485 486=item B<gitmode=>I<mode> 487 488Set the git clone operation I<mode>. The default is B<gitmode=shallow>. For 489some dumb git server, you may need to manually set B<gitmode=full> to force full 490clone operation. 491 492If the current directory is a git repository and the searched repository is 493listed among the registered "remotes", then uscan will use it instead of cloning 494separately. 495 496=item B<pgpmode=>I<mode> 497 498Set the PGP/GPG signature verification I<mode>. 499 500=over 501 502=item B<auto> 503 504B<uscan> checks possible URLs for the signature file and autogenerates a 505B<pgpsigurlmangle> rule to use it. 506 507=item B<default> 508 509Use B<pgpsigurlmangle=>I<rules> to generate the candidate upstream signature 510file URL string from the upstream tarball URL. (default) 511 512If the specified B<pgpsigurlmangle> is missing, B<uscan> checks possible URLs 513for the signature file and suggests adding a B<pgpsigurlmangle> rule. 514 515=item B<mangle> 516 517Use B<pgpsigurlmangle=>I<rules> to generate the candidate upstream signature 518file URL string from the upstream tarball URL. 519 520=item B<next> 521 522Verify this downloaded tarball file with the signature file specified in the 523next watch line. The next watch line must be B<pgpmode=previous>. Otherwise, 524no verification occurs. 525 526=item B<previous> 527 528Verify the downloaded tarball file specified in the previous watch line with 529this signature file. The previous watch line must be B<pgpmode=next>. 530 531=item B<self> 532 533Verify the downloaded file I<foo.ext> with its self signature and extract its 534content tarball file as I<foo>. 535 536=item B<gittag> 537 538Verify tag signature if B<mode=git>. 539 540=item B<none> 541 542No signature available. (No warning.) 543 544=back 545 546=item B<searchmode=>I<mode> 547 548Set the parsing search mode. 549 550=over 551 552=item B<html> I<(default)>: search pattern in "href" parameter of E<lt>aE<gt> 553HTML tags 554 555=item B<plain>: search pattern in the full page 556 557This is useful if page content is not HTML but JSON. Example with 558npmjs.com: 559 560 version=4 561 opts="searchmode=plain" \ 562 https://registry.npmjs.org/aes-js \ 563 https://registry.npmjs.org/aes-js/-/aes-js-(\d[\d\.]*)@ARCHIVE_EXT@ 564 565=back 566 567=item B<decompress> 568 569Decompress compressed archive before the pgp/gpg signature verification. 570 571=item B<bare> 572 573Disable all site specific special case code such as URL redirector uses and 574page content alterations. (persistent) 575 576=item B<user-agent=>I<user-agent-string> 577 578Set the user-agent string used to contact the HTTP(S) server as 579I<user-agent-string>. (persistent) 580 581B<user-agent> option should be specified by itself in the watch line without 582I<URL>, to allow using semicolons and commas in it. 583 584=item B<pasv>, B<passive> 585 586Use PASV mode for the FTP connection. 587 588If PASV mode is required due to the client side network environment, set 589B<uscan> to use PASV mode via L<COMMANDLINE OPTIONS> or L<DEVSCRIPT 590CONFIGURATION VARIABLES> instead. 591 592=item B<active>, B<nopasv> 593 594Don't use PASV mode for the FTP connection. 595 596=item B<unzipopt=>I<options> 597 598Add the extra options to use with the B<unzip> command, such as B<-a>, B<-aa>, 599and B<-b>, when executed by B<mk-origtargz>. 600 601=item B<dversionmangle=>I<rules> 602 603Normalize the last upstream version string found in F<debian/changelog> to 604compare it to the available upstream tarball version. Removal of the Debian 605specific suffix such as B<s/@DEB_EXT@//> is usually done here. 606 607You can also use B<dversionmangle=auto>, this is exactly the same than 608B<dversionmangle=s/@DEB_EXT@//> 609 610=item B<dirversionmangle=>I<rules> 611 612Normalize the directory path string matching the regex in a set of parentheses 613of B<http://>I<URL> as the sortable version index string. This is used as the 614directory path sorting index only. 615 616Substitution such as B<s/PRE/~pre/; s/RC/~rc/> may help. 617 618=item B<pagemangle=>I<rules> 619 620Normalize the downloaded web page string. (Don't use this unless this is 621absolutely needed. Generally, B<g> flag is required for these I<rules>.) 622 623This is handy if you wish to access Amazon AWS or Subversion repositories in 624which <a href="..."> is not used. 625 626=item B<uversionmangle=>I<rules> 627 628Normalize the candidate upstream version strings extracted from hrefs in the 629source of the web page. This is used as the version sorting index when 630selecting the latest upstream version. 631 632Substitution such as B<s/PRE/~pre/; s/RC/~rc/> may help. 633 634=item B<versionmangle=>I<rules> 635 636Syntactic shorthand for B<uversionmangle=>I<rules>B<, dversionmangle=>I<rules> 637 638=item B<hrefdecode=percent-encoding> 639 640Convert the selected upstream tarball href string from the percent-encoded 641hexadecimal string to the decoded normal URL string for obfuscated web sites. 642Only B<percent-encoding> is available and it is decoded with 643B<s/%([A-Fa-f\d]{2})/chr hex $1/eg>. 644 645=item B<downloadurlmangle=>I<rules> 646 647Convert the selected upstream tarball href string into the accessible URL for 648obfuscated web sites. This is run after B<hrefdecode>. 649 650=item B<filenamemangle=>I<rules> 651 652Generate the upstream tarball filename from the selected href string if 653I<matching-pattern> can extract the latest upstream version I<< <uversion> >> 654from the selected href string. Otherwise, generate the upstream tarball 655filename from its full URL string and set the missing I<< <uversion> >> from 656the generated upstream tarball filename. 657 658Without this option, the default upstream tarball filename is generated by 659taking the last component of the URL and removing everything after any '?' or 660'#'. 661 662=item B<pgpsigurlmangle=>I<rules> 663 664Generate the candidate upstream signature file URL string from the upstream 665tarball URL. 666 667=item B<oversionmangle=>I<rules> 668 669Generate the version string I<< <oversion> >> of the source tarball I<< 670<spkg>_<oversion>.orig.tar.gz >> from I<< <uversion> >>. This should be used 671to add a suffix such as B<+dfsg1> to a MUT package. 672 673=back 674 675Here, the mangling rules apply the I<rules> to the pertinent string. Multiple 676rules can be specified in a mangling rule string by making a concatenated 677string of each mangling I<rule> separated by B<;> (semicolon). 678 679Each mangling I<rule> cannot contain B<;> (semicolon), B<,> (comma), or B<"> 680(double quote). 681 682Each mangling I<rule> behaves as if a Perl command "I<$string> B<=~> I<rule>" 683is executed. There are some notable details. 684 685=over 686 687=item * I<rule> may only use the B<s>, B<tr>, and B<y> operations. 688 689=over 690 691=item B<s/>I<regex>B</>I<replacement>B</>I<options> 692 693Regex pattern match and replace the target string. Only the B<g>, B<i> and 694B<x> flags are available. Use the B<$1> syntax for back references (No 695B<\1> syntax). Code execution is not allowed (i.e. no B<(?{})> or B<(??{})> 696constructs). 697 698=item B<y/>I<source>B</>I<dest>B</> or B<tr/>I<source>B</>I<dest>B</> 699 700Transliterate the characters in the target string. 701 702=back 703 704=back 705 706=head1 EXAMPLE OF EXECUTION 707 708B<uscan> reads the first entry in F<debian/changelog> to determine the source 709package name and the last upstream version. 710 711For example, if the first entry of F<debian/changelog> is: 712 713=over 714 715=item * I<< bar >> (B<3:2.03+dfsg1-4>) unstable; urgency=low 716 717=back 718 719then, the source package name is I<< bar >> and the last Debian package version 720is B<3:2.03+dfsg1-4>. 721 722The last upstream version is normalized to B<2.03+dfsg1> by removing the epoch 723and the Debian revision. 724 725If the B<dversionmangle> rule exists, the last upstream version is further 726normalized by applying this rule to it. For example, if the last upstream 727version is B<2.03+dfsg1> indicating the source tarball is repackaged, the 728suffix B<+dfsg1> is removed by the string substitution B<s/\+dfsg\d*$//> to 729make the (dversionmangled) last upstream version B<2.03> and it is compared to 730the candidate upstream tarball versions such as B<2.03>, B<2.04>, ... found in 731the remote site. Thus, set this rule as: 732 733=over 734 735=item * B<opts="dversionmangle=s/\+dfsg\d*$//"> 736 737=back 738 739B<uscan> downloads a web page from B<http://>I<URL> specified in 740F<debian/watch>. 741 742=over 743 744=item * If the directory name part of I<URL> has no parentheses, B<(> and B<)>, 745it is taken as verbatim. 746 747=item * If the directory name part of I<URL> has parentheses, B<(> and B<)>, 748then B<uscan> recursively searches all possible directories to find a page for 749the newest version. If the B<dirversionmangle> rule exists, the generated 750sorting index is used to find the newest version. If a specific version is 751specified for the download, the matching version string has priority over the 752newest version. 753 754=back 755 756For example, this B<http://>I<URL> may be specified as: 757 758=over 759 760=item * B<http://www.example.org/([\d\.]+)/> 761 762=back 763 764Please note the trailing B</> in the above to make B<([\d\.]+)> as the 765directory. 766 767If the B<pagemangle> rule exists, the whole downloaded web page as a string is 768normalized by applying this rule to it. This is very powerful tool and needs 769to be used with caution. If other mangling rules can be used to address your 770objective, do not use this rule. 771 772The downloaded web page is scanned for hrefs defined in the B<< <a href=" >> 773I<...> B<< "> >> tag to locate the candidate upstream tarball hrefs. These 774candidate upstream tarball hrefs are matched by the Perl regex pattern 775I<matching-pattern> such as B<< DL-(?:[\d\.]+?)/foo-(.+)\.tar\.gz >> to narrow 776down the candidates. This pattern match needs to be anchored at the beginning 777and the end. For example, candidate hrefs may be: 778 779=over 780 781=item * B<< DL-2.02/foo-2.02.tar.gz >> 782 783=item * B<< DL-2.03/foo-2.03.tar.gz >> 784 785=item * B<< DL-2.04/foo-2.04.tar.gz >> 786 787=back 788 789Here the matching string of B<(.+)> in I<matching-pattern> is considered as the 790candidate upstream version. If there are multiple matching strings of 791capturing patterns in I<matching-pattern>, they are all concatenated with B<.> 792(period) to form the candidate upstream version. Make sure to use the 793non-capturing regex such as B<(?:[\d\.]+?)> instead for the variable text 794matching part unrelated to the version. 795 796Then, the candidate upstream versions are: 797 798=over 799 800=item * B<2.02> 801 802=item * B<2.03> 803 804=item * B<2.04> 805 806=back 807 808The downloaded tarball filename is basically set to the same as the filename in 809the remote URL of the selected href. 810 811If the B<uversionmangle> rule exists, the candidate upstream versions are 812normalized by applying this rule to them. (This rule may be useful if the 813upstream version scheme doesn't sort correctly to identify the newest version.) 814 815The upstream tarball href corresponding to the newest (uversionmangled) 816candidate upstream version newer than the (dversionmangled) last upstream 817version is selected. 818 819If multiple upstream tarball hrefs corresponding to a single version with 820different extensions exist, the highest compression one is chosen. (Priority: 821B<< tar.xz > tar.lzma > tar.bz2 > tar.gz >>.) 822 823If the selected upstream tarball href is the relative URL, it is converted to 824the absolute URL using the base URL of the web page. If the B<< <base href=" 825>> I< ... > B<< "> >> tag exists in the web page, the selected upstream tarball 826href is converted to the absolute URL using the specified base URL in the base 827tag, instead. 828 829If the B<downloadurlmangle> rule exists, the selected upstream tarball href is 830normalized by applying this rule to it. (This is useful for some sites with the 831obfuscated download URL.) 832 833If the B<filenamemangle> rule exists, the downloaded tarball filename is 834generated by applying this rule to the selected href if I<matching-pattern> can 835extract the latest upstream version I<< <uversion> >> from the selected href 836string. Otherwise, generate the upstream tarball filename from its full URL 837string and set the missing I<< <uversion> >> from the generated upstream 838tarball filename. 839 840Without the B<filenamemangle> rule, the default upstream tarball filename is 841generated by taking the last component of the URL and removing everything after 842any '?' or '#'. 843 844B<uscan> downloads the selected upstream tarball to the parent B<../> 845directory. For example, the downloaded file may be: 846 847=over 848 849=item * F<../foo-2.04.tar.gz> 850 851=back 852 853Let's call this downloaded version B<2.04> in the above example generically as 854I<< <uversion> >> in the following. 855 856If the B<pgpsigurlmangle> rule exists, the upstream signature file URL is 857generated by applying this rule to the (downloadurlmangled) selected upstream 858tarball href and the signature file is tried to be downloaded from it. 859 860If the B<pgpsigurlmangle> rule doesn't exist, B<uscan> warns user if the 861matching upstream signature file is available from the same URL with their 862filename being suffixed by the 5 common suffix B<asc>, B<gpg>, B<pgp>, B<sig> 863and B<sign>. (You can avoid this warning by setting B<pgpmode=none>.) 864 865If the signature file is downloaded, the downloaded upstream tarball is checked 866for its authenticity against the downloaded signature file using the armored keyring 867F<debian/upstream/signing-key.asc> (see L<KEYRING FILE EXAMPLES>). If its 868signature is not valid, or not made by one of the listed keys, B<uscan> will 869report an error. 870 871If the B<oversionmangle> rule exists, the source tarball version I<oversion> is 872generated from the downloaded upstream version I<uversion> by applying this 873rule. This rule is useful to add suffix such as B<+dfsg1> to the version of all 874the source packages of the MUT package for which the repacksuffix mechanism 875doesn't work. 876 877B<uscan> invokes B<mk-origtargz> to create the source tarball properly named 878for the source package with B<.orig.> (or B<< .orig-<component>. >> for the 879secondary tarballs) in its filename. 880 881=over 882 883=item case A: packaging of the upstream tarball as is 884 885B<mk-origtargz> creates a symlink I<< ../bar_<oversion>.orig.tar.gz >> 886linked to the downloaded local upstream tarball. Here, I<< bar >> is the source 887package name found in F<debian/changelog>. The generated symlink may be: 888 889=over 890 891=item * F<../bar_2.04.orig.tar.gz> -> F<foo-2.04.tar.gz> (as is) 892 893=back 894 895Usually, there is no need to set up B<opts="dversionmangle=> I<...> B<"> for 896this case. 897 898=item case B: packaging of the upstream tarball after removing non-DFSG files 899 900B<mk-origtargz> checks the filename glob of the B<Files-Excluded> stanza in the 901first section of F<debian/copyright>, removes matching files to create a 902repacked upstream tarball. Normally, the repacked upstream tarball is renamed 903with I<suffix> to I<< ../bar_<oversion><suffix>.orig.tar.gz >> using 904the B<repacksuffix> option for the single upstream package. Here I<< <oversion> >> 905is updated to be I<< <oversion><suffix> >>. 906 907The removal of files is required if files are not DFSG-compliant. For such 908case, B<+dfsg1> is used as I<suffix>. 909 910So the combined options are set as 911B<opts="dversionmangle=s/\+dfsg\d*$// ,repacksuffix=+dfsg1">, instead. 912 913For example, the repacked upstream tarball may be: 914 915=over 916 917=item * F<../bar_2.04+dfsg1.orig.tar.gz> (repackaged) 918 919=back 920 921=back 922 923B<uscan> normally invokes "B<uupdate> B<--find --upstream-version> I<oversion> 924" for the version=4 watch file. 925 926Please note that B<--find> option is used here since B<mk-origtargz> has been 927invoked to make B<*.orig.tar.gz> file already. B<uscan> picks I<< bar >> from 928F<debian/changelog>. 929 930It creates the new upstream source tree under the I<< ../bar-<oversion> >> 931directory and Debianize it leveraging the last package contents. 932 933=head1 WATCH FILE EXAMPLES 934 935When writing the watch file, you should rely on the latest upstream source 936announcement web page. You should not try to second guess the upstream archive 937structure if possible. Here are the typical F<debian/watch> files. 938 939Please note that executing B<uscan> with B<-v> or B<-vv> reveals what exactly 940happens internally. 941 942The existence and non-existence of a space the before tailing B<\> (back slash) 943are significant. 944 945Some undocumented shorter configuration strings are used in the below EXAMPLES 946to help you with typing. These are intentional ones. B<uscan> is written to 947accept such common sense abbreviations but don't push the limit. 948 949=head2 HTTP site (basic) 950 951Here is an example for the basic single upstream tarball. 952 953 version=4 954 http://example.com/~user/release/foo.html \ 955 files/foo-([\d\.]+)\.tar\.gz debian uupdate 956 957Or using the special strings: 958 959 version=4 960 http://example.com/~user/release/@PACKAGE@.html \ 961 files/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian uupdate 962 963For the upstream source package B<foo-2.0.tar.gz>, this watch file downloads 964and creates the Debian B<orig.tar> file B<foo_2.0.orig.tar.gz>. 965 966=head2 HTTP site (pgpsigurlmangle) 967 968Here is an example for the basic single upstream tarball with the matching 969signature file in the same file path. 970 971 version=4 972 opts="pgpsigurlmangle=s%$%.asc%" http://example.com/release/@PACKAGE@.html \ 973 files/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian uupdate 974 975For the upstream source package B<foo-2.0.tar.gz> and the upstream signature 976file B<foo-2.0.tar.gz.asc>, this watch file downloads these files, verifies the 977authenticity using the keyring F<debian/upstream/signing-key.asc> and creates the 978Debian B<orig.tar> file B<foo_2.0.orig.tar.gz>. 979 980Here is another example for the basic single upstream tarball with the matching 981signature file on decompressed tarball in the same file path. 982 983 version=4 984 opts="pgpsigurlmangle=s%@ARCHIVE_EXT@$%.asc%,decompress" \ 985 http://example.com/release/@PACKAGE@.html \ 986 files/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian uupdate 987 988For the upstream source package B<foo-2.0.tar.gz> and the upstream signature 989file B<foo-2.0.tar.asc>, this watch file downloads these files, verifies the 990authenticity using the keyring F<debian/upstream/signing-key.asc> and creates the 991Debian B<orig.tar> file B<foo_2.0.orig.tar.gz>. 992 993=head2 HTTP site (pgpmode=next/previous) 994 995Here is an example for the basic single upstream tarball with the matching 996signature file in the unrelated file path. 997 998 version=4 999 opts="pgpmode=next" http://example.com/release/@PACKAGE@.html \ 1000 files/(?:\d+)/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian 1001 opts="pgpmode=previous" http://example.com/release/@PACKAGE@.html \ 1002 files/(?:\d+)/@PACKAGE@@ANY_VERSION@@SIGNATURE_EXT@ previous uupdate 1003 1004B<(?:\d+)> part can be any random value. The tarball file can have B<53>, 1005while the signature file can have B<33>. 1006 1007B<([\d\.]+)> part for the signature file has a strict requirement to match that 1008for the upstream tarball specified in the previous line by having B<previous> 1009as I<version> in the watch line. 1010 1011=head2 HTTP site (flexible) 1012 1013Here is an example for the maximum flexibility of upstream tarball and 1014signature file extensions. 1015 1016 version=4 1017 opts="pgpmode=next" http://example.com/DL/ \ 1018 files/(?:\d+)/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian 1019 opts="pgpmode=previous" http://example.com/DL/ \ 1020 files/(?:\d+)/@PACKAGE@@ANY_VERSION@@SIGNATURE_EXT@ \ 1021 previous uupdate 1022 1023=head2 HTTP site (basic MUT) 1024 1025Here is an example for the basic multiple upstream tarballs. 1026 1027 version=4 1028 opts="pgpsigurlmangle=s%$%.sig%" \ 1029 http://example.com/release/foo.html \ 1030 files/foo-([\d\.]+)\.tar\.gz debian 1031 opts="pgpsigurlmangle=s%$%.sig%, component=bar" \ 1032 http://example.com/release/foo.html \ 1033 files/foobar-([\d\.]+)\.tar\.gz same 1034 opts="pgpsigurlmangle=s%$%.sig%, component=baz" \ 1035 http://example.com/release/foo.html \ 1036 files/foobaz-([\d\.]+)\.tar\.gz same uupdate 1037 1038For the main upstream source package B<foo-2.0.tar.gz> and the secondary 1039upstream source packages B<foobar-2.0.tar.gz> and B<foobaz-2.0.tar.gz> which 1040install under F<bar/> and F<baz/>, this watch file downloads and creates the 1041Debian B<orig.tar> file B<foo_2.0.orig.tar.gz>, B<foo_2.0.orig-bar.tar.gz> and 1042B<foo_2.0.orig-baz.tar.gz>. Also, these upstream tarballs are verified by 1043their signature files. 1044 1045=head2 HTTP site (recursive directory scanning) 1046 1047Here is an example with the recursive directory scanning for the upstream tarball 1048and its signature files released in a directory named 1049after their version. 1050 1051 version=4 1052 opts="pgpsigurlmangle=s%$%.sig%, dirversionmangle=s/-PRE/~pre/;s/-RC/~rc/" \ 1053 http://tmrc.mit.edu/mirror/twisted/Twisted/([\d+\.]+)/ \ 1054 Twisted-([\d\.]+)\.tar\.xz debian uupdate 1055 1056Here, the web site should be accessible at the following URL: 1057 1058 http://tmrc.mit.edu/mirror/twisted/Twisted/ 1059 1060Here, B<dirversionmangle> option is used to normalize the sorting order of the 1061directory names. 1062 1063=head2 HTTP site (alternative shorthand) 1064 1065For the bare HTTP site where you can directly see archive filenames, the normal 1066watch file: 1067 1068 version=4 1069 opts="pgpsigurlmangle=s%$%.sig%" \ 1070 http://www.cpan.org/modules/by-module/Text/ \ 1071 Text-CSV_XS-(.+)\.tar\.gz \ 1072 debian uupdate 1073 1074can be rewritten in an alternative shorthand form only with a single string 1075covering URL and filename: 1076 1077 version=4 1078 opts="pgpsigurlmangle=s%$%.sig%" \ 1079 http://www.cpan.org/modules/by-module/Text/Text-CSV_XS-(.+)\.tar\.gz \ 1080 debian uupdate 1081 1082In version=4, initial white spaces are dropped. Thus, this alternative 1083shorthand form can also be written as: 1084 1085 version=4 1086 opts="pgpsigurlmangle=s%$%.sig%" \ 1087 http://www.cpan.org/modules/by-module/Text/\ 1088 Text-CSV_XS-(.+)\.tar\.gz \ 1089 debian uupdate 1090 1091Please note the subtle difference of a space before the tailing B<\> 1092between the first and the last examples. 1093 1094=head2 HTTP site (funny version) 1095 1096For a site which has funny version numbers, the parenthesized groups will be 1097joined with B<.> (period) to make a sanitized version number. 1098 1099 version=4 1100 http://www.site.com/pub/foobar/foobar_v(\d+)_(\d+)\.tar\.gz \ 1101 debian uupdate 1102 1103=head2 HTTP site (DFSG) 1104 1105The upstream part of the Debian version number can be mangled to indicate the 1106source package was repackaged to clean up non-DFSG files: 1107 1108 version=4 1109 opts="dversionmangle=s/\+dfsg\d*$//,repacksuffix=+dfsg1" \ 1110 http://some.site.org/some/path/foobar-(.+)\.tar\.gz debian uupdate 1111 1112See L<COPYRIGHT FILE EXAMPLES>. 1113 1114=head2 HTTP site (filenamemangle) 1115 1116The upstream tarball filename is found by taking the last component of the URL 1117and removing everything after any '?' or '#'. 1118 1119If this does not fit to you, use B<filenamemangle>. For example, F<< <A 1120href="http://foo.bar.org/dl/?path=&dl=foo-0.1.1.tar.gz"> >> could be handled 1121as: 1122 1123 version=4 1124 opts=filenamemangle=s/.*=(.*)/$1/ \ 1125 http://foo.bar.org/dl/\?path=&dl=foo-(.+)\.tar\.gz \ 1126 debian uupdate 1127 1128F<< <A href="http://foo.bar.org/dl/?path=&dl_version=0.1.1"> >> 1129could be handled as: 1130 1131 version=4 1132 opts=filenamemangle=s/.*=(.*)/foo-$1\.tar\.gz/ \ 1133 http://foo.bar.org/dl/\?path=&dl_version=(.+) \ 1134 debian uupdate 1135 1136If the href string has no version using <I>matching-pattern>, the version can 1137be obtained from the full URL using B<filenamemangle>. 1138 1139 version=4 1140 opts=filenamemangle=s&.*/dl/(.*)/foo\.tar\.gz&foo-$1\.tar\.gz& \ 1141 http://foo.bar.org/dl/([\.\d]+)/ foo.tar.gz \ 1142 debian uupdate 1143 1144 1145=head2 HTTP site (downloadurlmangle) 1146 1147The option B<downloadurlmangle> can be used to mangle the URL of the file 1148to download. This can only be used with B<http://> URLs. This may be 1149necessary if the link given on the web page needs to be transformed in 1150some way into one which will work automatically, for example: 1151 1152 version=4 1153 opts=downloadurlmangle=s/prdownload/download/ \ 1154 http://developer.berlios.de/project/showfiles.php?group_id=2051 \ 1155 http://prdownload.berlios.de/softdevice/vdr-softdevice-(.+).tgz \ 1156 debian uupdate 1157 1158=head2 HTTP site (oversionmangle, MUT) 1159 1160The option B<oversionmangle> can be used to mangle the version of the source 1161tarball (B<.orig.tar.gz> and B<.orig-bar.tar.gz>). For example, B<+dfsg1> can 1162be added to the upstream version as: 1163 1164 version=4 1165 opts=oversionmangle=s/(.*)/$1+dfsg1/ \ 1166 http://example.com/~user/release/foo.html \ 1167 files/foo-([\d\.]*).tar.gz debian 1168 opts="component=bar" \ 1169 http://example.com/~user/release/foo.html \ 1170 files/bar-([\d\.]*).tar.gz same uupdate 1171 1172See L<COPYRIGHT FILE EXAMPLES>. 1173 1174=head2 HTTP site (pagemangle) 1175 1176The option B<pagemangle> can be used to mangle the downloaded web page before 1177applying other rules. The non-standard web page without proper B<< <a href=" 1178>> << ... >> B<< "> >> entries can be converted. For example, if F<foo.html> 1179uses B<< <a bogus=" >> I<< ... >> B<< "> >>, this can be converted to the 1180standard page format with: 1181 1182 version=4 1183 opts=pagemangle="s/<a\s+bogus=/<a href=/g" \ 1184 http://example.com/release/foo.html \ 1185 files/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian uupdate 1186 1187Please note the use of B<g> here to replace all occurrences. 1188 1189If F<foo.html> uses B<< <Key> >> I<< ... >> B<< </Key> >>, this can be 1190converted to the standard page format with: 1191 1192 version=4 1193 opts="pagemangle=s%<Key>([^<]*)</Key>%<Key><a href="$1">$1</a></Key>%g" \ 1194 http://example.com/release/foo.html \ 1195 (?:.*)/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian uupdate 1196 1197=head2 FTP site (basic): 1198 1199 version=4 1200 ftp://ftp.tex.ac.uk/tex-archive/web/c_cpp/cweb/cweb-(.+)\.tar\.gz \ 1201 debian uupdate 1202 1203=head2 FTP site (regex special characters): 1204 1205 version=4 1206 ftp://ftp.worldforge.org/pub/worldforge/libs/\ 1207 Atlas-C++/transitional/Atlas-C\+\+-(.+)\.tar\.gz debian uupdate 1208 1209Please note that this URL is connected to be I< ... >B<libs/Atlas-C++/>I< ... > 1210. For B<++>, the first one in the directory path is verbatim while the one in 1211the filename is escaped by B<\>. 1212 1213=head2 FTP site (funny version) 1214 1215This is another way of handling site with funny version numbers, 1216this time using mangling. (Note that multiple groups will be 1217concatenated before mangling is performed, and that mangling will 1218only be performed on the basename version number, not any path 1219version numbers.) 1220 1221 version=4 1222 opts="uversionmangle=s/^/0.0./" \ 1223 ftp://ftp.ibiblio.org/pub/Linux/ALPHA/wine/\ 1224 development/Wine-(.+)\.tar\.gz debian uupdate 1225 1226=head2 sf.net 1227 1228For SourceForge based projects, qa.debian.org runs a redirector which allows a 1229simpler form of URL. The format below will automatically be rewritten to use 1230the redirector with the watch file: 1231 1232 version=4 1233 https://sf.net/<project>/ <tar-name>-(.+)\.tar\.gz debian uupdate 1234 1235For B<audacity>, set the watch file as: 1236 1237 version=4 1238 https://sf.net/audacity/ audacity-minsrc-(.+)\.tar\.gz debian uupdate 1239 1240Please note, you can still use normal functionalities of B<uscan> to set up a 1241watch file for this site without using the redirector. 1242 1243 version=4 1244 opts="uversionmangle=s/-pre/~pre/, \ 1245 filenamemangle=s%(?:.*)audacity-minsrc-(.+)\.tar\.xz/download%\ 1246 audacity-$1.tar.xz%" \ 1247 http://sourceforge.net/projects/audacity/files/audacity/(\d[\d\.]+)/ \ 1248 (?:.*)audacity-minsrc-([\d\.]+)\.tar\.xz/download debian uupdate 1249 1250Here, B<%> is used as the separator instead of the standard B</>. 1251 1252=head2 github.com 1253 1254For GitHub based projects, you can use the tags or releases page. The archive 1255URL uses only the version as the filename. You can rename the downloaded 1256upstream tarball from into the standard F<< <project>-<version>.tar.gz >> using 1257B<filenamemangle>: 1258 1259 version=4 1260 opts="filenamemangle=s%(?:.*?)?v?(\d[\d.]*)\.tar\.gz%@PACKAGE@-$1.tar.gz%" \ 1261 https://github.com/<user>/<project>/tags \ 1262 (?:.*?/)?v?(\d[\d.]*)\.tar\.gz debian uupdate 1263 1264=head2 PyPI 1265 1266For PyPI based projects, pypi.debian.net runs a redirector which allows a 1267simpler form of URL. The format below will automatically be rewritten to use 1268the redirector with the watch file: 1269 1270 version=4 1271 https://pypi.python.org/packages/source/<initial>/<project>/ \ 1272 <tar-name>-(.+)\.tar\.gz debian uupdate 1273 1274For B<cfn-sphere>, set the watch file as: 1275 1276 version=4 1277 https://pypi.python.org/packages/source/c/cfn-sphere/ \ 1278 cfn-sphere-([\d\.]+).tar.gz debian uupdate 1279 1280Please note, you can still use normal functionalities of B<uscan> to set up a 1281watch file for this site without using the redirector. 1282 1283 version=4 1284 opts="pgpmode=none" \ 1285 https://pypi.python.org/pypi/cfn-sphere/ \ 1286 https://pypi.python.org/packages/.*/.*/.*/\ 1287 cfn-sphere-([\d\.]+).tar.gz#.* debian uupdate 1288 1289=head2 code.google.com 1290 1291Sites which used to be hosted on the Google Code service should have migrated 1292to elsewhere (github?). Please look for the newer upstream site if available. 1293 1294=head2 npmjs.org (node modules) 1295 1296npmjs.org modules are published in JSON files. Here is a way to read them: 1297 1298 version=4 1299 opts="searchmode=plain" \ 1300 https://registry.npmjs.org/aes-js \ 1301 https://registry.npmjs.org/aes-js/-/aes-js-(\d[\d\.]*)@ARCHIVE_EXT@ 1302 1303=head2 grouped package 1304 1305Some node modules are split into multiple little upstream package. Here is 1306a way to group them: 1307 1308 version=4 1309 opts="searchmode=plain,pgpmode=none" \ 1310 https://registry.npmjs.org/mongodb \ 1311 https://registry.npmjs.org/mongodb/-/mongodb-(\d[\d\.]*)@ARCHIVE_EXT@ group 1312 opts="searchmode=plain,pgpmode=none,component=bson" \ 1313 https://registry.npmjs.org/bson \ 1314 https://registry.npmjs.org/bson/-/bson-(\d[\d\.]*)@ARCHIVE_EXT@ group 1315 opts="searchmode=plain,pgpmode=none,component=mongodb-core" \ 1316 https://registry.npmjs.org/mongodb-core \ 1317 https://registry.npmjs.org/mongodb-core/-/mongodb-core-(\d[\d\.]*)@ARCHIVE_EXT@ group 1318 opts="searchmode=plain,pgpmode=none,component=requireoptional" \ 1319 https://registry.npmjs.org/require_optional \ 1320 https://registry.npmjs.org/require_optional/-/require_optional-(\d[\d\.]*)@ARCHIVE_EXT@ group 1321 1322Package version is then the concatenation of upstream versions separated by 1323"+~". 1324 1325To avoid having a too long version, the "checksum" method can be used. 1326In this case, the main source has to be declared as "group": 1327 1328 version=4 1329 opts="searchmode=plain,pgpmode=none" \ 1330 https://registry.npmjs.org/mongodb \ 1331 https://registry.npmjs.org/mongodb/-/mongodb-(\d[\d\.]*)@ARCHIVE_EXT@ group 1332 opts="searchmode=plain,pgpmode=none,component=bson" \ 1333 https://registry.npmjs.org/bson \ 1334 https://registry.npmjs.org/bson/-/bson-(\d[\d\.]*)@ARCHIVE_EXT@ checksum 1335 opts="searchmode=plain,pgpmode=none,component=mongodb-core" \ 1336 https://registry.npmjs.org/mongodb-core \ 1337 https://registry.npmjs.org/mongodb-core/-/mongodb-core-(\d[\d\.]*)@ARCHIVE_EXT@ checksum 1338 opts="searchmode=plain,pgpmode=none,component=requireoptional" \ 1339 https://registry.npmjs.org/require_optional \ 1340 https://registry.npmjs.org/require_optional/-/require_optional-(\d[\d\.]*)@ARCHIVE_EXT@ checksum 1341 1342The "checksum" is made up of the separate sum of each number composing the 1343component versions. Following is an example with 3 components whose versions 1344are "1.2.4", "2.0.1" and "10.0", with the main tarball having version "2.0.6": 1345 1346 Main: 2.0.6 1347 Comp1: 1 . 2 . 4 1348 Comp2: 2 . 0 . 1 1349 Comp3: 10 . 0 1350 ================================ 1351 Result : 1+2+10 . 2+0+0 . 4+1 1352 Checksum: 13 . 2 . 5 1353 ================================ 1354 Final Version: 2.0.6+~cs13.2.5 1355 1356uscan will also display the original version string before being encoded into 1357the checksum, which can for example be used in a debian/changelog entry to 1358easily follow the changes: 1359 1360 2.0.6+~1.2.4+~2.0.1+~10.0 1361 1362B<Note>: This feature currently accepts only versions composed of digits and 1363full stops (`.`). 1364 1365=head2 direct access to the git repository (tags) 1366 1367If the upstream only publishes its code via the git repository and its code has 1368no web interface to obtain the release tarball, you can use B<uscan> with the 1369tags of the git repository to track and package the new upstream release. 1370 1371 version=4 1372 opts="mode=git, gitmode=full, pgpmode=none" \ 1373 http://git.ao2.it/tweeper.git \ 1374 refs/tags/v([\d\.]+) debian uupdate 1375 1376Please note "B<git ls-remote>" is used to obtain references for tags. 1377 1378If a tag B<v20.5> is the newest tag, the above example downloads 1379I<spkg>B<-20.5.tar.xz> after making a full clone of the git repository which is 1380needed for dumb git server. 1381 1382If tags are signed, set B<pgpmode=gittag> to verify them. 1383 1384=head2 direct access to the git repository (HEAD) 1385 1386If the upstream only publishes its code via the git repository and its code has 1387no web interface nor the tags to obtain the released tarball, you can use 1388B<uscan> with the HEAD of the git repository to track and package the new 1389upstream release with an automatically generated version string. 1390 1391 version=4 1392 opts="mode=git, pgpmode=none" \ 1393 https://github.com/Debian/dh-make-golang \ 1394 HEAD debian uupdate 1395 1396Please note that a local shallow copy of the git repository is made with "B<git 1397clone --bare --depth=1> ..." normally in the target directory. B<uscan> 1398generates the new upstream version with "B<git log --date=format:%Y%m%d 1399--pretty=0.0~git%cd.%h>" on this local copy of repository as its default 1400behavior. 1401 1402The generation of the upstream version string may the adjusted to your taste by 1403adding B<pretty> and B<date> options to the B<opts> arguments. 1404 1405=head2 direct access to the Subversion repository (tags) 1406 1407If the upstream only publishes its code via the Subversion repository and its 1408code has no web interface to obtain the release tarball, you can use B<uscan> 1409with the tags of the Subversion repository to track and package the new upstream 1410release. 1411 1412 version=4 1413 opts="mode=svn, pgpmode=none" \ 1414 svn://svn.code.sf.net/p/jmol/code/tags/ \ 1415 ([\d.]+)\/ debian uupdate 1416 1417=head2 direct access to the Subversion repository (HEAD) 1418 1419If the upstream only publishes its code via the Subversion repository and its 1420code has no web interface to obtain the release tarball, you can use B<uscan> 1421to get the most recent source of a subtree in the repository with an 1422automatically generated version string. 1423 1424 version=4 1425 opts="mode=svn, pgpmode=none" \ 1426 svn://svn.code.sf.net/p/jmol/code/trunk/ \ 1427 HEAD debian uupdate 1428 1429By default, B<uscan> generates the new upstream version by appending the 1430revision number to "0.0~svn". This can later be changed using B<uversionmangle>. 1431 1432=head1 COPYRIGHT FILE EXAMPLES 1433 1434Here is an example for the F<debian/copyright> file which initiates automatic 1435repackaging of the upstream tarball into I<< <spkg>_<oversion>.orig.tar.gz >> 1436(In F<debian/copyright>, the B<Files-Excluded> and 1437B<Files-Excluded->I<component> stanzas are a part of the first paragraph and 1438there is a blank line before the following paragraphs which contain B<Files> 1439and other stanzas.): 1440 1441 Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/ 1442 Files-Excluded: exclude-this 1443 exclude-dir 1444 */exclude-dir 1445 .* 1446 */js/jquery.js 1447 1448 Files: * 1449 Copyright: ... 1450 ... 1451 1452Here is another example for the F<debian/copyright> file which initiates 1453automatic repackaging of the multiple upstream tarballs into 1454I<< <spkg>_<oversion>.orig.tar.gz >> and 1455I<< <spkg>_<oversion>.orig-bar.tar.gz >>: 1456 1457 Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/ 1458 Files-Excluded: exclude-this 1459 exclude-dir 1460 */exclude-dir 1461 .* 1462 */js/jquery.js 1463 Files-Excluded-bar: exclude-this 1464 exclude-dir 1465 */exclude-dir 1466 .* 1467 */js/jquery.js 1468 1469 Files: * 1470 Copyright: ... 1471 ... 1472 1473See mk-origtargz(1). 1474 1475=head1 KEYRING FILE EXAMPLES 1476 1477Let's assume that the upstream "B<< uscan test key (no secret) 1478<none@debian.org> >>" signs its package with a secret OpenPGP key and publishes 1479the corresponding public OpenPGP key. This public OpenPGP key can be 1480identified in 3 ways using the hexadecimal form. 1481 1482=over 1483 1484=item * The fingerprint as the 20 byte data calculated from the public OpenPGP 1485key. E. g., 'B<CF21 8F0E 7EAB F584 B7E2 0402 C77E 2D68 7254 3FAF>' 1486 1487=item * The long keyid as the last 8 byte data of the fingerprint. E. g., 1488'B<C77E2D6872543FAF>' 1489 1490=item * The short keyid is the last 4 byte data of the fingerprint. E. g., 1491'B<72543FAF>' 1492 1493=back 1494 1495Considering the existence of the collision attack on the short keyid, the use 1496of the long keyid is recommended for receiving keys from the public key 1497servers. You must verify the downloaded OpenPGP key using its full fingerprint 1498value which you know is the trusted one. 1499 1500The armored keyring file F<debian/upstream/signing-key.asc> can be created by 1501using the B<gpg> (or B<gpg2>) command as follows. 1502 1503 $ gpg --recv-keys "C77E2D6872543FAF" 1504 ... 1505 $ gpg --finger "C77E2D6872543FAF" 1506 pub 4096R/72543FAF 2015-09-02 1507 Key fingerprint = CF21 8F0E 7EAB F584 B7E2 0402 C77E 2D68 7254 3FAF 1508 uid uscan test key (no secret) <none@debian.org> 1509 sub 4096R/52C6ED39 2015-09-02 1510 $ cd path/to/<upkg>-<uversion> 1511 $ mkdir -p debian/upstream 1512 $ gpg --export --export-options export-minimal --armor \ 1513 'CF21 8F0E 7EAB F584 B7E2 0402 C77E 2D68 7254 3FAF' \ 1514 >debian/upstream/signing-key.asc 1515 1516The binary keyring files, F<debian/upstream/signing-key.pgp> and 1517F<debian/upstream-signing-key.pgp>, are still supported but deprecated. 1518 1519If a group of developers sign the package, you need to list fingerprints of all 1520of them in the argument for B<gpg --export ...> to make the keyring to contain 1521all OpenPGP keys of them. 1522 1523Sometimes you may wonder who made a signature file. You can get the public 1524keyid used to create the detached signature file F<foo-2.0.tar.gz.asc> by 1525running B<gpg> as: 1526 1527 $ gpg -vv foo-2.0.tar.gz.asc 1528 gpg: armor: BEGIN PGP SIGNATURE 1529 gpg: armor header: Version: GnuPG v1 1530 :signature packet: algo 1, keyid C77E2D6872543FAF 1531 version 4, created 1445177469, md5len 0, sigclass 0x00 1532 digest algo 2, begin of digest 7a c7 1533 hashed subpkt 2 len 4 (sig created 2015-10-18) 1534 subpkt 16 len 8 (issuer key ID C77E2D6872543FAF) 1535 data: [4091 bits] 1536 gpg: assuming signed data in `foo-2.0.tar.gz' 1537 gpg: Signature made Sun 18 Oct 2015 11:11:09 PM JST using RSA key ID 72543FAF 1538 ... 1539 1540=head1 COMMANDLINE OPTIONS 1541 1542For the basic usage, B<uscan> does not require to set these options. 1543 1544=over 1545 1546=item B<--conffile>, B<--conf-file> 1547 1548Add or replace default configuration files (C</etc/devscripts.conf> and 1549C<~/.devscripts>). This can only be used as the first option given on the 1550command-line. 1551 1552=over 1553 1554=item replace: 1555 1556 uscan --conf-file test.conf --verbose 1557 1558=item add: 1559 1560 uscan --conf-file +test.conf --verbose 1561 1562If one B<--conf-file> has no C<+>, default configuration files are ignored. 1563 1564=back 1565 1566=item B<--no-conf>, B<--noconf> 1567 1568Don't read any configuration files. This can only be used as the first option 1569given on the command-line. 1570 1571=item B<--no-verbose> 1572 1573Don't report verbose information. (default) 1574 1575=item B<--verbose>, B<-v> 1576 1577Report verbose information. 1578 1579=item B<--debug>, B<-vv> 1580 1581Report verbose information and some internal state values. 1582 1583=item B<--extra-debug>, B<-vvv> 1584 1585Report verbose information including the downloaded 1586web pages as processed to STDERR for debugging. 1587 1588=item B<--dehs> 1589 1590Send DEHS style output (XML-type) to STDOUT, while 1591send all other uscan output to STDERR. 1592 1593=item B<--no-dehs> 1594 1595Use only traditional uscan output format. (default) 1596 1597=item B<--download>, B<-d> 1598 1599Download the new upstream release. (default) 1600 1601=item B<--force-download>, B<-dd> 1602 1603Download the new upstream release even if up-to-date. (may not overwrite the local file) 1604 1605=item B<--overwrite-download>, B<-ddd> 1606 1607Download the new upstream release even if up-to-date. (may overwrite the local file) 1608 1609=item B<--no-download>, B<--nodownload> 1610 1611Don't download and report information. 1612 1613Previously downloaded tarballs may be used. 1614 1615Change default to B<--skip-signature>. 1616 1617=item B<--signature> 1618 1619Download signature. (default) 1620 1621=item B<--no-signature> 1622 1623Don't download signature but verify if already downloaded. 1624 1625=item B<--skip-signature> 1626 1627Don't bother download signature nor verifying signature. 1628 1629=item B<--safe>, B<--report> 1630 1631Avoid running unsafe scripts by skipping both the repacking of the downloaded 1632package and the updating of the new source tree. 1633 1634Change default to B<--no-download> and B<--skip-signature>. 1635 1636When the objective of running B<uscan> is to gather the upstream package status 1637under the security conscious environment, please make sure to use this option. 1638 1639=item B<--report-status> 1640 1641This is equivalent of setting "B<--verbose --safe>". 1642 1643=item B<--download-version> I<version> 1644 1645Specify the I<version> which the upstream release must match in order to be 1646considered, rather than using the release with the highest version. 1647(a best effort feature) 1648 1649=item B<--download-debversion> I<version> 1650 1651Specify the Debian package version to download the corresponding upstream 1652release version. The B<dversionmangle> and B<uversionmangle> rules are considered. 1653(a best effort feature) 1654 1655=item B<--download-current-version> 1656 1657Download the currently packaged version. 1658(a best effort feature) 1659 1660=item B<--check-dirname-level> I<N> 1661 1662See the below section L<Directory name checking> for an explanation of this option. 1663 1664=item B<--check-dirname-regex> I<regex> 1665 1666See the below section L<Directory name checking> for an explanation of this option. 1667 1668=item B<--destdir> I<path> 1669Normally, B<uscan> changes its internal current directory to the package's 1670source directory where the F<debian/> is located. Then the destination 1671directory for the downloaded tarball and other files is set to the parent 1672directory F<../> from this internal current directory. 1673 1674This default destination directory can be overridden by setting B<--destdir> 1675option to a particular I<path>. If this I<path> is a relative path, the 1676destination directory is determined in relative to the internal current 1677directory of B<uscan> execution. If this I<path> is a absolute path, the 1678destination directory is set to I<path> irrespective of the internal current 1679directory of B<uscan> execution. 1680 1681The above is true not only for the simple B<uscan> run in the single source tree 1682but also for the advanced scanning B<uscan> run with subdirectories holding 1683multiple source trees. 1684 1685One exception is when B<--watchfile> and B<--package> are used together. For 1686this case, the internal current directory of B<uscan> execution and the default 1687destination directory are set to the current directory F<.> where B<uscan> is 1688started. The default destination directory can be overridden by setting 1689B<--destdir> option as well. 1690 1691=item B<--package> I<package> 1692 1693Specify the name of the package to check for rather than examining 1694F<debian/changelog>; this requires the B<--upstream-version> (unless a version 1695is specified in the F<watch> file) and B<--watchfile> options as well. 1696Furthermore, no directory scanning will be done and nothing will be downloaded. 1697This option automatically sets B<--no-download> and B<--skip-signature>; and 1698probably most useful in conjunction with the DEHS system (and B<--dehs>). 1699 1700=item B<--upstream-version> I<upstream-version> 1701 1702Specify the current upstream version rather than examine F<debian/watch> or 1703F<debian/changelog> to determine it. This is ignored if a directory scan is being 1704performed and more than one F<debian/watch> file is found. 1705 1706=item B<--watchfile> I<watchfile> 1707 1708Specify the I<watchfile> rather than perform a directory scan to determine it. 1709If this option is used without B<--package>, then B<uscan> must be called from 1710within the Debian package source tree (so that F<debian/changelog> can be found 1711simply by stepping up through the tree). 1712 1713One exception is when B<--watchfile> and B<--package> are used together. 1714B<uscan> can be called from anywhare and the internal current directory of 1715B<uscan> execution and the default destination directory are set to the current 1716directory F<.> where B<uscan> is started. 1717 1718See more in the B<--destdir> explanation. 1719 1720=item B<--bare> 1721 1722Disable all site specific special case codes to perform URL redirections and 1723page content alterations. 1724 1725=item B<--http-header> 1726 1727Add specified header in HTTP requests for matching url. This option can be used 1728more than one time, values must be in the form "baseUrl@Name=value. Example: 1729 1730 uscan --http-header https://example.org@My-Token=qwertyuiop 1731 1732Security: 1733 1734=over 1735 1736=item The given I<baseUrl> must exactly match the base url before '/'. 1737Examples: 1738 1739 | --http-header value | Good for | Never used | 1740 +------------------------------------+-----------------------------+------------+ 1741 | https://example.org.com@Hdr=Value | https://example.org.com/... | | 1742 | https://example.org.com/@Hdr=Value | | X | 1743 | https://e.com:1879@Hdr=Value | https://e.com:1879/... | | 1744 | https://e.com:1879/dir@Hdr=Value | https://e.com:1879/dir/... | | 1745 | https://e.com:1879/dir/@Hdr=Value | | X | 1746 1747=item It is strongly recommended to not use this feature to pass a secret 1748token over unciphered connection I<(http://)> 1749 1750=item You can use C<USCAN_HTTP_HEADER> variable (in C<~/.devscripts>) to hide 1751secret token from scripts 1752 1753=back 1754 1755=item B<--no-exclusion> 1756 1757Don't automatically exclude files mentioned in F<debian/copyright> field B<Files-Excluded>. 1758 1759=item B<--pasv> 1760 1761Force PASV mode for FTP connections. 1762 1763=item B<--no-pasv> 1764 1765Don't use PASV mode for FTP connections. 1766 1767=item B<--no-symlink> 1768 1769Don't rename nor repack upstream tarball. 1770 1771=item B<--timeout> I<N> 1772 1773Set timeout to I<N> seconds (default 20 seconds). 1774 1775=item B<--user-agent>, B<--useragent> 1776 1777Override the default user agent header. 1778 1779=item B<--help> 1780 1781Give brief usage information. 1782 1783=item B<--version> 1784 1785Display version information. 1786 1787=back 1788 1789B<uscan> also accepts following options and passes them to B<mk-origtargz>: 1790 1791=over 1792 1793=item B<--symlink> 1794 1795Make B<orig.tar.gz> (with the appropriate extension) symlink to the downloaded 1796files. (This is the default behavior.) 1797 1798=item B<--copy> 1799 1800Instead of symlinking as described above, copy the downloaded files. 1801 1802=item B<--rename> 1803 1804Instead of symlinking as described above, rename the downloaded files. 1805 1806=item B<--repack> 1807 1808After having downloaded an lzma tar, xz tar, bzip tar, gz tar, zip, jar, xpi 1809archive, repack it to the specified compression (see B<--compression>). 1810 1811The unzip package must be installed in order to repack zip and jar archives, 1812the mozilla-devscripts package must be installed to repack xpi archives, and 1813the xz-utils package must be installed to repack lzma or xz tar archives. 1814 1815=item B<--compression> [ B<gzip> | B<bzip2> | B<lzma> | B<xz> ] 1816 1817In the case where the upstream sources are repacked (either because B<--repack> 1818option is given or F<debian/copyright> contains the field B<Files-Excluded>), 1819it is possible to control the compression method via the parameter. The 1820default is B<gzip> for normal tarballs, and B<xz> for tarballs generated 1821directly from the git repository. 1822 1823=item B<--copyright-file> I<copyright-file> 1824 1825Exclude files mentioned in B<Files-Excluded> in the given I<copyright-file>. 1826This is useful when running B<uscan> not within a source package directory. 1827 1828=back 1829 1830=head1 DEVSCRIPT CONFIGURATION VARIABLES 1831 1832For the basic usage, B<uscan> does not require to set these configuration 1833variables. 1834 1835The two configuration files F</etc/devscripts.conf> and F<~/.devscripts> are 1836sourced by a shell in that order to set configuration variables. These 1837may be overridden by command line options. Environment variable settings are 1838ignored for this purpose. If the first command line option given is 1839B<--noconf>, then these files will not be read. The currently recognized 1840variables are: 1841 1842=over 1843 1844=item B<USCAN_DOWNLOAD> 1845 1846Download or report only: 1847 1848=over 1849 1850=item B<no>: equivalent to B<--no-download>, newer upstream files will 1851not be downloaded. 1852 1853=item B<yes>: equivalent to B<--download>, newer upstream files will 1854be downloaded. This is the default behavior. 1855 1856See also B<--force-download> and B<--overwrite-download>. 1857 1858=back 1859 1860=item B<USCAN_SAFE> 1861 1862If this is set to B<yes>, then B<uscan> avoids running unsafe scripts by 1863skipping both the repacking of the downloaded package and the updating of the 1864new source tree; this is equivalent to the B<--safe> options; this also sets 1865the default to B<--no-download> and B<--skip-signature>. 1866 1867=item B<USCAN_PASV> 1868 1869If this is set to yes or no, this will force FTP connections to use PASV mode 1870or not to, respectively. If this is set to default, then B<Net::FTP(3)> makes 1871the choice (primarily based on the B<FTP_PASSIVE> environment variable). 1872 1873=item B<USCAN_TIMEOUT> 1874 1875If set to a number I<N>, then set the timeout to I<N> seconds. This is 1876equivalent to the B<--timeout> option. 1877 1878=item B<USCAN_SYMLINK> 1879 1880If this is set to no, then a I<pkg>_I<version>B<.orig.tar.{gz|bz2|lzma|xz}> 1881symlink will not be made (equivalent to the B<--no-symlink> option). If it is 1882set to B<yes> or B<symlink>, then the symlinks will be made. If it is set to 1883B<rename>, then the files are renamed (equivalent to the B<--rename> option). 1884 1885=item B<USCAN_DEHS_OUTPUT> 1886 1887If this is set to B<yes>, then DEHS-style output will be used. This is 1888equivalent to the B<--dehs> option. 1889 1890=item B<USCAN_VERBOSE> 1891 1892If this is set to B<yes>, then verbose output will be given. This is 1893equivalent to the B<--verbose> option. 1894 1895=item B<USCAN_USER_AGENT> 1896 1897If set, the specified user agent string will be used in place of the default. 1898This is equivalent to the B<--user-agent> option. 1899 1900=item B<USCAN_DESTDIR> 1901 1902If set, the downloaded files will be placed in this directory. This is 1903equivalent to the B<--destdir> option. 1904 1905=item B<USCAN_REPACK> 1906 1907If this is set to yes, then after having downloaded a bzip tar, lzma tar, xz 1908tar, or zip archive, uscan will repack it to the specified compression (see 1909B<--compression>). This is equivalent to the B<--repack> option. 1910 1911=item B<USCAN_EXCLUSION> 1912 1913If this is set to no, files mentioned in the field B<Files-Excluded> of 1914F<debian/copyright> will be ignored and no exclusion of files will be tried. 1915This is equivalent to the B<--no-exclusion> option. 1916 1917=item B<USCAN_HTTP_HEADER> 1918 1919If set, the specified http header will be used if URL match. This is equivalent 1920to B<--http-header> option. 1921 1922=back 1923 1924=head1 EXIT STATUS 1925 1926The exit status gives some indication of whether a newer version was found or 1927not; one is advised to read the output to determine exactly what happened and 1928whether there were any warnings to be noted. 1929 1930=over 1931 1932=item B<0> 1933 1934Either B<--help> or B<--version> was used, or for some F<watch> file which was 1935examined, a newer upstream version was located. 1936 1937=item B<1> 1938 1939No newer upstream versions were located for any of the F<watch> files examined. 1940 1941=back 1942 1943=head1 ADVANCED FEATURES 1944 1945B<uscan> has many other enhanced features which are skipped in the above 1946section for the simplicity. Let's check their highlights. 1947 1948B<uscan> can be executed with I<path> as its argument to change the starting 1949directory of search from the current directory to I<path> . 1950 1951If you are not sure what exactly is happening behind the scene, please enable 1952the B<--verbose> option. If this is not enough, enable the B<--debug> option 1953too see all the internal activities. 1954 1955See L<COMMANDLINE OPTIONS> and L<DEVSCRIPT CONFIGURATION VARIABLES> for other 1956variations. 1957 1958=head2 Custom script 1959 1960The optional I<script> parameter in F<debian/watch> means to execute I<script> 1961with options after processing this line if specified. 1962 1963See L<HISTORY AND UPGRADING> for how B<uscan> invokes the custom I<script>. 1964 1965For compatibility with other tools such as B<git-buildpackage>, it may not be 1966wise to create custom scripts with random behavior. In general, B<uupdate> is 1967the best choice for the non-native package and custom scripts, if created, 1968should behave as if B<uupdate>. For possible use case, see 1969L<http://bugs.debian.org/748474> as an example. 1970 1971=head2 URL diversion 1972 1973Some popular web sites changed their web page structure causing maintenance 1974problems to the watch file. There are some redirection services created to 1975ease maintenance of the watch file. Currently, B<uscan> makes automatic 1976diversion of URL requests to the following URLs to cope with this situation. 1977 1978=over 1979 1980=item * L<http://sf.net> 1981 1982=item * L<http://pypi.python.org> 1983 1984=back 1985 1986=head2 Directory name checking 1987 1988Similarly to several other scripts in the B<devscripts> package, B<uscan> 1989explores the requested directory trees looking for F<debian/changelog> and 1990F<debian/watch> files. As a safeguard against stray files causing potential 1991problems, and in order to promote efficiency, it will examine the name of the 1992parent directory once it finds the F<debian/changelog> file, and check that the 1993directory name corresponds to the package name. It will only attempt to 1994download newer versions of the package and then perform any requested action if 1995the directory name matches the package name. Precisely how it does this is 1996controlled by two configuration file variables 1997B<DEVSCRIPTS_CHECK_DIRNAME_LEVEL> and B<DEVSCRIPTS_CHECK_DIRNAME_REGEX>, and 1998their corresponding command-line options B<--check-dirname-level> and 1999B<--check-dirname-regex>. 2000 2001B<DEVSCRIPTS_CHECK_DIRNAME_LEVEL> can take the following values: 2002 2003=over 2004 2005=item B<0> 2006 2007Never check the directory name. 2008 2009=item B<1> 2010 2011Only check the directory name if we have had to change directory in 2012our search for F<debian/changelog>, that is, the directory containing 2013F<debian/changelog> is not the directory from which B<uscan> was invoked. 2014This is the default behavior. 2015 2016=item B<2> 2017 2018Always check the directory name. 2019 2020=back 2021 2022The directory name is checked by testing whether the current directory name (as 2023determined by pwd(1)) matches the regex given by the configuration file 2024option B<DEVSCRIPTS_CHECK_DIRNAME_REGEX> or by the command line option 2025B<--check-dirname-regex> I<regex>. Here regex is a Perl regex (see 2026perlre(3perl)), which will be anchored at the beginning and the end. If regex 2027contains a B</>, then it must match the full directory path. If not, then 2028it must match the full directory name. If regex contains the string I<package>, 2029this will be replaced by the source package name, as determined from the 2030F<debian/changelog>. The default value for the regex is: I<package>B<(-.+)?>, thus matching 2031directory names such as I<package> and I<package>-I<version>. 2032 2033=head1 HISTORY AND UPGRADING 2034 2035This section briefly describes the backwards-incompatible F<watch> file features 2036which have been added in each F<watch> file version, and the first version of the 2037B<devscripts> package which understood them. 2038 2039=over 2040 2041=item Pre-version 2 2042 2043The F<watch> file syntax was significantly different in those days. Don't use it. 2044If you are upgrading from a pre-version 2 F<watch> file, you are advised to read 2045this manpage and to start from scratch. 2046 2047=item Version 2 2048 2049B<devscripts> version 2.6.90: The first incarnation of the current style of 2050F<watch> files. This version is also deprecated and will be rejected after 2051the Debian 11 release. 2052 2053=item Version 3 2054 2055B<devscripts> version 2.8.12: Introduced the following: correct handling of 2056regex special characters in the path part, directory/path pattern matching, 2057version number in several parts, version number mangling. Later versions 2058have also introduced URL mangling. 2059 2060If you are upgrading from version 2, the key incompatibility is if you have 2061multiple groups in the pattern part; whereas only the first one would be used 2062in version 2, they will all be used in version 3. To avoid this behavior, 2063change the non-version-number groups to be B<(?:> I< ...> B<)> instead of a 2064plain B<(> I< ... > B<)> group. 2065 2066=over 2067 2068=item * B<uscan> invokes the custom I<script> as "I<script> B<--upstream-version> 2069I<version> B<../>I<spkg>B<_>I<version>B<.orig.tar.gz>". 2070 2071=item * B<uscan> invokes the standard B<uupdate> as "B<uupdate> B<--no-symlink 2072--upstream-version> I<version> B<../>I<spkg>B<_>I<version>B<.orig.tar.gz>". 2073 2074=back 2075 2076=item Version 4 2077 2078B<devscripts> version 2.15.10: The first incarnation of F<watch> files 2079supporting multiple upstream tarballs. 2080 2081The syntax of the watch file is relaxed to allow more spaces for readability. 2082 2083If you have a custom script in place of B<uupdate>, you may also encounter 2084problems updating from Version 3. 2085 2086=over 2087 2088=item * B<uscan> invokes the custom I<script> as "I<script> B<--upstream-version> 2089I<version>". 2090 2091=item * B<uscan> invokes the standard B<uupdate> as "B<uupdate> B<--find> 2092B<--upstream-version> I<version>". 2093 2094=back 2095 2096Restriction for B<--dehs> is lifted by redirecting other output to STDERR when 2097it is activated. 2098 2099=back 2100 2101=head1 SEE ALSO 2102 2103dpkg(1), mk-origtargz(1), perlre(1), uupdate(1), devscripts.conf(5) 2104 2105=head1 AUTHOR 2106 2107The original version of uscan was written by Christoph Lameter 2108<clameter@debian.org>. Significant improvements, changes and bugfixes were 2109made by Julian Gilbey <jdg@debian.org>. HTTP support was added by Piotr 2110Roszatycki <dexter@debian.org>. The program was rewritten in Perl by Julian 2111Gilbey. Xavier Guimard converted it in object-oriented Perl using L<Moo>. 2112 2113=cut 2114 2115####################################################################### 2116# }}} code 0: POD for manpage 2117####################################################################### 2118####################################################################### 2119# {{{ code 1: initializer, command parser, and loop over watchfiles 2120####################################################################### 2121 2122# This code block is the start up of uscan. 2123# Actual processing is performed by process_watchfile in the next block 2124# 2125# This has 3 different modes to process watchfiles 2126# 2127# * If $opt_watchfile and $opt_package are defined, test specified watchfile 2128# without changelog (sanity check for $opt_uversion may be good idea) 2129# * If $opt_watchfile is defined but $opt_package isn't defined, test specified 2130# watchfile assuming you are in source tree and debian/changelogis used to 2131# set variables 2132# * If $opt_watchfile isn't defined, scan subdirectories of directories 2133# specified as ARGS (if none specified, "." is scanned). 2134# * Normal packaging has no ARGS and uses "." 2135# * Archive status scanning tool uses many ARGS pointing to the expanded 2136# source tree to be checked. 2137# Comments below focus on Normal packaging case and sometimes ignores first 2 2138# watch file testing setup. 2139 2140use 5.010; # defined-or (//) 2141use strict; 2142use warnings; 2143use Cwd qw/cwd/; 2144use Devscripts::Uscan::Config; 2145use Devscripts::Uscan::FindFiles; 2146use Devscripts::Uscan::Output; 2147use Devscripts::Uscan::WatchFile; 2148 2149our $uscan_version = "###VERSION###"; 2150 2151BEGIN { 2152 pop @INC if $INC[-1] eq '.'; 2153} 2154 2155my $config = Devscripts::Uscan::Config->new->parse; 2156 2157uscan_verbose "$progname (version $uscan_version) See $progname(1) for help"; 2158if ($dehs) { 2159 uscan_verbose "The --dehs option enabled.\n" 2160 . " STDOUT = XML output for use by other programs\n" 2161 . " STDERR = plain text output for human\n" 2162 . " Use the redirection of STDOUT to a file to get the clean XML data"; 2163} 2164 2165# Did we find any new upstream versions on our wanderings? 2166my $res = 0; 2167 2168my @wf = find_watch_files($config); 2169foreach (@wf) { 2170 my $tmp = process_watchfile(@$_); 2171 $res ||= $tmp; 2172 2173 # Are there any warnings to give if we're using dehs? 2174 dehs_output if ($dehs); 2175} 2176 2177uscan_verbose "Scan finished"; 2178 2179# Are there any warnings to give if we're using dehs? 2180$dehs_end_output = 1; 2181dehs_output if ($dehs); 2182 2183exit($res ? $res : $found ? 0 : 1); 2184 2185####################################################################### 2186# {{{ code 2: process watchfile by looping over watchline 2187####################################################################### 2188 2189sub process_watchfile { 2190 my ($pkg_dir, $package, $version, $watchfile) = @_; 2191 my $opwd = cwd(); 2192 chdir $pkg_dir; 2193 2194 my $wf = Devscripts::Uscan::WatchFile->new({ 2195 config => $config, 2196 package => $package, 2197 pkg_dir => $pkg_dir, 2198 pkg_version => $version, 2199 watchfile => $watchfile, 2200 }); 2201 return $wf->status if ($wf->status); 2202 2203 my $res = $wf->process_lines; 2204 chdir $opwd; 2205 return $res; 2206} 2207####################################################################### 2208# }}} code 2: process watchfile by looping over watchline 2209####################################################################### 2210 2211