.\"                                      Hey, EMACS: -*- nroff -*-
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH atool 1 "March 30, 2001"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
atool \- A script for managing file archives of various types
.SH SYNOPSIS
.B atool
.RI [ OPTION ]... " ARCHIVE " [ FILE ]...
.br
.B aunpack
.RI [ OPTION ]... " ARCHIVE " [ FILE ]...
.br
.B apack
.RI [ OPTION ]... " ARCHIVE " "" FILE ...
.br
.B als
.RI [ OPTION ]... " ARCHIVE " [ FILE ]...
.br
.B acat
.RI [ OPTION ]... " ARCHIVE " [ FILE ]...
.SH DESCRIPTION
This manual page document describes the \fBatool\fP commands.
These commands are used for managing file archives of various
types, such as tar and Zip archives. Each command can be
executed individually or by giving the appropriate options
to \fBatool\fP (see \fBOPTIONS\fP below).
.PP
\fBaunpack\fP extracts files from an archive. Often one wants
to extract all files in an archive to a single subdirectory.
However, some archives contain multiple files in their root
directories. The aunpack program overcomes this problem by
first extracting files to a unique (temporary) directory, and
then moving its contents back if possible. This also prevents
local files from being overwritten by mistake.
.PP
\fBapack\fP creates archives (or compresses files).
.PP
\fBals\fP lists files in an archive.
.PP
\fBacat\fP extracts files in an archive to standard out.
.PP
Unless the \fB\-\-format\fP (\fB\-f\fP) option is provided,
the archive format is determined by the archive file extension. I.e.
an extension ".tar.gz" or ".tgz" means tar+gzip format. Note that
the extensions are checked in the order listed in the section
\fBARCHIVE TYPES\fP below, which is why a file with extension ".tar.gz"
is considered to a be tar+gzip archive, not a gzip compressed file.
.SH OPTIONS
These programs follow the usual GNU command line syntax, with long
options starting with two dashes (`-').
A summary of options is included below.
.TP
.B \-l, \-\-list
List files in archive.
This option is automaticly assumed when \fBals\fP is executed.
.TP
.B \-x, \-\-extract
Extract files from archive.
This option is automaticly assumed when \fBaunpack\fP is executed.
.TP
.B \-X, \-\-extract-to\fR=\fIPATH\fR
Extract files from archive to current directory.
.TP
.B \-a, \-\-add
Create archive.
This option is automaticly assumed when \fBapack\fP is executed.
.TP
.B \-c, \-\-cat
Extract a file from archive to standard out (displaying it on
screen).
This option is automaticly assumed when \fBacat\fP is executed.
.TP
.B \-e, \-\-each
For each argument, execute the specified command. This can be used
to quickly extract, list or create multiple archives (see \fBEXAMPLES\fR
below). This option can not be used with the cat command.
.TP
.B \-F, \-\-format\fR=\fIEXTENSION\fR
Specify archive format manually (see \fBARCHIVE TYPES\fR below).
.TP
.B \-S, \-\-simulate
Run atool in simulation mode. No changes to the filesystem
(i.e. writes) will be made, and all commands that would be
executed are displayed instead. This option can't be combined
with \fB\-\-explain\fP (since it implies that already).
.TP
.B \-E, \-\-explain
Display commands executed by atool. This option can't be combined
with \fB\-\-simulate\fP.
.TP
.B \-p, \-\-page
Run output through a pager, usually \fBpager\fP.
.TP
.B \-f, \-\-force
When extracting from files, allow overwriting of local files.
When creating an archive, allow the archive file to be overwritten
if it already exists. Note that it is possible to add files to
existing RAR and Zip archives (this is not possible for many
other formats).
.TP
.B \-q, \-\-quiet
Decrease verbosity level by one. This is subtracted from the
default verbosity level, or the level specified
with \fB\-\-verbosity\fP. This option may be specified more than
once to make atool even less verbose.
.TP
.B \-v, \-\-verbose
Increase verbosity level by one. This is added to the
default verbosity level, or the level specified
with \fB\-\-verbosity\fP. This option may be specified more than
once to make atool even more verbose.
.TP
.B \-V, \-\-verbosity\fR=\fILEVEL\fR
Specify verbosity level. The default level is 1,
which means "normal verbosity" - e.g. when creating and
extracting from archives, files will be listed.
.TP
.B \-\-config\fR=\fIFILE\fR
Load configuration from the specified file. When using this
option, the system-wide and user-wide configuration files
will not be loaded. If the specified file does not exist or
can not be read, atool will terminate with an error message.
.TP
.B \-h, \-\-help
Show summary of options.
.TP
.B \-v, \-\-version
Output version information and exit.
.SH ARCHIVE TYPES
Unless the \-f (\-\-format) option is provided, the archive format
is determined by the archive file extension. I.e. an extension
".tar.gz" or ".tgz" means tar+gzip format. Note that the extensions
are checked in the other listed above, which is why a file
with extension ".tar.gz" is considered to a tar+gzip archive,
not a gzip archive.
.PP
The supported archive types are:
.TP
.RI \fBtar+gzip\fP " " ( .tar.gz ", " .tgz )
all commands supported
.TP
.RI \fBtar+bzip\fP " " ( .tar.bz ", " .tbz )
all commands supported
.TP
.RI \fBtar+bzip2\fP " " ( .tar.bz2 ", " .tbz2 )
all commands supported
.TP
.RI \fBtar+compress\fP " " ( .tar.Z ", " .tZ )
all commands supported
.TP
.RI \fBtar\fP " " ( .tar ", identified via file)"
all commands supported
.TP
.RI \fBzip\fP " " ( .zip ", identified via file)"
all commands supported
.TP
.RI \fBjar\fP " " ( .jar ", " .war ", identified via file)"
list, extract, add supported (and cat if $use_jar_program disabled)
.TP
.RI \fBrar\fP " " ( .rar ", identified via file)"
all commands supported
.TP
.RI \fBgzip\fP " " ( .gz )
cat, extract, add supported
.TP
.RI \fBbzip\fP " " ( .bz )
cat, extract, add supported
.TP
.RI \fBbzip2\fP " " ( .bz2 )
cat, extract, add supported
.TP
.RI \fBcompress\fP " " ( .Z )
cat, extract, add supported
.SH CONFIGURATION
Since version 0.8.0, atool can read custom configuration files.
First, hardcoded defaults in the atool program file are evaluated.
Then system-wide configuration values are loaded from
\fI/etc/atool.conf\fR if that file exists. Finally, per-user
configuration values are loaded from \fI.atoolrc\fR in the current
user's home directory.
.PP
The format of the configuration files is simple:
.IP
variable value
.PP
Here \fBvariable\fR is a variable listed below, and \fBvalue\fR is the
value to associate the variable with. \fBvariable\fR and \fBvalue\fR
should be separated with at least one whitespace (space, tab etc). Empty
lines and lines beginning with # are discarded.
.PP
A value of `1' means that the option is enabled, and `0'
that it is disabled. Strings should not be quoted, as they start at
the first non-whitespace character and end at the end of the line.
.PP
The options are:
.TP
.B use_tar_j_option \fR(default: 1)\fR
Enable this if you use GNU tar and it supports the \fB\-j\fP option
for filtering bzip2'ed files through bzip2. Versions 1.13.18
or later of GNU tar supports \fB\-j\fP. (Earlier versions used \fB\-I\fP,
but this was changed in 1.13.18.) Therefore, if you use a
GNU tar earlier than 1.13.18, you need to disable this option.
.TP
.B use_tar_z_option \fR(default: 1)\fR
Enable this if you use GNU tar and it supports the \fB-z\fP option
for filtering gzipped files through gzip. You will need to disable
this and \fIuse_tar_j_option\fR if you don't use GNU tar.

Disabling these two options doesn't mean that atool can't
extract bzip2/gzip files. If disabled, atool use a pipe to
send output from bzip2/gzip to tar instead.

If possible, these options should be enabled since error
management is better when filtering is done by tar.
.TP
.B use_gzip_for_z \fR(default: 1)\fR
Enable this if you want to use gzip instead of uncompress when
decompressing compress'ed files (`.Z' files).
.TP
.B use_jar \fR(default: 0)\fR
Enable this if you want to use jar for managing jar
archives. If you disable this option, zip will be
used (which should work just as well, and probably be
faster too).

This option is disabled by default since extracting
files to standard out (`cat') is not supported by jar.
.TP
.B use_file \fR(default: 1)\fR
Enable this if you want atool to identify file types
using file(1) for those files with an unrecognized
extension (or none at all).
    
Note that tar-archives compressed with a single-file-compressor
(gzip, bzip2 etc) can't be identified this way. For this reason,
files packed with gzip and other single-file-compressors are
not identified either.
.TP
.B tmpdir_name \fR(default: Unpack-%04d)\fR
atool extracts to a temporary directory created in the current
directory so that no files are overwritten. This variable
controlls what name that temporary directory should have.

The `%d' string in this variable will be replaced with a random
number between 0 and 9999. It is possible change the format
of this number by using something else than `%d' - see printf(3).
.TP
.B path_pager \fR(default: pager)\fR
.TP
.B path_jar \fR(default: jar)\fR
.TP
.B path_tar \fR(default: tar)\fR
.TP
.B path_zip \fR(default: zip)\fR
.TP
.B path_unzip \fR(default: unzip)\fR
.TP
.B path_gzip \fR(default: gzip)\fR
.TP
.B path_bzip \fR(default: bzip)\fR
.TP
.B path_bzip2 \fR(default: bzip2)\fR
.TP
.B path_compress \fR(default: compress)\fR
.TP
.B path_rar \fR(default: rar)\fR
.TP
.B path_file \fR(default: file)\fR
These are all paths to the corresponding programs. It is usually
best to leave them as is, since that way their locations can be
looked up from the PATH variable (by the shell).
.TP
.B path_syscfg \fR(default: /etc/atool.conf)\fR
(This variable can only be set in the atool program file.)
This variable specifies where the system-wide configuration
file is located.
.TP
.B path_usercfg \fR(default: .atoolrc)\fR
(This variable can only be set in the atool program file
and system-wide configuration file.)
This variable specifies where the user configuration file
is located. Note that if this filename is relative (i.e. doesn't
being with `/'), it will be relative to the current user's home
directory (as determined by the HOME environment variable).
.TP
.B default_verbosity \fR(default: 1)\fR
This is the default verbosity of atool. By using -q and -v
options, the verbosity level can be raised and lowered.
Level 1 means "normal verbosity" - e.g. when creating and
extracting from archives, files will be listed.
.SH EXAMPLES
To extract all files from archive `foobar.tar.gz' to a subdirectory
(or the current directory if it only contains one file):
.br
	\fBaunpack foobar.tar.gz\fP
.PP
To extract all files from all `.tar.gz' archives in the
current directory:
.br
	\fBaunpack -e *.tar.gz\fP
.PP
To create a zip archive of two files `foo' and `bar':
.br
	\fBapack myarchive.zip foo bar\fP
.PP
To display the file `baz' in the archive `myarchive.zip'
through a pager:
.br
	\fBacat -p myarchive.zip baz\fP
.PP
To list contents of the rar archive `stuff.rar':
.br
	\fBals stuff.rar\fP
.PP
To create three archives, `dir1.tar.gz', `dir2.tar.gz' and `dir3.tar.gz',
so that the first one contains all files in dir1, the second all
in dir2 and the third all dir3:
.br
	\fBapack -e -F .tar.gz dir1 dir2 dir3\fP
.SH KNOWN BUGS
Trying to extract gzip and other compressed files without the .gz (or .bz2
etc) extension won't work:
.PP
  aunpack: foo: format not known, identifying using file
  aunpack: foo: format is `gzip'
  gzip: foo: unknown suffix -- ignored
.PP
This last error above is generated by \fBgzip -d foo\fP.
.PP
If you find a bug not listed here, please report it to <osk@hem.passagen.se>.
.SH AUTHOR
atool was written by Oskar Liljeblad <osk@hem.passagen.se>.