1ATOOL(1) General Commands Manual ATOOL(1)
2
6 atool - A script for managing file archives of various types
7
9 atool [OPTION]... ARCHIVE [FILE]...
10 aunpack [OPTION]... ARCHIVE [FILE]...
11 apack [OPTION]... ARCHIVE [FILE]...
12 als [OPTION]... ARCHIVE [FILE]...
13 acat [OPTION]... ARCHIVE [FILE]...
14 adiff [OPTION]... ARCHIVE ARCHIVE
15 arepack [OPTION]...OLD-ARCHIVE NEW-ARCHIVE
16
18 This manual page document describes the atool commands. These commands
19 are used for managing file archives of various types, such as tar and
20 Zip archives. Each command can be executed individually or by giving
21 the appropriate options to atool (see OPTIONS below).
22 aunpack extracts files from an archive. Often one wants to extract all
24 files in an archive to a single subdirectory. However, some archives
25 contain multiple files in their root directories. The aunpack program
26 overcomes this problem by first extracting files to a unique (tempo‐
27 rary) directory, and then moving its contents back if possible. This
28 also prevents local files from being overwritten by mistake.
29 apack creates archives (or compresses files). If no file arguments are
31 specified, filenames to add are read from standard in.
32 als lists files in an archive.
34 acat extracts files in an archive to standard out.
36 adiff generates a diff between two archives using diff(1).
38 arepack repacks archives to a different format. It does this by first
40 extracting all files of the old archive into a temporary directory,
41 then packing all files extracted to that directory to the new archive.
42 Use the --each (-e) option in combination with --format (-F) to repack
43 multiple archives using a single invocation of atool. Note that arepack
44 will not remove the old archive.
45 Unless the --format (-F) option is provided, the archive format is
47 determined by the archive file extension. I.e. an extension ".tar.gz"
48 or ".tgz" means tar+gzip format. Note that the extensions are checked
49 in the order listed in the section ARCHIVE TYPES below, which is why a
50 file with extension ".tar.gz" is considered to a be tar+gzip archive,
51 not a gzip compressed file.
52
54 These programs follow the usual GNU command line syntax, with long
55 options starting with two dashes (`-'). A summary of options is
56 included below.
57 -l, --list
59 List files in archive. This option is automaticly assumed when
60 als is executed.
61 -x, --extract
63 Extract files from archive. This option is automaticly assumed
64 when aunpack is executed.
65 -X, --extract-to=PATH
67 Extract files from archive to the specified directory. When
68 unpacking compressed files, PATH may refer to either a filename
69 or an existing directory.
70 -a, --add
72 Create archive. This option is automaticly assumed when apack
73 is executed.
74 -c, --cat
76 Extract a file from archive to standard out (displaying it on
77 screen). This option is automaticly assumed when acat is exe‐
78 cuted.
79 -d, --diff
81 Extract two archives and use diff(1) to generate differencies
82 between them. This option is automaticly assumed when adiff is
83 executed.
84 -e, --each
86 For each argument, execute the specified command. This can be
87 used to quickly extract, list or create multiple archives (see
88 EXAMPLES below). This option can not be used with the cat com‐
89 mand.
90 -F, --format=EXTENSION
92 Specify archive format manually (see ARCHIVE TYPES below).
93 -S, --simulate
95 Run atool in simulation mode. No changes to the filesystem (i.e.
96 writes) will be made, and all commands that would be executed
97 are displayed instead. This option can't be combined with
98 --explain (since it implies that already).
99 Note that it is not guaranteed that the commands printed in sim‐
101 ulation mode will be the same as those executed in non- simula‐
102 tion mode. This is because some operations depend on what files
103 archives contain, and atool can at this time only determine that
104 by extracting archives.
105 -E, --explain
107 Display commands executed by atool. This option can't be com‐
108 bined with --simulate.
109 -p, --page
111 Run output through a pager, usually pager unless the environment
112 variable PAGER is set.
113 -f, --force
115 When extracting from files, allow overwriting of local files.
116 When creating an archive, allow the archive file to be overwrit‐
117 ten if it already exists. Note that it is possible to add files
118 to existing RAR and Zip archives (this is not possible for many
119 other formats).
120 -D, --subdir
122 When extracting archives, always create a new directory for the
123 archive even if the archive only contains one file in its root
124 directory.
125 -0, --null
127 If no file arguments are specified when creating or adding files
128 to archives, the list of files will be read from standard in.
129 Normally these filenames are separated by newline, but with this
130 option they are separated by null-bytes. This is useful with the
131 GNU find -print0 option.
132 -q, --quiet
134 Decrease verbosity level by one. This is subtracted from the
135 default verbosity level, or the level specified with --ver‐
136 bosity. This option may be specified more than once to make
137 atool even less verbose.
138 -v, --verbose
140 Increase verbosity level by one. This is added to the default
141 verbosity level, or the level specified with --verbosity. This
142 option may be specified more than once to make atool even more
143 verbose.
144 -V, --verbosity=LEVEL
146 Specify verbosity level. The default level is 1, which means
147 "normal verbosity" - e.g. when creating and extracting from ar‐
148 chives, files will be listed.
149 --config=FILE
151 Load configuration from the specified file. When using this
152 option, the system-wide and user-wide configuration files will
153 not be loaded. If the specified file does not exist or can not
154 be read, atool will terminate with an error message.
155 -o, --option=KEY=VALUE
157 Override a configuration option. These are applied after reading
158 the configuration files.
159 You can specify this multiple times to override different
161 options.
162 --save-outdir=FILE
164 When extracting files, save the name of the directory which the
165 archive was extracted to to the specified file. If the command
166 was not `extract', or the archive was not extracted to a new
167 directory, then nothing will be written to the specified file.
168 If multiple archives were specified (with -e), then only the
169 last directory that files were extracted to will be written to
170 FILE.
171 This option is used internally (see EXAMPLES below).
173 --help Show summary of options.
175 --version
177 Output version information and exit.
178
180 Unless the -f (--format) option is provided, the archive format is
181 determined by the archive file extension. I.e. an extension ".tar.gz"
182 or ".tgz" means tar+gzip format. Note that the extensions are checked
183 in the other listed above, which is why a file with extension ".tar.gz"
184 is considered to a tar+gzip archive, not a gzip archive.
185 The diff command is supported whenever the extract command is sup‐
187 ported.
188 The supported archive types are:
190 tar+gzip (.tar.gz, .tgz)
192 All commands are supported.
193 tar+bzip (.tar.bz, .tbz)
195 All commands are supported.
196 tar+bzip2 (.tar.bz2, .tbz2)
198 All commands are supported.
199 tar+compress (.tar.Z, .tZ)
201 All commands are supported.
202 tar+lzop (.tar.lzo, .tzo)
204 All commands are supported.
205 tar+lzip (.tar.lz, .tlz)
207 All commands are supported.
208 tar+xz (.tar.xz, .txz)
210 All commands are supported.
211 tar+7z (.tar.7z, .t7z)
213 All commands are supported.
214 tar (.tar)
216 All commands are supported.
217 zip (.zip)
219 All commands are supported.
220 jar (.jar, .war)
222 List, extract, and add commands are supported. Cat is supported
223 if use_jar_program is disabled.
224 rar (.rar)
226 All commands are supported.
227 lha (.lha, .lzh)
229 All commands are supported.
230 7z (.7z)
232 Extract, list and add commands are supported.
233 alzip (.alz)
235 Extract command is supported.
236 ace (.ace)
238 Extract and list commands are supported.
239 ar (.a)
241 All commands are supported.
242 arj (.arj)
244 List, extract and add commands are supported.
245 arc (.arc)
247 All command are supported. (Note that arc outputs an extra new‐
248 line when the cat command is used.)
249 rpm (.rpm)
251 Extract and list commands are supported.
252 deb (.deb)
254 Extract and list commands are supported.
255 cab (.cab)
257 Cat, extract, and list commands are supported.
258 gzip (.gz)
260 Cat, extract, and add commands are supported.
261 bzip (.bz)
263 Cat, extract, and add commands are supported.
264 bzip2 (.bz2)
266 Cat, extract, and add commands are supported.
267 compress (.Z)
269 Cat, extract, and add commands are supported.
270 lzma (.lzma)
272 Cat, extract, and add commands are supported.
273 lzop (.lzo)
275 Extract and add commands are supported. The cat command is not
276 suppored because lzop does not want to extract files to standard
277 out unless the -f flag is given.
278 lzip (.lz)
280 Cat, extract, and add commands are supported.
281 xz (.xz)
283 Cat, extract, and add commands are supported.
284 rzip (.rz)
286 Extract and add commands are supported.
287 lrzip (.lrz)
289 Extract and add commands are supported.
290 7zip (.7z)
292 All commands are supported. (Note that 7z refuses to write
293 extracted files to standard out if standard out is a terminal.
294 Use -p or pipe the output of atool/acat to a pager when reading
295 in a terminal.)
296 cpio (.cpio)
298 List, extract and add commands are supported.
299
303 Since version 0.8.0, atool can read custom configuration files. First,
304 hardcoded defaults in the atool program file are evaluated. Then sys‐
305 tem-wide configuration values are loaded from /etc/atool.conf if that
306 file exists. Finally, per-user configuration values are loaded from
307 .atoolrc in the current user's home directory.
308 The format of the configuration files is simple:
310 variable value
312 Here variable is a variable listed below, and value is the value to as‐
314 sociate the variable with. variable and value should be separated with
315 at least one whitespace (space, tab etc). Empty lines and lines begin‐
316 ning with # are discarded.
317 A value of `1' means that the option is enabled, and `0' that it is
319 disabled. Strings should not be quoted, as they start at the first non-
320 whitespace character and end at the end of the line.
321 The options are:
323 use_tar_bzip2_option (default: 1)
325 Enable this if you use GNU tar and it supports the --bzip2
326 option for filtering bzip2'ed files through bzip2. Versions
327 1.13.6 or later of GNU tar support --bzip2. Therefore, if you
328 use GNU tar earlier than 1.13.6, you will need to disable this
329 option.
330 This used to be use_tar_j_option but using --bzip2 is more por‐
332 table.
333 use_tar_z_option (default: 1)
335 Enable this if you use GNU tar and it supports the -z option for
336 filtering gzipped files through gzip. You will need to disable
337 this and use_tar_j_option if you don't use GNU tar.
338 Disabling these two options doesn't mean that atool can't
340 extract bzip2/gzip files. If disabled, atool use a pipe to send
341 output from bzip2/gzip to tar instead.
342 If possible, these options should be enabled since error manage‐
344 ment is better when filtering is done by tar.
345 use_tar_lzma_option (default: 1)
347 Enable this if you use GNU tar and it supports the --lzma option
348 for filtering lzma compressed files through lzma. Versions 1.20
349 or later of GNU tar support --lzma.
350 use_tar_lzop_option (default: 0)
352 Enable this if you use GNU tar and it supports the --lzop option
353 for filtering lzop compressed files through lzop. Versions 1.21
354 or later of GNU tar support --lzop.
355 use_tar_xv_option (default: 0)
357 Enable this if you use GNU tar and it supports the --xv option
358 for filtering xv compressed files through xv. Versions 1.22 or
359 later of GNU tar support --xv.
360 use_gzip_for_z (default: 1)
362 Enable this if you want to use gzip instead of uncompress when
363 decompressing compress'ed files (`.Z' files).
364 use_rar_for_unpack (default: 0)
366 Enable this if you want to always use rar instead of unrar when
367 possible. This makes atool use the rar command (path_rar) even
368 when listing and extracting RAR files.
369 use_arc_for_unpack (default: 0)
371 Enable this if you want to always use arc instead of nomarch
372 when possible. This makes atool use the arc command (path_arc)
373 even when listing and extracting ARC files.
374 use_arj_for_unpack (default: 0)
376 Enable this if you want to always use arj instead of unarj when
377 possible. This makes atool use the arj command (path_arj) even
378 when listing and extracting ARJ files.
379 use_find_cpio_print0 (default: 1)
381 Enable this if find supports the -print0 option and cpio sup‐
382 ports the -0 option. Without it, it is impossible/harder to make
383 cpio archives of files with newline characters in their names.
384 extract_deb_control (default: 1)
386 Debian .deb package files contain control information in a
387 DEBIAN directory, especially the package's "control" file.
388 Enable this if you want the control information to be exctracted
389 during extraction in addition to the normal files.
390 strip_unknown_ext (default: 1)
392 Certain types of files are actually archives, but their exten‐
393 sions doesn't tell so. Examples are Open Office documents (Zip
394 files) and Gnumeric documents (gzip'ed files). Since the exten‐
395 sions of those filenames are unknown to atool, they would not be
396 stripped with this option set to 0. The output file in that case
397 would be something like Unpack-XYZW. Setting this option to 1
398 will cause the extension to be stripped instead.
399 use_pbzip2 (default: 0)
401 Enable this if you want to use pbzip2 rather than bzip2. Please
402 not that if use_tar_bzip2_option is enabled, then bzip2 will be
403 used by tar regardless of the use_pbzip2 option. So if you want
404 tar to use pbzip2 rather than bzip2, set use_pbzip2 to 1 and
405 use_tar_bzip2_option to 0.
406 use_jar (default: 0)
408 Enable this if you want to use jar for managing jar archives. If
409 you disable this option, zip will be used (which should work
410 just as well, and probably be faster too).
411 This option is disabled by default since extracting files to
413 standard out (`cat') is not supported by jar.
414 use_file (default: 1)
416 Enable this if you want atool to identify file types using
417 file(1) for those files with an unrecognized extension (or none
418 at all).
419 use_file_always (default: 0)
421 Enable this if you want atool to always identify archives using
422 file(1), regardless of the file extension. Please note that this
423 currently has some drawbacks, such as not being able to identify
424 all archive types (especially tar archives compressed with 7zip,
425 lzop, szip etc).
426 tmpdir_name (default: Unpack-%04d)
428 atool extracts to a temporary directory created in the current
429 directory so that no files are overwritten. This variable con‐
430 trolls what name that temporary directory should have.
431 The `%d' string in this variable will be replaced with a random
433 number between 0 and 9999. It is possible change the format of
434 this number by using something else than `%d' - see printf(3).
435 tmpfile_name (default: Pack-%04d)
437 When using pbzip2, and creating archives, a temporary file need
438 to be created. This option controls the name of that file. See
439 tmpdir_name for further details on the format.
440 path_pager (default: pager)
442 path_jar (default: jar)
444 path_tar (default: tar)
446 path_zip (default: zip)
448 path_unzip (default: unzip)
450 path_gzip (default: gzip)
452 path_bzip (default: bzip)
454 path_bzip2 (default: bzip2)
456 path_pbzip2 (default: pbzip2)
458 path_compress (default: compress)
460 path_lzma (default: lzma)
462 path_lzop (default: lzop)
464 path_lzip (default: lzip)
466 path_rar (default: rar)
468 path_unrar (default: unrar)
470 path_cabextract (default: cabextract)
472 path_7z (default: 7z)
474 path_unalz (default: unalz)
476 path_lha (default: lha)
478 path_unace (default: unace)
480 path_ar (default: ar)
482 path_arj (default: arj)
484 path_unarj (default: unarj)
486 path_arc (default: arc)
488 path_nomarch (default: nomarch)
490 path_rpm (default: rpm)
492 path_rpm2cpio (default: rpm2cpio)
494 path_dpkg_deb (default: dpkg-deb)
496 path_cpio (default: cpio)
498 path_file (default: file)
500 path_find (default: find)
502 path_xargs (default: xargs)
504 path_cat (default: cat)
506 path_diff (default: diff)
508 These are all paths to the corresponding programs. It is usually
509 best to leave them as is, because that way their locations can
510 be looked up from the PATH variable.
511 args_diff (default: -ru)
513 This variable specifies command line arguments to pass to the
514 diff command (as specified by path_diff) when using adiff. Space
515 characters separate arguments in this string.
516 path_syscfg (default: /etc/atool.conf)
518 (This variable can only be set in the atool program file.) This
519 variable specifies the directory where the system-wide configu‐
520 ration file is located.
521 path_usercfg (default: .atoolrc)
523 (This variable can only be set in the atool program file and
524 system-wide configuration file.) This variable specifies where
525 the user configuration file is located. Note that if this file‐
526 name is relative (i.e. doesn't being with `/'), it will be rela‐
527 tive to the current user's home directory (as determined by the
528 HOME environment variable).
529 default_verbosity (default: 1)
531 This is the default verbosity of atool. By using -q and -v
532 options, the verbosity level can be raised and lowered. Level 1
533 means "normal verbosity" - e.g. when creating and extracting
534 from archives, files will be listed.
535 show_extracted (default: 1)
537 If this is set to 1, the aunpack command will always show what
538 file or directory that was extracted. Otherwise that will only
539 be printed if the archive was extracted to an unexpected loca‐
540 tion (as a result of local files already existing or the archive
541 having multiple files in its root directory).
542 This can be quite useful in combinatiaon with `default_verbosity
544 0'. Note that this option will have no effect when the -X
545 option is used with aunpack, and it has no effect on compressed
546 files.
547 keep_compressed (default: 1)
549 When compressing a file with gzip or bzip2, the original (uncom‐
550 pressed) file is usually deleted once it has been compressed.
551 I.e. if you compress a file "test" you will end up with only one
552 file, "test.gz". With this option set to 1, you will make atool
553 keep the original file as well. The original behaviour is
554 achieved by setting this option to 0.
555 This option also has an equivalent effect on uncompressing com‐
557 pressed files. When set to 1, the original (compressed) file
558 will be kept. Otherwise it will be deleted.
559 Note however that this option has no effect when packing up a
561 compressed file with the -X option (for specifying an output
562 directory or file). In that case the original file is always
563 kept.
564 decompress_to_cwd (default: 1)
566 When decompressing a file with commands such as gzip or bzip2,
567 the decompressed file is usually placed in the same directory as
568 the compressed file. With this option set to 1, the decompressed
569 file is instead placed in the current working directory.
570 Note that this option has no effect when -X is used.
572
575 PAGER The default pager to use when the -p/--page option is specified.
576
578 To extract all files from archive `foobar.tar.gz' to a subdirectory (or
579 the current directory if it only contains one file):
580 aunpack foobar.tar.gz
581 To extract all files from all `.tar.gz' archives in the current direc‐
583 tory:
584 aunpack -e *.tar.gz
585 To create a zip archive of two files `foo' and `bar':
587 apack myarchive.zip foo bar
588 To display the file `baz' in the archive `myarchive.zip' through a
590 pager:
591 acat -p myarchive.zip baz
592 To list contents of the rar archive `stuff.rar':
594 als stuff.rar
595 To create three archives, `dir1.tar.gz', `dir2.tar.gz' and
597 `dir3.tar.gz', so that the first one contains all files in dir1, the
598 second all in dir2 and the third all dir3:
599 apack -e -F .tar.gz dir1 dir2 dir3
600 To show all differences between version 2.4.17 and 2.4.18 of the ker‐
602 nel:
603 adiff linux-2.4.17.tar.gz linux-2.4.18.tar.gz
604 To repack all .tar.gz archives in the current directory to .tar.7z (the
606 old archive will be kept untouched):
607 arepack -F.tar.7z -e *.tar.gz
608 Here's a shell function that will make the aunpack command change into
610 the directory where files were extracted:
611 aunpack () {
612 TMP=`mktemp /tmp/aunpack.XXXXXXXXXX`
613 atool -x --save-outdir=$TMP "$@"
614 DIR="`cat $TMP`"
615 [ "$DIR" != "" -a -d "$DIR" ] && cd "$DIR"
616 rm $TMP
617 }
618 If you don't have the mktemp program, you can replace the second line
619 with (note however that this is not entirely safe)
620 TMP="/tmp/atool_outdir.$$"
621
623 Trying to extract gzip and other compressed files without the .gz (or
624 .bz2 etc) extension won't work:
625 aunpack: foo: format not known, identifying using file
627 aunpack: foo: format is `gzip'
628 gzip: foo: unknown suffix -- ignored
629 This last error above is generated by gzip -d foo.
631 If you find a bug not listed here, please report it to
633 <oskar@osk.mine.nu>.
634
636 Report bugs to <oskar@osk.mine.nu>.
637
639 The author of atool and this manual page is Oskar Liljeblad
640 <oskar@osk.mine.nu>.
641
643 Copyright © 2001, 2002, 2003, 2004, 2005, 2007, 2008, 2009 Oskar Lilje‐
644 blad
645 This is free software; see the source for copying conditions. There is
647 NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
648 PURPOSE.
649atool August 8, 2009 ATOOL(1)