1ATOOL(1) General Commands Manual ATOOL(1)
2
3
4
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
23 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
30 apack creates archives (or compresses files). If no file arguments are
31 specified, filenames to add are read from standard in.
32
33 als lists files in an archive.
34
35 acat extracts files in an archive to standard out.
36
37 adiff generates a diff between two archives using diff(1).
38
39 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
46 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
58 -l, --list
59 List files in archive. This option is automaticly assumed when
60 als is executed.
61
62 -x, --extract
63 Extract files from archive. This option is automaticly assumed
64 when aunpack is executed.
65
66 -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
71 -a, --add
72 Create archive. This option is automaticly assumed when apack
73 is executed.
74
75 -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
80 -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
85 -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
91 -F, --format=EXTENSION
92 Specify archive format manually (see ARCHIVE TYPES below).
93
94 -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
100 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
106 -E, --explain
107 Display commands executed by atool. This option can't be com‐
108 bined with --simulate.
109
110 -p, --page
111 Run output through a pager, usually pager unless the environment
112 variable PAGER is set.
113
114 -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
121 -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
126 -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
133 -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
139 -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
145 -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
150 --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
156 -o, --option=KEY=VALUE
157 Override a configuration option. These are applied after reading
158 the configuration files.
159
160 You can specify this multiple times to override different
161 options.
162
163 --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
172 This option is used internally (see EXAMPLES below).
173
174 --help Show summary of options.
175
176 --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
186 The diff command is supported whenever the extract command is sup‐
187 ported.
188
189 The supported archive types are:
190
191 tar+gzip (.tar.gz, .tgz)
192 All commands are supported.
193
194 tar+bzip (.tar.bz, .tbz)
195 All commands are supported.
196
197 tar+bzip2 (.tar.bz2, .tbz2)
198 All commands are supported.
199
200 tar+compress (.tar.Z, .tZ)
201 All commands are supported.
202
203 tar+lzop (.tar.lzo, .tzo)
204 All commands are supported.
205
206 tar+lzip (.tar.lz, .tlz)
207 All commands are supported.
208
209 tar+xz (.tar.xz, .txz)
210 All commands are supported.
211
212 tar+7z (.tar.7z, .t7z)
213 All commands are supported.
214
215 tar (.tar)
216 All commands are supported.
217
218 zip (.zip)
219 All commands are supported.
220
221 jar (.jar, .war)
222 List, extract, and add commands are supported. Cat is supported
223 if use_jar_program is disabled.
224
225 rar (.rar)
226 All commands are supported.
227
228 lha (.lha, .lzh)
229 All commands are supported.
230
231 7z (.7z)
232 Extract, list and add commands are supported.
233
234 alzip (.alz)
235 Extract command is supported.
236
237 ace (.ace)
238 Extract and list commands are supported.
239
240 ar (.a)
241 All commands are supported.
242
243 arj (.arj)
244 List, extract and add commands are supported.
245
246 arc (.arc)
247 All command are supported. (Note that arc outputs an extra new‐
248 line when the cat command is used.)
249
250 rpm (.rpm)
251 Extract and list commands are supported.
252
253 deb (.deb)
254 Extract and list commands are supported.
255
256 cab (.cab)
257 Cat, extract, and list commands are supported.
258
259 gzip (.gz)
260 Cat, extract, and add commands are supported.
261
262 bzip (.bz)
263 Cat, extract, and add commands are supported.
264
265 bzip2 (.bz2)
266 Cat, extract, and add commands are supported.
267
268 compress (.Z)
269 Cat, extract, and add commands are supported.
270
271 lzma (.lzma)
272 Cat, extract, and add commands are supported.
273
274 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
279 lzip (.lz)
280 Cat, extract, and add commands are supported.
281
282 xz (.xz)
283 Cat, extract, and add commands are supported.
284
285 rzip (.rz)
286 Extract and add commands are supported.
287
288 lrzip (.lrz)
289 Extract and add commands are supported.
290
291 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
297 cpio (.cpio)
298 List, extract and add commands are supported.
299
300
301
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
309 The format of the configuration files is simple:
310
311 variable value
312
313 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
318 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
322 The options are:
323
324 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
331 This used to be use_tar_j_option but using --bzip2 is more por‐
332 table.
333
334 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
339 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
343 If possible, these options should be enabled since error manage‐
344 ment is better when filtering is done by tar.
345
346 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
351 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
356 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
361 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
365 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
370 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
375 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
380 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
385 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
391 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
400 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
407 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
412 This option is disabled by default since extracting files to
413 standard out (`cat') is not supported by jar.
414
415 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
420 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
427 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
432 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
436 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
441 path_pager (default: pager)
442
443 path_jar (default: jar)
444
445 path_tar (default: tar)
446
447 path_zip (default: zip)
448
449 path_unzip (default: unzip)
450
451 path_gzip (default: gzip)
452
453 path_bzip (default: bzip)
454
455 path_bzip2 (default: bzip2)
456
457 path_pbzip2 (default: pbzip2)
458
459 path_compress (default: compress)
460
461 path_lzma (default: lzma)
462
463 path_lzop (default: lzop)
464
465 path_lzip (default: lzip)
466
467 path_rar (default: rar)
468
469 path_unrar (default: unrar)
470
471 path_cabextract (default: cabextract)
472
473 path_7z (default: 7z)
474
475 path_unalz (default: unalz)
476
477 path_lha (default: lha)
478
479 path_unace (default: unace)
480
481 path_ar (default: ar)
482
483 path_arj (default: arj)
484
485 path_unarj (default: unarj)
486
487 path_arc (default: arc)
488
489 path_nomarch (default: nomarch)
490
491 path_rpm (default: rpm)
492
493 path_rpm2cpio (default: rpm2cpio)
494
495 path_dpkg_deb (default: dpkg-deb)
496
497 path_cpio (default: cpio)
498
499 path_file (default: file)
500
501 path_find (default: find)
502
503 path_xargs (default: xargs)
504
505 path_cat (default: cat)
506
507 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
512 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
517 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
522 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
530 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
536 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
543 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
548 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
556 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
560 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
565 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
571 Note that this option has no effect when -X is used.
572
573
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
582 To extract all files from all `.tar.gz' archives in the current direc‐
583 tory:
584 aunpack -e *.tar.gz
585
586 To create a zip archive of two files `foo' and `bar':
587 apack myarchive.zip foo bar
588
589 To display the file `baz' in the archive `myarchive.zip' through a
590 pager:
591 acat -p myarchive.zip baz
592
593 To list contents of the rar archive `stuff.rar':
594 als stuff.rar
595
596 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
601 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
605 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
609 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
626 aunpack: foo: format not known, identifying using file
627 aunpack: foo: format is `gzip'
628 gzip: foo: unknown suffix -- ignored
629
630 This last error above is generated by gzip -d foo.
631
632 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
646 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.
649
650
651
652atool August 8, 2009 ATOOL(1)