tarcust -- a tar customizer

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]]

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 `CWmake 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.

-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 CW%F hash array, e.g. CW$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.

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.

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 CW.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

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 CW^ and CW$.

GNU implementation does not follow POSIX specifications about file names longer than 100 characters. Current CWtarcust 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.

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.

tar(1) tardy(1) Archive::Tar(3)

Denis Barbier barbier@engelschall.com http://www.engelschall.com/sw/tarcust/

John Midgley CW<jmidgley@labyrinth.net.au> suggested the -s and -e flags which make tarcust much more powerful.