[devscripts] 02/03: uscan: documentation for mode=git

Sun Nov 29 16:05:21 UTC 2015

This is an automated email from the git hooks/post-receive script.

osamu pushed a commit to branch master
in repository devscripts.

commit 543249c3511693edaca3e541d61a9e6635d64896
Author: Osamu Aoki <osamu at debian.org>
Date:   Sun Nov 29 09:22:07 2015 +0900

    uscan: documentation for mode=git
    
    Update documentation to address new mode=git
    Update changelog for mode=git (Closes: #663357)
---
 debian/changelog |  1 +
 scripts/uscan.pl | 59 ++++++++++++++++++++++++++++++++++++++++++++++++--------
 2 files changed, 52 insertions(+), 8 deletions(-)

diff --git a/debian/changelog b/debian/changelog
index a314c22..ce1873d 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -66,6 +66,7 @@ devscripts (2.15.10) UNRELEASED; urgency=medium
     + Add generalized search regex with some special strings @PACKAGE@,
       @ANY_VERSION@, @ARCHIVE_EXT@, and @SIGNATURE_EXT at .
       (Closes: #517637, #539780)
+    + Add direct git repository support. (Closes: #663357)
   * uupdate:
     + Prevent failure when upstream version is 0.  (Closes: #798175)
     + Work around missing debian.tar.gz for "3.0 (quilt)".  (Closes: 798133)
diff --git a/scripts/uscan.pl b/scripts/uscan.pl
index 316431f..03c8054 100755
--- a/scripts/uscan.pl
+++ b/scripts/uscan.pl
@@ -297,7 +297,8 @@ Set the name of the secondary source tarball as I<<
 Set the compression I<method> when the tarball is repacked. (persistent)
 
 Available I<method> values are B<xz>, B<gzip> (alias B<gz>), B<bzip2> (alias
-B<bz2>), and B<lzma>.  The default is B<gzip>.
+B<bz2>), and B<lzma>.  The default is B<gzip> for normal tarballs, and B<xz>
+for tarballs generated directly from the git repository.
 
 If the debian source format is not in the old 1.0, setting this to B<xz> should
 help reduce the package size when the package is repacked.
@@ -331,6 +332,28 @@ Add I<suffix> to the Debian package upstream version as suffix only when the
 source tarball is repackaged.  This rule should be used only for the single
 upstream tarball package.
 
+=item B<mode=>I<mode>
+
+Set the archive download I<mode>.
+
+=over
+
+=item B<LWP>
+
+This mode is the default one which downloads the specified tarball from the
+archive URL on the web.
+
+=item B<git>
+
+This mode accesses the upstream git archive directly with the B<git> command
+and packs the source tree with the specified tag into
+I<spkg-version>B<.tar.xz>.
+
+If the upstream publishes the released tarball via its web interface, please
+use it instead of using this mode.  This mode is the last resort method.
+
+=back
+
 =item B<pgpmode=>I<mode>
 
 Set the pgp/gpg signature verification I<mode>.
@@ -731,6 +754,9 @@ When writing the watch file, you should rely on the latest upstream source
 announcement web page.  You should not try to second guess the upstream archive
 structure if possible.  Here are the typical F<debian/watch> files.
 
+Please note that executing B<uscan> with B<-v> or B<-vv> reveals what exactly
+happens internally.
+
 The existence and non-existence of a space the before tailing B<\> (back slash)
 are significant.
 
@@ -1041,7 +1067,7 @@ For B<cfn-sphere>, set the watch file as:
 
   version=4
   https://pypi.python.org/packages/source/c/cfn-sphere/ \
-      cfn-sphere-([\d\.]+).tar.gz
+      cfn-sphere-([\d\.]+).tar.gz debian uupdate
 
 Please note, you can still use normal functionalities of B<uscan> to set up a
 watch file for this site without using the redirector.
@@ -1050,17 +1076,30 @@ watch file for this site without using the redirector.
   opts="pgpmode=none, \
       https://pypi.python.org/pypi/cfn-sphere/ \
       https://pypi.python.org/packages/source/c/cfn-sphere/\
-      cfn-sphere-([\d\.]+).tar.gz#.*
+      cfn-sphere-([\d\.]+).tar.gz#.* debian uupdate
 
 =head2 code.google.com
 
 Sites which used to be hosted on the Google Code service should have migrated
 to elsewhere (github?).  Please look for the newer upstream site.
 
+=head2 direct access to the git repository
+
+If the upstream only publishes its code via the git repository and it has no web
+interface to obtain the releasse tarball, you can use uscan with the tags of
+the git repository.
+
+  version=4
+  opts="mode=git" http://git.ao2.it/tweeper.git \
+  refs/tags/v([\d\.]+) debian uupdate
+
+Please note "B<git ls-remote>" is used to obtain references for tags.  If a tag
+B<v20.5> is the newest tag, the above example downloads I<spkg>B<-20.5.tar.xz>.
 
 =head1 COPYRIGHT FILE EXAMPLES
 
-Here is an example for the F<debian/copyright> file which initiates automatic repackaging of the upstream tarball into I<< <spkg>_<oversion>.orig.tar.gz >>:
+Here is an example for the F<debian/copyright> file which initiates automatic
+repackaging of the upstream tarball into I<< <spkg>_<oversion>.orig.tar.gz >>:
 
   Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
   Files-Excluded: exclude-this
@@ -1071,7 +1110,10 @@ Here is an example for the F<debian/copyright> file which initiates automatic re
 
    ...
 
-Here is another example for the F<debian/copyright> file which initiates automatic repackaging of the multiple upstream tarballs into I<< <spkg>_<oversion>.orig.tar.gz >> and I<< <spkg>_<oversion>.orig-bar.tar.gz >>:
+Here is another example for the F<debian/copyright> file which initiates
+automatic repackaging of the multiple upstream tarballs into 
+I<< <spkg>_<oversion>.orig.tar.gz >> and 
+I<< <spkg>_<oversion>.orig-bar.tar.gz >>:
 
   Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
   Files-Excluded: exclude-this
@@ -1336,9 +1378,10 @@ lzma or xz tar archives.
 =item B<--compression> [ B<gzip> | B<bzip2> | B<lzma> | B<xz> ]
 
 In the case where the upstream sources are repacked (either because B<--repack>
-option is given or F<debian/copyright> contains the field B<Files-Excluded>), it is
-possible to control the compression method via the parameter (defaults to
-B<gzip>).
+option is given or F<debian/copyright> contains the field B<Files-Excluded>),
+it is possible to control the compression method via the parameter.  The
+default is B<gzip> for normal tarballs, and B<xz> for tarballs generated
+directly from the git repository.
 
 =item B<--copyright-file> I<copyright-file>
 

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/collab-maint/devscripts.git

