2
.\" atool.1 - Manual page for atool.
4
.\" Copyright (C) 2001, 2002, 2003, 2004, 2005, 2007, 2008,
5
.\" 2009 Oskar Liljeblad
7
.\" This program is free software; you can redistribute it and/or modify
8
.\" it under the terms of the GNU General Public License as published by
9
.\" the Free Software Foundation; either version 2 of the License, or
10
.\" (at your option) any later version.
12
.\" This program is distributed in the hope that it will be useful,
13
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
14
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15
.\" GNU Library General Public License for more details.
17
.\" You should have received a copy of the GNU General Public License along
18
.\" with this program; if not, write to the Free Software Foundation,
19
.\" Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
21
.TH ATOOL "1" "August 8, 2009" "atool"
22
.\" Read this file with groff -man -Tascii atool.1
24
atool \- A script for managing file archives of various types
27
.RI [ OPTION ]... " ARCHIVE " [ FILE ]...
30
.RI [ OPTION ]... " ARCHIVE " [ FILE ]...
33
.RI [ OPTION ]... " ARCHIVE " [ FILE ]...
36
.RI [ OPTION ]... " ARCHIVE " [ FILE ]...
39
.RI [ OPTION ]... " ARCHIVE " [ FILE ]...
42
.RI [ OPTION ]... " ARCHIVE " "" ARCHIVE
45
.RI [ OPTION ]... OLD-ARCHIVE " " NEW-ARCHIVE
47
This manual page document describes the \fBatool\fP commands.
48
These commands are used for managing file archives of various
49
types, such as tar and Zip archives. Each command can be
50
executed individually or by giving the appropriate options
51
to \fBatool\fP (see \fBOPTIONS\fP below).
53
\fBaunpack\fP extracts files from an archive. Often one wants
54
to extract all files in an archive to a single subdirectory.
55
However, some archives contain multiple files in their root
56
directories. The aunpack program overcomes this problem by
57
first extracting files to a unique (temporary) directory, and
58
then moving its contents back if possible. This also prevents
59
local files from being overwritten by mistake.
61
\fBapack\fP creates archives (or compresses files). If no file
62
arguments are specified, filenames to add are read from standard in.
64
\fBals\fP lists files in an archive.
66
\fBacat\fP extracts files in an archive to standard out.
68
\fBadiff\fP generates a diff between two archives using
71
\fBarepack\fP repacks archives to a different format. It does
72
this by first extracting all files of the old archive into a
73
temporary directory, then packing all files extracted to
74
that directory to the new archive. Use the \-\-each (\-e) option in
75
combination with \-\-format (\-F) to repack multiple archives using a
76
single invocation of atool. Note that arepack will not remove the old
79
Unless the \fB\-\-format\fP (\fB\-F\fP) option is provided,
80
the archive format is determined by the archive file extension. I.e.
81
an extension ".tar.gz" or ".tgz" means tar+gzip format. Note that
82
the extensions are checked in the order listed in the section
83
\fBARCHIVE TYPES\fP below, which is why a file with extension ".tar.gz"
84
is considered to a be tar+gzip archive, not a gzip compressed file.
86
These programs follow the usual GNU command line syntax, with long
87
options starting with two dashes (`-').
88
A summary of options is included below.
91
List files in archive.
92
This option is automaticly assumed when \fBals\fP is executed.
95
Extract files from archive.
96
This option is automaticly assumed when \fBaunpack\fP is executed.
98
.B \-X, \-\-extract-to\fR=\fIPATH\fR
99
Extract files from archive to the specified directory. When
100
unpacking compressed files, PATH may refer to either a filename
101
or an existing directory.
105
This option is automaticly assumed when \fBapack\fP is executed.
108
Extract a file from archive to standard out (displaying it on
110
This option is automaticly assumed when \fBacat\fP is executed.
113
Extract two archives and use diff(1) to generate differencies
115
This option is automaticly assumed when \fBadiff\fP is executed.
118
For each argument, execute the specified command. This can be used
119
to quickly extract, list or create multiple archives (see \fBEXAMPLES\fR
120
below). This option can not be used with the cat command.
122
.B \-F, \-\-format\fR=\fIEXTENSION\fR
123
Specify archive format manually (see \fBARCHIVE TYPES\fR below).
126
Run atool in simulation mode. No changes to the filesystem
127
(i.e. writes) will be made, and all commands that would be
128
executed are displayed instead. This option can't be combined
129
with \fB\-\-explain\fP (since it implies that already).
131
Note that it is not guaranteed that the commands printed in
132
simulation mode will be the same as those executed in non-
133
simulation mode. This is because some operations depend on
134
what files archives contain, and atool can at this time
135
only determine that by extracting archives.
138
Display commands executed by atool. This option can't be combined
139
with \fB\-\-simulate\fP.
142
Run output through a pager, usually \fBpager\fP unless the environment
143
variable \fBPAGER\fP is set.
146
When extracting from files, allow overwriting of local files.
147
When creating an archive, allow the archive file to be overwritten
148
if it already exists. Note that it is possible to add files to
149
existing RAR and Zip archives (this is not possible for many
153
When extracting archives, always create a new directory for
154
the archive even if the archive only contains one file in
158
If no file arguments are specified when creating or adding files
159
to archives, the list of files will be read from standard in.
160
Normally these filenames are separated by newline, but with this
161
option they are separated by null-bytes. This is useful with the
162
GNU find \-print0 option.
165
Decrease verbosity level by one. This is subtracted from the
166
default verbosity level, or the level specified
167
with \fB\-\-verbosity\fP. This option may be specified more than
168
once to make atool even less verbose.
171
Increase verbosity level by one. This is added to the
172
default verbosity level, or the level specified
173
with \fB\-\-verbosity\fP. This option may be specified more than
174
once to make atool even more verbose.
176
.B \-V, \-\-verbosity\fR=\fILEVEL\fR
177
Specify verbosity level. The default level is 1,
178
which means "normal verbosity" - e.g. when creating and
179
extracting from archives, files will be listed.
181
.B \-\-config\fR=\fIFILE\fR
182
Load configuration from the specified file. When using this
183
option, the system-wide and user-wide configuration files
184
will not be loaded. If the specified file does not exist or
185
can not be read, atool will terminate with an error message.
187
.B \-o, \-\-option\fR=\fIKEY=VALUE\fR
188
Override a configuration option. These are applied after
189
reading the configuration files.
191
You can specify this multiple times to override different options.
193
.B \-\-save\-outdir\fR=\fIFILE\fR
194
When extracting files, save the name of the directory which
195
the archive was extracted to to the specified file. If the
196
command was not `extract', or the archive was not extracted to
197
a new directory, then nothing will be written to the specified
198
file. If multiple archives were specified (with \-e), then
199
only the last directory that files were extracted to will be
202
This option is used internally (see \fBEXAMPLES\fR below).
205
Show summary of options.
208
Output version information and exit.
210
Unless the \-f (\-\-format) option is provided, the archive format
211
is determined by the archive file extension. I.e. an extension
212
".tar.gz" or ".tgz" means tar+gzip format. Note that the extensions
213
are checked in the other listed above, which is why a file
214
with extension ".tar.gz" is considered to a tar+gzip archive,
217
The diff command is supported whenever the extract command is
220
The supported archive types are:
222
.RI \fBtar+gzip\fP " " ( .tar.gz ", " .tgz )
223
All commands are supported.
225
.RI \fBtar+bzip\fP " " ( .tar.bz ", " .tbz )
226
All commands are supported.
228
.RI \fBtar+bzip2\fP " " ( .tar.bz2 ", " .tbz2 )
229
All commands are supported.
231
.RI \fBtar+compress\fP " " ( .tar.Z ", " .tZ )
232
All commands are supported.
234
.RI \fBtar+lzop\fP " " ( .tar.lzo ", " .tzo )
235
All commands are supported.
237
.RI \fBtar+lzip\fP " " ( .tar.lz ", " .tlz )
238
All commands are supported.
240
.RI \fBtar+xz\fP " " ( .tar.xz ", " .txz )
241
All commands are supported.
243
.RI \fBtar+7z\fP " " ( .tar.7z ", " .t7z )
244
All commands are supported.
246
.RI \fBtar\fP " " ( .tar )
247
All commands are supported.
249
.RI \fBzip\fP " " ( .zip )
250
All commands are supported.
252
.RI \fBjar\fP " " ( .jar ", " .war )
253
List, extract, and add commands are supported.
254
Cat is supported if use_jar_program is disabled.
256
.RI \fBrar\fP " " ( .rar )
257
All commands are supported.
259
.RI \fBlha\fP " " ( .lha ", " .lzh )
260
All commands are supported.
262
.RI \fB7z\fP " " ( .7z )
263
Extract, list and add commands are supported.
265
.RI \fBalzip\fP " " ( .alz )
266
Extract command is supported.
268
.RI \fBace\fP " " ( .ace )
269
Extract and list commands are supported.
271
.RI \fBar\fP " " ( .a )
272
All commands are supported.
274
.RI \fBarj\fP " " ( .arj )
275
List, extract and add commands are supported.
277
.RI \fBarc\fP " " ( .arc )
278
All command are supported.
279
(Note that arc outputs an extra newline when the cat command is used.)
281
.RI \fBrpm\fP " " ( .rpm )
282
Extract and list commands are supported.
284
.RI \fBdeb\fP " " ( .deb )
285
Extract and list commands are supported.
287
.RI \fBcab\fP " " ( .cab )
288
Cat, extract, and list commands are supported.
290
.RI \fBgzip\fP " " ( .gz )
291
Cat, extract, and add commands are supported.
293
.RI \fBbzip\fP " " ( .bz )
294
Cat, extract, and add commands are supported.
296
.RI \fBbzip2\fP " " ( .bz2 )
297
Cat, extract, and add commands are supported.
299
.RI \fBcompress\fP " " ( .Z )
300
Cat, extract, and add commands are supported.
302
.RI \fBlzma\fP " " ( .lzma )
303
Cat, extract, and add commands are supported.
305
.RI \fBlzop\fP " " ( .lzo )
306
Extract and add commands are supported. The cat command is not suppored
307
because lzop does not want to extract files to standard out unless the -f
310
.RI \fBlzip\fP " " ( .lz )
311
Cat, extract, and add commands are supported.
313
.RI \fBxz\fP " " ( .xz )
314
Cat, extract, and add commands are supported.
316
.RI \fBrzip\fP " " ( .rz )
317
Extract and add commands are supported.
319
.RI \fBlrzip\fP " " ( .lrz )
320
Extract and add commands are supported.
322
.RI \fB7zip\fP " " ( .7z )
323
All commands are supported.
324
(Note that 7z refuses to write extracted files to standard out
325
if standard out is a terminal. Use \-p or pipe the output
326
of atool/acat to a pager when reading in a terminal.)
328
.RI \fBcpio\fP " " ( .cpio )
329
List, extract and add commands are supported.
333
Since version 0.8.0, atool can read custom configuration files.
334
First, hardcoded defaults in the atool program file are evaluated.
335
Then system-wide configuration values are loaded from
336
\fI/etc/atool.conf\fR if that file exists. Finally, per-user
337
configuration values are loaded from \fI.atoolrc\fR in the current
338
user's home directory.
340
The format of the configuration files is simple:
344
Here \fBvariable\fR is a variable listed below, and \fBvalue\fR is the
345
value to associate the variable with. \fBvariable\fR and \fBvalue\fR
346
should be separated with at least one whitespace (space, tab etc). Empty
347
lines and lines beginning with # are discarded.
349
A value of `1' means that the option is enabled, and `0'
350
that it is disabled. Strings should not be quoted, as they start at
351
the first non-whitespace character and end at the end of the line.
355
.B use_tar_bzip2_option \fR(default: 1)\fR
356
Enable this if you use GNU tar and it supports the \fB\-\-bzip2\fP option
357
for filtering bzip2'ed files through bzip2. Versions 1.13.6
358
or later of GNU tar support \fB\-\-bzip2\fP. Therefore, if you use
359
GNU tar earlier than 1.13.6, you will need to disable this option.
361
This used to be \fBuse_tar_j_option\fP but using \-\-bzip2 is more portable.
363
.B use_tar_z_option \fR(default: 1)\fR
364
Enable this if you use GNU tar and it supports the \fB\-z\fP option
365
for filtering gzipped files through gzip. You will need to disable
366
this and \fIuse_tar_j_option\fR if you don't use GNU tar.
368
Disabling these two options doesn't mean that atool can't
369
extract bzip2/gzip files. If disabled, atool use a pipe to
370
send output from bzip2/gzip to tar instead.
372
If possible, these options should be enabled since error
373
management is better when filtering is done by tar.
375
.B use_tar_lzma_option \fR(default: 1)\fR
376
Enable this if you use GNU tar and it supports the \fB\-\-lzma\fP option
377
for filtering lzma compressed files through lzma. Versions 1.20
378
or later of GNU tar support \fB\-\-lzma\fP.
380
.B use_tar_lzop_option \fR(default: 0)\fR
381
Enable this if you use GNU tar and it supports the \fB\-\-lzop\fP option
382
for filtering lzop compressed files through lzop. Versions 1.21
383
or later of GNU tar support \fB\-\-lzop\fP.
385
.B use_tar_xv_option \fR(default: 0)\fR
386
Enable this if you use GNU tar and it supports the \fB\-\-xv\fP option
387
for filtering xv compressed files through xv. Versions 1.22
388
or later of GNU tar support \fB\-\-xv\fP.
390
.B use_gzip_for_z \fR(default: 1)\fR
391
Enable this if you want to use gzip instead of uncompress when
392
decompressing compress'ed files (`.Z' files).
394
.B use_rar_for_unpack \fR(default: 0)\fR
395
Enable this if you want to always use rar instead of unrar
396
when possible. This makes atool use the rar command
397
(path_rar) even when listing and extracting RAR files.
399
.B use_arc_for_unpack \fR(default: 0)\fR
400
Enable this if you want to always use arc instead of nomarch
401
when possible. This makes atool use the arc command
402
(path_arc) even when listing and extracting ARC files.
404
.B use_arj_for_unpack \fR(default: 0)\fR
405
Enable this if you want to always use arj instead of unarj
406
when possible. This makes atool use the arj command
407
(path_arj) even when listing and extracting ARJ files.
409
.B use_find_cpio_print0 \fR(default: 1)\fR
410
Enable this if find supports the \-print0 option and cpio supports
411
the \-0 option. Without it, it is impossible/harder to make cpio
412
archives of files with newline characters in their names.
414
.B extract_deb_control \fR(default: 1)\fR
415
Debian .deb package files contain control information in a DEBIAN
416
directory, especially the package's "control" file. Enable this if
417
you want the control information to be exctracted during extraction in
418
addition to the normal files.
420
.B strip_unknown_ext \fR(default: 1)\fR
421
Certain types of files are actually archives, but their extensions
422
doesn't tell so. Examples are Open Office documents (Zip files) and
423
Gnumeric documents (gzip'ed files). Since the extensions of those
424
filenames are unknown to atool, they would not be stripped with
425
this option set to 0. The output file in that case would be something
426
like Unpack-XYZW. Setting this option to 1 will cause the extension
427
to be stripped instead.
429
.B use_pbzip2 \fR(default: 0)\fR
430
Enable this if you want to use pbzip2 rather than bzip2.
431
Please not that if use_tar_bzip2_option is enabled, then
432
bzip2 will be used by tar regardless of the use_pbzip2
433
option. So if you want tar to use pbzip2 rather than bzip2,
434
set use_pbzip2 to 1 and use_tar_bzip2_option to 0.
436
.B use_jar \fR(default: 0)\fR
437
Enable this if you want to use jar for managing jar
438
archives. If you disable this option, zip will be
439
used (which should work just as well, and probably be
442
This option is disabled by default since extracting
443
files to standard out (`cat') is not supported by jar.
445
.B use_file \fR(default: 1)\fR
446
Enable this if you want atool to identify file types
447
using file(1) for those files with an unrecognized
448
extension (or none at all).
450
.B use_file_always \fR(default: 0)\fR
451
Enable this if you want atool to always identify archives
452
using file(1), regardless of the file extension. Please note
453
that this currently has some drawbacks, such as not being able
454
to identify all archive types (especially tar archives compressed
455
with 7zip, lzop, szip etc).
457
.B tmpdir_name \fR(default: Unpack-%04d)\fR
458
atool extracts to a temporary directory created in the current
459
directory so that no files are overwritten. This variable
460
controlls what name that temporary directory should have.
462
The `%d' string in this variable will be replaced with a random
463
number between 0 and 9999. It is possible change the format
464
of this number by using something else than `%d' - see printf(3).
466
.B tmpfile_name \fR(default: Pack-%04d)\fR
467
When using pbzip2, and creating archives, a temporary file need
468
to be created. This option controls the name of that file.
469
See tmpdir_name for further details on the format.
471
.B path_pager \fR(default: pager)\fR
473
.B path_jar \fR(default: jar)\fR
475
.B path_tar \fR(default: tar)\fR
477
.B path_zip \fR(default: zip)\fR
479
.B path_unzip \fR(default: unzip)\fR
481
.B path_gzip \fR(default: gzip)\fR
483
.B path_bzip \fR(default: bzip)\fR
485
.B path_bzip2 \fR(default: bzip2)\fR
487
.B path_pbzip2 \fR(default: pbzip2)\fR
489
.B path_compress \fR(default: compress)\fR
491
.B path_lzma \fR(default: lzma)\fR
493
.B path_lzop \fR(default: lzop)\fR
495
.B path_lzip \fR(default: lzip)\fR
497
.B path_rar \fR(default: rar)\fR
499
.B path_unrar \fR(default: unrar)\fR
501
.B path_cabextract \fR(default: cabextract)\fR
503
.B path_7z \fR(default: 7z)\fR
505
.B path_unalz \fR(default: unalz)\fR
507
.B path_lha \fR(default: lha)\fR
509
.B path_unace \fR(default: unace)\fR
511
.B path_ar \fR(default: ar)\fR
513
.B path_arj \fR(default: arj)\fR
515
.B path_unarj \fR(default: unarj)\fR
517
.B path_arc \fR(default: arc)\fR
519
.B path_nomarch \fR(default: nomarch)\fR
521
.B path_rpm \fR(default: rpm)\fR
523
.B path_rpm2cpio \fR(default: rpm2cpio)\fR
525
.B path_dpkg_deb \fR(default: dpkg-deb)\fR
527
.B path_cpio \fR(default: cpio)\fR
529
.B path_file \fR(default: file)\fR
531
.B path_find \fR(default: find)\fR
533
.B path_xargs \fR(default: xargs)\fR
535
.B path_cat \fR(default: cat)\fR
537
.B path_diff \fR(default: diff)\fR
538
These are all paths to the corresponding programs. It is usually
539
best to leave them as is, because that way their locations can be
540
looked up from the PATH variable.
542
.B args_diff \fR(default: \-ru)\fR
543
This variable specifies command line arguments to pass to the
544
diff command (as specified by path_diff) when using adiff. Space
545
characters separate arguments in this string.
547
.B path_syscfg \fR(default: /etc/atool.conf)\fR
548
(This variable can only be set in the atool program file.)
549
This variable specifies the directory where the system-wide
550
configuration file is located.
552
.B path_usercfg \fR(default: .atoolrc)\fR
553
(This variable can only be set in the atool program file
554
and system-wide configuration file.)
555
This variable specifies where the user configuration file
556
is located. Note that if this filename is relative (i.e. doesn't
557
being with `/'), it will be relative to the current user's home
558
directory (as determined by the HOME environment variable).
560
.B default_verbosity \fR(default: 1)\fR
561
This is the default verbosity of atool. By using \-q and \-v
562
options, the verbosity level can be raised and lowered.
563
Level 1 means "normal verbosity" - e.g. when creating and
564
extracting from archives, files will be listed.
566
.B show_extracted \fR(default: 1)\fR
567
If this is set to 1, the aunpack command will always show
568
what file or directory that was extracted. Otherwise
569
that will only be printed if the archive was extracted to
570
an unexpected location (as a result of local files already
571
existing or the archive having multiple files in its root
574
This can be quite useful in combinatiaon with `default_verbosity 0'.
575
Note that this option will have no effect when the \-X option is used
576
with aunpack, and it has no effect on compressed files.
578
.B keep_compressed \fR(default: 1)\fR
579
When compressing a file with gzip or bzip2, the original (uncompressed)
580
file is usually deleted once it has been compressed. I.e. if you
581
compress a file "test" you will end up with only one file, "test.gz".
582
With this option set to 1, you will make atool keep the original file
583
as well. The original behaviour is achieved by setting this option to 0.
585
This option also has an equivalent effect on uncompressing compressed
586
files. When set to 1, the original (compressed) file will be kept.
587
Otherwise it will be deleted.
589
Note however that this option has no effect when packing up a compressed
590
file with the \-X option (for specifying an output directory or file). In
591
that case the original file is always kept.
593
.B decompress_to_cwd \fR(default: 1)\fR
594
When decompressing a file with commands such as gzip or bzip2, the
595
decompressed file is usually placed in the same directory as the
596
compressed file. With this option set to 1, the decompressed file is
597
instead placed in the current working directory.
599
Note that this option has no effect when \-X is used.
601
.SH ENVIRONMENT VARIABLES
603
The default pager to use when the \-p/\-\-page option is specified.
605
To extract all files from archive `foobar.tar.gz' to a subdirectory
606
(or the current directory if it only contains one file):
608
\fBaunpack foobar.tar.gz\fP
610
To extract all files from all `.tar.gz' archives in the
613
\fBaunpack \-e *.tar.gz\fP
615
To create a zip archive of two files `foo' and `bar':
617
\fBapack myarchive.zip foo bar\fP
619
To display the file `baz' in the archive `myarchive.zip'
622
\fBacat \-p myarchive.zip baz\fP
624
To list contents of the rar archive `stuff.rar':
628
To create three archives, `dir1.tar.gz', `dir2.tar.gz' and `dir3.tar.gz',
629
so that the first one contains all files in dir1, the second all
630
in dir2 and the third all dir3:
632
\fBapack \-e \-F .tar.gz dir1 dir2 dir3\fP
634
To show all differences between version 2.4.17 and 2.4.18 of the kernel:
636
\fBadiff linux-2.4.17.tar.gz linux-2.4.18.tar.gz\fP
638
To repack all .tar.gz archives in the current directory to .tar.7z (the
639
old archive will be kept untouched):
641
\fBarepack \-F.tar.7z \-e *.tar.gz\fP
643
Here's a shell function that will make the aunpack command change into the
644
directory where files were extracted:
648
\fB TMP=`mktemp /tmp/aunpack.XXXXXXXXXX`\fP
650
\fB atool \-x \-\-save-outdir=$TMP "$@"\fP
652
\fB DIR="`cat $TMP`"\fP
654
\fB [ "$DIR" != "" \-a \-d "$DIR" ] && cd "$DIR"\fP
660
If you don't have the mktemp program, you can replace the second line with
661
(note however that this is not entirely safe)
663
\fB TMP="/tmp/atool_outdir.$$"\fP
666
Trying to extract gzip and other compressed files without the .gz (or .bz2
667
etc) extension won't work:
669
aunpack: foo: format not known, identifying using file
670
aunpack: foo: format is `gzip'
671
gzip: foo: unknown suffix -- ignored
673
This last error above is generated by \fBgzip \-d foo\fP.
675
If you find a bug not listed here, please report it to <@PACKAGE_BUGREPORT@>.
677
Report bugs to <\fIoskar@osk.mine.nu\fP>.
679
The author of \fBatool\fP and this manual page is Oskar Liljeblad <\fIoskar@osk.mine.nu\fP>.
681
Copyright \(co 2001, 2002, 2003, 2004, 2005, 2007, 2008, 2009 Oskar Liljeblad
683
This is free software; see the source for copying conditions. There is NO
684
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.