The man pages for the tar(1) command do not have the correct syntax for the 'include' and 'exclude' options. For example, the presently documented syntax is:
It should be:
Note the missing '=' symbol in the presently documented syntax.
The same observation holds true for the 'include' option.
The presently documented syntax works, though. For example, this is how I extract the source distribution from a CURRENT-Snapshot ISO, without the kernel .symbols-files:
tar --unlink -xpJf /usr/freebsd-dist/kernel.txz -C $DEST --exclude '*.symbols'
It works without the = symbol, I have no .symbols files in the $DEST directory when that operation completes.
Yes. It works. I got mislead by reading one of the posts on the FreeBSD forum:
Also, The explanation for the 'include' options uses the '=' symbol. Quoting from the man pages for tar(1):
For example, the command
tar -c -f new.tar --include='*foo*' @old.tgz
creates a new archive new.tar containing only the entries from
old.tgz containing the string `foo'.
You can consider removing the '=' symbol from the example cited above for consistency or including the '=' symbol as an optional symbol in the synopsis of the tar command.
Also, now that this has come to my observation, I was trying out the 'include' option while trying to create a new archive. What's surprising about the 'include' option is that the following doesn't work! :
tar -cvf new.tar --include '*foo*' .
Note that the directory to tar is the current directory indicated by the '.' at the end of the above command. Even though there are many 'foo' files in the current directory, in this case the tar command does nothing! The following works, however:
tar -cvf new.tar --include '*foo*' *
Note that the '.' has been replaced by the shell globing pattern *. This caveat could be explained in the example in the man pages. It had me stumped for a while till I found this helpful link: http://stackoverflow.com/questions/5747755/tar-with-include-pattern