--- name: "tarcust" section: "1" platform: "linux" package: "tarcust" version: "0.9.0-3" release: "Debian 3.1 (Sarge)" platforms: ["linux"] url: "https://new.carta.tech/tarcust" --- # tarcust(1) ## NAME tarcust -- a tar customizer ## SYNOPSIS **tarcust** \[**-h**, **--help**\] \[**-V**, **--version**\] \[**-v**, **--verbose**\] \[**-D**, **--force-directory**\] \[**-u**, **--owner=NAME**, **--user-name=NAME**\] \[**-U**, **--user-number=NUMBER**\] \[**-g**, **--group=NAME**, **--group-name=NAME**\] \[**-G**, **--group-number=NUMBER**\] \[**-p**, **--prefix=DIR\[:MODE\]**\] \[**-s**, **--transform-name=EXPR**\] \[**-x**, **--exclude=EXPR**\] \[**-a**, **--applies-to=EXPR**\] \[**-e**, **--eval=EXPR**\] \[**-B**, **--begin-eval=EXPR**\] \[**-E**, **--end-eval=EXPR**\] \[*input.tar* \[*output.tar*\]\] ## DESCRIPTION The **tarcust** program has been written to help developers building distributions of their programs. The great **automake** GNU tool provides an easy way, just type \``"make dist"`' and your package is ready to distribute. But if for some reason you do not use this tool, it may be a pain. The **tarcust** script has been designed to provide a portable way to implement nice features missing in standard UNIX **tar**, like deletion of files, manipulation of owner/group of files, changes in names. GNU **tar** has such features, so **tarcust** may seem useless in this case, but remember it has been designed to work with any UNIX system. ## OPTIONS - **-h**, **-?**, **--help** Prints a message help and exit - **-V**, **--version** Prints the version number and exit - **-v**, **--verbose** Process verbosely - **-D**, **--force-directory** With this option, before inserting a file into the archive, **tarcust** checks whether the directory in which this file reside exists in the archive and create it if it does not. Uid and gid are those of the first file found in this directory. Note that since 0.8.2, this option is deprecated because it is always set. - **-u**, **--owner=NAME**, **--user-name=NAME** Sets the name of the owner of all files in the archive - **-U**, **--user-number=NUMBER** Sets the numerical ID of the owner of all files - **-g**, **--group=NAME**, **--group-name=NAME** Sets the name of the group - **-G**, **--group-number=NUMBER** Sets the numerical ID of the group - **-p**, **--prefix=DIR\[:MODE\]** Inserts a prefix directory name so that all files are extracted under the *DIR* directory ; by default, this new directory has mode permissions set to 755, this can be changed with the optional **MODE** attribute (only numeric modes are supported) - **-s**, **--transform-names=EXPR** Transform file and directory names ; *EXPR* is a Perl command to manipulate strings, see examples below - **-x**, **--exclude=EXPR** Exclude files matching this Perl regular expression. - **-a**, **--applies-to=EXPR** Apply **-u**, **-U**, **-g** and **-g** flags only to the files and directories matching this pattern. - **-e**, **--eval=EXPR** Apply any Perl statement on file and directory attributes. Any piece of archive contains the following attributes (see the info GNU tar documentation for a detailed description) ``` name mode uid gid size mtime chksum typeflag linkname magic version uname gname devmajor devminor prefix ``` Each attribute is accessible via the `%F` hash array, e.g. `$F{name}`. - **-B**, **--begin-eval=EXPR** The argument of this flag is Perl statements which are evalled before archive is read. - **-E**, **--end-eval=EXPR** The argument of this flag is Perl statements which are evalled after archive is rwritten. ## ARGUMENTS You may specify input and output filenames on command-line. By default datas are read on standard input and sent to standard output. As with most Unix commands, an hyphen is equivalent to standard input or standard output. ## EXAMPLES Prepends a prefix to each file name, the new directory has mode permissions set to 775 ``` cat MANIFEST ⎪ xargs tar cf - \ ⎪ tarcust --prefix=myprog-0.3:775 \ ⎪ gzip -c > myprog-0.3.tar.gz ``` This rule in your *Makefile* will build a distribution without the need of a *MANIFEST* file, ignoring all CVS files ``` dist: distclean find . -type f -a ! -name myprog-0.3.tar.gz \ ⎪ xargs tar cf - \ ⎪ tarcust -x '.*CVS.*' -x '.*\.cvsignore' \ ⎪ gzip -9 -c > myprog-0.3.tar.gz ``` Or with GNU tar ``` dist: distclean find * -depth -print ⎪ sort \ ⎪ xargs tar --no-recursion -cf - ⎪\ ⎪ tarcust -x '.*CVS.*' -x '.*\.cvsignore' \ ⎪ gzip -9 -c > myprog-0.3.tar.gz ``` To satisfy your egocentric feelings, try this one ``` dist: cat MANIFEST ⎪ xargs tar cf - \ ⎪ tarcust -u Denis -g Barbier ⎪ gzip -9 -c > myprog-0.3.tar.gz ``` Change every filename in uppercase letters and suppress any suffix ``` dist: cat MANIFEST ⎪ xargs tar cf - \ ⎪ tarcust -s tr[a-z][A-Z] -s 's,\.[^/]*$,,' \ ⎪ gzip -9 -c > myprog-0.3.tar.gz ``` Make all files with a `".pl"` suffix executable: ``` cat MANIFEST ⎪ xargs tar cf - \ ⎪ tarcust -e '$F{name}=~/\.pl$/ && ($F{mode} ⎪= oct 111)' \ ⎪ gzip -9 -c > myprog-0.3.tar.gz ``` Print how many directories have been written into archive ``` cat MANIFEST ⎪ xargs tar cf - \ ⎪ tarcust -B '$cnt=0' -e '$cnt++ if $F{typeflag} == 5' \ -E 'printf STDERR "# directories: %d\n", $cnt' \ ⎪ gzip -9 -c > myprog-0.3.tar.gz ``` ## NOTES Unlike **tar** and **tardy**, **tarcust** does not perform checks on user and group informations. And it never will, unless a kind guy explain me the benefits of taking care of those informations when distributing a tarball worldwide. String manipulations may look strange at the first glance. To understand how it works, remember that: - • the **tarcust** program is a simple Perl script, so it is natural to use Perl instead of shell regular expressions; - • it has been designed for developers, and not end-users, so this syntax should be quite familiar. There is one point i have to mention : when excluding files, the regular expression must exactly match file names, in other words the regexp you type is surrounded by `"^"` and `"$"`. ## LIMITATIONS GNU implementation does not follow POSIX specifications about file names longer than 100 characters. Current `"tarcust"` version do know how to deal with filenames \< 512 chars with GNU implementation. Further releases should support both GNU and POSIX standards. For portability reasons, directories are put in the archive to make sure they exist when files are extracted. So when you apply a transformation on file names which move them to another directory, you have to ensure that directories are updated too. The **--prefix** option will automatically insert directories, but not **--transform-names**. ## HISTORY The **tarcust** program is strongly inspired by **tardy**, a tar post-processor written in C by Peter Miller. I realized that a tarfile is just a formatted text, so Perl should be a nice tool to manipulate it. On CPAN, i found the Archive::Tar module by Calle Dybedahl, Gurusamy Sarathy and Stephen Zander. But this module is more a Perl replacement for **tar** than a post-processor. So i wrote my own Perl script to follow these goals: - o Keep it simple and portable. - o Do not try to emulate unnecessary features already provided by **tar** or other standard UNIX tools (e.g. there is no plan to handle compressed tarfiles or to add files to an archive). - o Concentrate on the building of software packages. When writing **tarcust**, i tried to be compatible with existing softwares, it's why option names are taken from **tardy** or **tar**. ## SEE ALSO [*tar*(1)](/tar/1.md) [*tardy*(1)](/tardy/1.md) *Archive::Tar*(3) ## AUTHOR Denis Barbier barbier@engelschall.com http://www.engelschall.com/sw/tarcust/ ## CREDITS John Midgley `""` suggested the **-s** and **-e** flags which make **tarcust** much more powerful.