From: Frank Lichtenheld Date: Mon, 24 Sep 2007 20:50:53 +0000 (+0200) Subject: dpkg-source.1: Rework documentation of -i and -I options X-Git-Url: https://err.no/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=32b4ea4557d59e39fe7c5fbdd4b50479b6bd34be;p=dpkg dpkg-source.1: Rework documentation of -i and -I options Now gives clearer explanations and better explains the differences between the two in syntax and semantics. --- diff --git a/debian/changelog b/debian/changelog index 70d0190e..dca92608 100644 --- a/debian/changelog +++ b/debian/changelog @@ -26,6 +26,8 @@ dpkg (1.14.7) UNRELEASED; urgency=low * Allow dpkg-source -I without a pattern which will load a default list of pattern similar to -i without regexp. Patch by Jari Aalto. Closes: #440972 + * Rework documentation of dpkg-source's -i and -I options. + Closes: #323911, #440956 [ Updated dpkg translations ] * Basque (Piarres Beobide). Closes: #440859 diff --git a/man/ChangeLog b/man/ChangeLog index ebc4d959..4171e9f1 100644 --- a/man/ChangeLog +++ b/man/ChangeLog @@ -1,3 +1,10 @@ +2007-09-24 Frank Lichtenheld + + * dpkg-source.1: Rework documentation of -i + and -I options to give clearer explanations and + explain the differences between the two in syntax + and semantics. + 2007-09-24 Jari Aalto * dpkg-source.1: Document new behaviour diff --git a/man/dpkg-buildpackage.1 b/man/dpkg-buildpackage.1 index e7a67577..b33ab12e 100644 --- a/man/dpkg-buildpackage.1 +++ b/man/dpkg-buildpackage.1 @@ -172,7 +172,7 @@ Do not sign the .changes file. Passed unchanged to .BR dpkg\-source . .TP -.BI \-I filename +.BI \-I [\fIpattern\fP] Passed unchanged to .BR dpkg\-source . May be repeated multiple times. diff --git a/man/dpkg-source.1 b/man/dpkg-source.1 index faaf238f..c3a9eeb7 100644 --- a/man/dpkg-source.1 +++ b/man/dpkg-source.1 @@ -1,5 +1,5 @@ .\" Authors: Ian Jackson -.TH dpkg\-source 1 "2007-07-18" "Debian Project" "dpkg utilities" +.TH dpkg\-source 1 "2007-09-24" "Debian Project" "dpkg utilities" .SH NAME dpkg\-source \- Debian source package (.dsc) manipulation tool . @@ -112,37 +112,48 @@ filtered out of the list of files for the diff. (This list is generated by a find command.) \fB\-i\fR by itself enables the option, with a default that will filter out control files and directories of the most common revision control systems, backup and swap files and Libtool -build output directories. +build output directories. There can only be one active regexp, of multiple +\-i options only the last one will take effect. + This is very helpful in cutting out extraneous files that get included -in the .diff.gz, (eg: "debian/BUGS_TODO/*" or "debian/RCS/*,v"). For -instance, if you maintain a package that you track via remote CVS, -where you don't have access permissions for committing the debian -control files and making tags for \fIcvs\-buildpackage(1)\fR, it is -necessary to perform an extra checkout/update into a directory you -keep pristine, to generate the .orig.tar.gz from. That directory will -have CVS/Entries files in it that will contain timestamps that differ -from the ones in your working directory, thus causing them to be -unnecessarily included in every .diff.gz, unless you use the \fB\-i\fR -switch. +in the .diff.gz, e.g. if you maintain your source in a revision control +system and want to use a checkout to build a source package without +including the additional files and directories that it will usually +contain (e.g. CVS/, .cvsignore, .svn/). The default regexp is already +very exhaustive, but if you need to replace it, please note that by +default it can match any part of a path, so if you want to match the +begin of a filename or only full filenames, you will need to provide +the neccessary anchors (e.g. '(^|/)', '($|/)') yourself. .TP -.BI \-I[\fIfile-pattern\fP] - -If this option is specified, the pattern will be passed to tar's \-\-exclude +.BR \-I [\fIfile-pattern\fP] +If this option is specified, the pattern will be passed to +.BR tar (1)'s +\-\-exclude option when it is called to generate a .orig.tar.gz or .tar.gz file. For example, \-ICVS will make tar skip over CVS directories when generating a .tar.gz file. The option may be repeated multiple times to list multiple patterns to exclude. -\fB\-I\fR by itself adds default tar(1) \-\-exclude options that will +\fB\-I\fR by itself adds default \-\-exclude options that will filter out control files and directories of the most common revision control systems, backup and swap files and Libtool build output directories. .PP -All the -.BI \-s X -options are mutually exclusive. If you specify more than one only the -last one will be used. +.B Note: +While they have similar purposes, \fB-i\fP and \fB-I\fP have very +different syntax and semantics. \fB-i\fP can only be specified once and +takes a perl compatible regular expression which is matched against +the full relative path of each file. \fB-I\fP can specified +multiple times and takes a filename pattern with shell wildcards. +The pattern is applied to the full relative path but also +to each part of the path individually. The exact semantic of tar's +\-\-exclude option is somewhat complicated, see +http://www.gnu.org/software/tar/manual/tar.html#wildcards for a full +documentation. + +The default regexp and patterns for both options can be seen +in the output of the \fB\-\-help\fP command. .TP .B Build options (with -b): .PP @@ -233,6 +244,11 @@ Unpacks the original source tree. Ensures that the original source is neither copied to the current directory nor unpacked. Any original source tree that was in the current directory is still removed. +.PP +All the +.BI \-s X +options are mutually exclusive. If you specify more than one only the +last one will be used. . .SH BUGS The point at which field overriding occurs compared to certain diff --git a/scripts/dpkg-buildpackage.pl b/scripts/dpkg-buildpackage.pl old mode 100755 new mode 100644 index 303fdd1c..c7cd4229 --- a/scripts/dpkg-buildpackage.pl +++ b/scripts/dpkg-buildpackage.pl @@ -68,7 +68,7 @@ Options: -W turn certain errors into warnings. } passed to -E when -W is turned on, -E turns it off. } dpkg-source -i[] ignore diffs of files matching regex. } only passed - -I filter out files when building tarballs. } to dpkg-source + -I[] filter out files when building tarballs. } to dpkg-source --admindir= change the administrative directory. -h, --help show this help message.