.\" 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
.
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
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
projects / dpkg / commitdiff