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 automatically assumed
60 when als is executed.
61 -x, --extract
63 Extract files from archive. This option is automatically
64 assumed 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 automatically 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 automatically 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 automatically assumed when adiff
83 is 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 -O, --format-option=OPTION
165 Send additional options to the archiver command. This can be
166 useful when specifying compression options for some archives,
167 e.g.
168 apack -F7z -O-mx=9 archive.7z dir
169 You can specify this multiple times add different options.
170 --save-outdir=FILE
172 When extracting files, save the name of the directory which the
173 archive was extracted to to the specified file. If the command
174 was not `extract', or the archive was not extracted to a new
175 directory, then nothing will be written to the specified file.
176 If multiple archives were specified (with -e), then only the
177 last directory that files were extracted to will be written to
178 FILE.
179 This option is used internally (see EXAMPLES below).
181 --help Show summary of options.
183 --version
185 Output version information and exit.
186
188 Unless the -f (--format) option is provided, the archive format is
189 determined by the archive file extension. I.e. an extension ".tar.gz"
190 or ".tgz" means tar+gzip format. Note that the extensions are checked
191 in the other listed above, which is why a file with extension ".tar.gz"
192 is considered to a tar+gzip archive, not a gzip archive.
193 The diff command is supported whenever the extract command is sup‐
195 ported.
196 The supported archive types are:
198 tar+gzip (.tar.gz, .tgz)
200 All commands are supported.
201 tar+bzip (.tar.bz, .tbz)
203 All commands are supported.
204 tar+bzip2 (.tar.bz2, .tbz2)
206 All commands are supported.
207 tar+compress (.tar.Z, .tZ)
209 All commands are supported.
210 tar+lzop (.tar.lzo, .tzo)
212 All commands are supported.
213 tar+lzip (.tar.lz, .tlz)
215 All commands are supported.
216 tar+xz (.tar.xz, .txz)
218 All commands are supported.
219 tar+7z (.tar.7z, .t7z)
221 All commands are supported.
222 tar (.tar)
224 All commands are supported.
225 zip (.zip)
227 All commands are supported.
228 jar (.jar, .war)
230 List, extract, and add commands are supported. Cat is supported
231 if use_jar_program is disabled.
232 rar (.rar)
234 All commands are supported.
235 lha (.lha, .lzh)
237 All commands are supported.
238 7z (.7z)
240 Extract, list and add commands are supported.
241 alzip (.alz)
243 Extract command is supported.
244 ace (.ace)
246 Extract and list commands are supported.
247 ar (.a)
249 All commands are supported.
250 arj (.arj)
252 List, extract and add commands are supported.
253 arc (.arc)
255 All command are supported. (Note that arc outputs an extra new‐
256 line when the cat command is used.)
257 rpm (.rpm)
259 Extract and list commands are supported.
260 deb (.deb)
262 Extract and list commands are supported.
263 cab (.cab)
265 Cat, extract, and list commands are supported.
266 gzip (.gz)
268 Cat, extract, and add commands are supported.
269 bzip (.bz)
271 Cat, extract, and add commands are supported.
272 bzip2 (.bz2)
274 Cat, extract, and add commands are supported.
275 compress (.Z)
277 Cat, extract, and add commands are supported.
278 lzma (.lzma)
280 Cat, extract, and add commands are supported.
281 lzop (.lzo)
283 Extract and add commands are supported. The cat command is not
284 supported because lzop does not want to extract files to stan‐
285 dard out unless the -f flag is given.
286 lzip (.lz)
288 Cat, extract, and add commands are supported.
289 xz (.xz)
291 Cat, extract, and add commands are supported.
292 rzip (.rz)
294 Extract and add commands are supported.
295 lrzip (.lrz)
297 Extract and add commands are supported.
298 7zip (.7z)
300 All commands are supported. (Note that 7z refuses to write
301 extracted files to standard out if standard out is a terminal.
302 Use -p or pipe the output of atool/acat to a pager when reading
303 in a terminal.)
304 cpio (.cpio)
306 List, extract and add commands are supported.
307
311 Since version 0.8.0, atool can read custom configuration files. First,
312 hardcoded defaults in the atool program file are evaluated. Then sys‐
313 tem-wide configuration values are loaded from /etc/atool.conf if that
314 file exists. Finally, per-user configuration values are loaded from
315 .atoolrc in the current user's home directory.
316 The format of the configuration files is simple:
318 variable value
320 Here variable is a variable listed below, and value is the value to as‐
322 sociate the variable with. variable and value should be separated with
323 at least one whitespace (space, tab etc). Empty lines and lines begin‐
324 ning with # are discarded.
325 A value of `1' means that the option is enabled, and `0' that it is
327 disabled. Strings should not be quoted, as they start at the first non-
328 whitespace character and end at the end of the line.
329 The options are:
331 use_tar_bzip2_option (default: 1)
333 Enable this if you use GNU tar and it supports the --bzip2
334 option for filtering bzip2'ed files through bzip2. Versions
335 1.13.6 or later of GNU tar support --bzip2. Therefore, if you
336 use GNU tar earlier than 1.13.6, you will need to disable this
337 option.
338 This used to be use_tar_j_option but using --bzip2 is more por‐
340 table.
341 use_tar_lzip_option (default: 0)
343 Enable this if you use GNU tar and it supports the --lzip option
344 for filtering lzip'ed files through lzip. Versions 1.23 or later
345 of GNU tar support --lzip. Therefore, if you use GNU tar earlier
346 than 1.23, you will need to disable this option.
347 use_tar_z_option (default: 1)
349 Enable this if you use GNU tar and it supports the -z option for
350 filtering gzipped files through gzip. You will need to disable
351 this and use_tar_j_option if you don't use GNU tar.
352 Disabling these two options doesn't mean that atool can't
354 extract bzip2/gzip files. If disabled, atool use a pipe to send
355 output from bzip2/gzip to tar instead.
356 If possible, these options should be enabled since error manage‐
358 ment is better when filtering is done by tar.
359 use_tar_lzma_option (default: 1)
361 Enable this if you use GNU tar and it supports the --lzma option
362 for filtering lzma compressed files through lzma. Versions 1.20
363 or later of GNU tar support --lzma.
364 use_tar_lzop_option (default: 0)
366 Enable this if you use GNU tar and it supports the --lzop option
367 for filtering lzop compressed files through lzop. Versions 1.21
368 or later of GNU tar support --lzop.
369 use_tar_xz_option (default: 0)
371 Enable this if you use GNU tar and it supports the --xz option
372 for filtering xz compressed files through xz. Versions 1.22 or
373 later of GNU tar support --xz.
374 use_gzip_for_z (default: 1)
376 Enable this if you want to use gzip instead of uncompress when
377 decompressing compress'ed files (`.Z' files).
378 use_rar_for_unpack (default: 0)
380 Enable this if you want to always use rar instead of unrar when
381 possible. This makes atool use the rar command (path_rar) even
382 when listing and extracting RAR files.
383 use_arc_for_unpack (default: 0)
385 Enable this if you want to always use arc instead of nomarch
386 when possible. This makes atool use the arc command (path_arc)
387 even when listing and extracting ARC files.
388 use_arj_for_unpack (default: 0)
390 Enable this if you want to always use arj instead of unarj when
391 possible. This makes atool use the arj command (path_arj) even
392 when listing and extracting ARJ files.
393 use_find_cpio_print0 (default: 1)
395 Enable this if find supports the -print0 option and cpio sup‐
396 ports the -0 option. Without it, it is impossible/harder to make
397 cpio archives of files with newline characters in their names.
398 extract_deb_control (default: 1)
400 Debian .deb package files contain control information in a
401 DEBIAN directory, especially the package's "control" file.
402 Enable this if you want the control information to be exctracted
403 during extraction in addition to the normal files.
404 strip_unknown_ext (default: 1)
406 Certain types of files are actually archives, but their exten‐
407 sions doesn't tell so. Examples are Open Office documents (Zip
408 files) and Gnumeric documents (gzip'ed files). Since the exten‐
409 sions of those filenames are unknown to atool, they would not be
410 stripped with this option set to 0. The output file in that case
411 would be something like Unpack-XYZW. Setting this option to 1
412 will cause the extension to be stripped instead.
413 use_pbzip2 (default: 0)
415 Enable this if you want to use pbzip2 rather than bzip2. Please
416 not that if use_tar_bzip2_option is enabled, then bzip2 will be
417 used by tar regardless of the use_pbzip2 option. So if you want
418 tar to use pbzip2 rather than bzip2, set use_pbzip2 to 1 and
419 use_tar_bzip2_option to 0.
420 use_lbzip2 (default: 0)
422 Enable this if you want to use lbzip2 rather than bzip2. Please
423 not that if use_tar_bzip2_option is enabled, then bzip2 will be
424 used by tar regardless of the use_lbzip2 option. So if you want
425 tar to use lbzip2 rather than bzip2, set use_lbzip2 to 1 and
426 use_tar_bzip2_option to 0.
427 use_pigz (default: 0)
429 Enable this if you want to use pigz rather than gzip. Please
430 not that if use_tar_z_option is enabled, then gzip will be used
431 by tar regardless of the use_pigz option. So if you want tar to
432 use pigz rather than gzip, set use_pigz to 1 and
433 use_tar_z_option to 0.
434 use_plzip (default: 0)
436 Enable this if you want to use plzip rather than lzip. Please
437 not that if use_tar_lzip_option is enabled, then lzip will be
438 used by tar regardless of the use_plzip option. So if you want
439 tar to use plzip rather than lzip, set use_plzip to 1 and
440 use_tar_lzip_option to 0.
441 use_jar (default: 0)
443 Enable this if you want to use jar for managing jar archives. If
444 you disable this option, zip will be used (which should work
445 just as well, and probably be faster too).
446 This option is disabled by default since extracting files to
448 standard out (`cat') is not supported by jar.
449 use_file (default: 1)
451 Enable this if you want atool to identify file types using
452 file(1) for those files with an unrecognized extension (or none
453 at all).
454 use_file_always (default: 0)
456 Enable this if you want atool to always identify archives using
457 file(1), regardless of the file extension. Please note that this
458 currently has some drawbacks, such as not being able to identify
459 all archive types (especially tar archives compressed with 7zip,
460 lzop, szip etc).
461 tmpdir_name (default: Unpack-%04d)
463 atool extracts to a temporary directory created in the current
464 directory so that no files are overwritten. This variable con‐
465 trolls what name that temporary directory should have.
466 The `%d' string in this variable will be replaced with a random
468 number between 0 and 9999. It is possible change the format of
469 this number by using something else than `%d' - see printf(3).
470 tmpfile_name (default: Pack-%04d)
472 When using pbzip2, and creating archives, a temporary file need
473 to be created. This option controls the name of that file. See
474 tmpdir_name for further details on the format.
475 path_pager (default: pager)
477 path_jar (default: jar)
479 path_tar (default: tar)
481 path_zip (default: zip)
483 path_unzip (default: unzip)
485 path_gzip (default: gzip)
487 path_bzip (default: bzip)
489 path_bzip2 (default: bzip2)
491 path_pbzip2 (default: pbzip2)
493 path_compress (default: compress)
495 path_lzma (default: lzma)
497 path_lzop (default: lzop)
499 path_lzip (default: lzip)
501 path_rar (default: rar)
503 path_unrar (default: unrar)
505 path_lbzip2 (default: lbzip2)
507 path_pigz (default: pigz)
509 path_cabextract (default: cabextract)
511 path_7z (default: 7z)
513 path_unalz (default: unalz)
515 path_lha (default: lha)
517 path_unace (default: unace)
519 path_ar (default: ar)
521 path_arj (default: arj)
523 path_unarj (default: unarj)
525 path_arc (default: arc)
527 path_nomarch (default: nomarch)
529 path_rpm (default: rpm)
531 path_rpm2cpio (default: rpm2cpio)
533 path_dpkg_deb (default: dpkg-deb)
535 path_cpio (default: cpio)
537 path_file (default: file)
539 path_find (default: find)
541 path_xargs (default: xargs)
543 path_cat (default: cat)
545 path_diff (default: diff)
547 These are all paths to the corresponding programs. It is usually
548 best to leave them as is, because that way their locations can
549 be looked up from the PATH variable.
550 args_diff (default: -ru)
552 This variable specifies command line arguments to pass to the
553 diff command (as specified by path_diff) when using adiff. Space
554 characters separate arguments in this string.
555 path_syscfg (default: /etc/atool.conf)
557 (This variable can only be set in the atool program file.) This
558 variable specifies the directory where the system-wide configu‐
559 ration file is located.
560 path_usercfg (default: .atoolrc)
562 (This variable can only be set in the atool program file and
563 system-wide configuration file.) This variable specifies where
564 the user configuration file is located. Note that if this file‐
565 name is relative (i.e. doesn't being with `/'), it will be rela‐
566 tive to the current user's home directory (as determined by the
567 HOME environment variable).
568 default_verbosity (default: 1)
570 This is the default verbosity of atool. By using -q and -v
571 options, the verbosity level can be raised and lowered. Level 1
572 means "normal verbosity" - e.g. when creating and extracting
573 from archives, files will be listed.
574 show_extracted (default: 1)
576 If this is set to 1, the aunpack command will always show what
577 file or directory that was extracted. Otherwise that will only
578 be printed if the archive was extracted to an unexpected loca‐
579 tion (as a result of local files already existing or the archive
580 having multiple files in its root directory).
581 This can be quite useful in combinatiaon with `default_verbosity
583 0'. Note that this option will have no effect when the -X
584 option is used with aunpack, and it has no effect on compressed
585 files.
586 keep_compressed (default: 1)
588 When compressing a file with gzip or bzip2, the original (uncom‐
589 pressed) file is usually deleted once it has been compressed.
590 I.e. if you compress a file "test" you will end up with only one
591 file, "test.gz". With this option set to 1, you will make atool
592 keep the original file as well. The original behaviour is
593 achieved by setting this option to 0.
594 This option also has an equivalent effect on uncompressing com‐
596 pressed files. When set to 1, the original (compressed) file
597 will be kept. Otherwise it will be deleted.
598 Note however that this option has no effect when packing up a
600 compressed file with the -X option (for specifying an output
601 directory or file). In that case the original file is always
602 kept.
603 decompress_to_cwd (default: 1)
605 When decompressing a file with commands such as gzip or bzip2,
606 the decompressed file is usually placed in the same directory as
607 the compressed file. With this option set to 1, the decompressed
608 file is instead placed in the current working directory.
609 Note that this option has no effect when -X is used.
611
614 PAGER The default pager to use when the -p/--page option is specified.
615
617 To extract all files from archive `foobar.tar.gz' to a subdirectory (or
618 the current directory if it only contains one file):
619 aunpack foobar.tar.gz
620 To extract all files from all `.tar.gz' archives in the current direc‐
622 tory:
623 aunpack -e *.tar.gz
624 To create a zip archive of two files `foo' and `bar':
626 apack myarchive.zip foo bar
627 To display the file `baz' in the archive `myarchive.zip' through a
629 pager:
630 acat -p myarchive.zip baz
631 To list contents of the rar archive `stuff.rar':
633 als stuff.rar
634 To create three archives, `dir1.tar.gz', `dir2.tar.gz' and
636 `dir3.tar.gz', so that the first one contains all files in dir1, the
637 second all in dir2 and the third all dir3:
638 apack -e -F .tar.gz dir1 dir2 dir3
639 To show all differences between version 2.4.17 and 2.4.18 of the ker‐
641 nel:
642 adiff linux-2.4.17.tar.gz linux-2.4.18.tar.gz
643 To repack all .tar.gz archives in the current directory to .tar.7z (the
645 old archive will be kept untouched):
646 arepack -F.tar.7z -e *.tar.gz
647 Here's a shell function that will make the aunpack command change into
649 the directory where files were extracted:
650 aunpack () {
651 TMP=`mktemp /tmp/aunpack.XXXXXXXXXX`
652 atool -x --save-outdir=$TMP "$@"
653 DIR="`cat $TMP`"
654 [ "$DIR" != "" -a -d "$DIR" ] && cd "$DIR"
655 rm $TMP
656 }
657 If you don't have the mktemp program, you can replace the second line
658 with (note however that this is not entirely safe)
659 TMP="/tmp/atool_outdir.$$"
660
662 Trying to extract gzip and other compressed files without the .gz (or
663 .bz2 etc) extension won't work:
664 aunpack: foo: format not known, identifying using file
666 aunpack: foo: format is `gzip'
667 gzip: foo: unknown suffix -- ignored
668 This last error above is generated by gzip -d foo.
670 If you find a bug not listed here, please report it to
672 <oskar@osk.mine.nu>.
673
675 Report bugs to <oskar@osk.mine.nu>.
676
678 The author of atool and this manual page is Oskar Liljeblad
679 <oskar@osk.mine.nu>.
680
682 Copyright © 2001, 2002, 2003, 2004, 2005, 2007, 2008, 2009, 2011, 2012
683 Oskar Liljeblad
684 This is free software; see the source for copying conditions. There is
686 NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
687 PURPOSE.
688atool August 8, 2009 ATOOL(1)