1ATOOL(1)                    General Commands Manual                   ATOOL(1)
2
3
4

NAME

6       atool - A script for managing file archives of various types
7

SYNOPSIS

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

DESCRIPTION

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

OPTIONS

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  automatically  assumed
60              when als is executed.
61
62       -x, --extract
63              Extract  files  from  archive.   This  option  is  automatically
64              assumed 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 automatically 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 automatically 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 automatically assumed  when  adiff
83              is 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
164       -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
171       --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
180              This option is used internally (see EXAMPLES below).
181
182       --help Show summary of options.
183
184       --version
185              Output version information and exit.
186

ARCHIVE TYPES

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
194       The diff command is supported whenever  the  extract  command  is  sup‐
195       ported.
196
197       The supported archive types are:
198
199       tar+gzip (.tar.gz, .tgz)
200              All commands are supported.
201
202       tar+bzip (.tar.bz, .tbz)
203              All commands are supported.
204
205       tar+bzip2 (.tar.bz2, .tbz2)
206              All commands are supported.
207
208       tar+compress (.tar.Z, .tZ)
209              All commands are supported.
210
211       tar+lzop (.tar.lzo, .tzo)
212              All commands are supported.
213
214       tar+lzip (.tar.lz, .tlz)
215              All commands are supported.
216
217       tar+xz (.tar.xz, .txz)
218              All commands are supported.
219
220       tar+7z (.tar.7z, .t7z)
221              All commands are supported.
222
223       tar (.tar)
224              All commands are supported.
225
226       zip (.zip)
227              All commands are supported.
228
229       jar (.jar, .war)
230              List, extract, and add commands are supported.  Cat is supported
231              if use_jar_program is disabled.
232
233       rar (.rar)
234              All commands are supported.
235
236       lha (.lha, .lzh)
237              All commands are supported.
238
239       7z (.7z)
240              Extract, list and add commands are supported.
241
242       alzip (.alz)
243              Extract command is supported.
244
245       ace (.ace)
246              Extract and list commands are supported.
247
248       ar (.a)
249              All commands are supported.
250
251       arj (.arj)
252              List, extract and add commands are supported.
253
254       arc (.arc)
255              All command are supported.  (Note that arc outputs an extra new‐
256              line when the cat command is used.)
257
258       rpm (.rpm)
259              Extract and list commands are supported.
260
261       deb (.deb)
262              Extract and list commands are supported.
263
264       cab (.cab)
265              Cat, extract, and list commands are supported.
266
267       gzip (.gz)
268              Cat, extract, and add commands are supported.
269
270       bzip (.bz)
271              Cat, extract, and add commands are supported.
272
273       bzip2 (.bz2)
274              Cat, extract, and add commands are supported.
275
276       compress (.Z)
277              Cat, extract, and add commands are supported.
278
279       lzma (.lzma)
280              Cat, extract, and add commands are supported.
281
282       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
287       lzip (.lz)
288              Cat, extract, and add commands are supported.
289
290       xz (.xz)
291              Cat, extract, and add commands are supported.
292
293       rzip (.rz)
294              Extract and add commands are supported.
295
296       lrzip (.lrz)
297              Extract and add commands are supported.
298
299       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
305       cpio (.cpio)
306              List, extract and add commands are supported.
307
308
309

CONFIGURATION

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
317       The format of the configuration files is simple:
318
319              variable value
320
321       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
326       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
330       The options are:
331
332       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
339              This  used to be use_tar_j_option but using --bzip2 is more por‐
340              table.
341
342       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
348       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
353              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
357              If possible, these options should be enabled since error manage‐
358              ment is better when filtering is done by tar.
359
360       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
365       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
370       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
375       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
379       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
384       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
389       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
394       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
399       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
405       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
414       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
421       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
428       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
435       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
442       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
447              This option is disabled by default  since  extracting  files  to
448              standard out (`cat') is not supported by jar.
449
450       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
455       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
462       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
467              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
471       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
476       path_pager (default: pager)
477
478       path_jar (default: jar)
479
480       path_tar (default: tar)
481
482       path_zip (default: zip)
483
484       path_unzip (default: unzip)
485
486       path_gzip (default: gzip)
487
488       path_bzip (default: bzip)
489
490       path_bzip2 (default: bzip2)
491
492       path_pbzip2 (default: pbzip2)
493
494       path_compress (default: compress)
495
496       path_lzma (default: lzma)
497
498       path_lzop (default: lzop)
499
500       path_lzip (default: lzip)
501
502       path_rar (default: rar)
503
504       path_unrar (default: unrar)
505
506       path_lbzip2 (default: lbzip2)
507
508       path_pigz (default: pigz)
509
510       path_cabextract (default: cabextract)
511
512       path_7z (default: 7z)
513
514       path_unalz (default: unalz)
515
516       path_lha (default: lha)
517
518       path_unace (default: unace)
519
520       path_ar (default: ar)
521
522       path_arj (default: arj)
523
524       path_unarj (default: unarj)
525
526       path_arc (default: arc)
527
528       path_nomarch (default: nomarch)
529
530       path_rpm (default: rpm)
531
532       path_rpm2cpio (default: rpm2cpio)
533
534       path_dpkg_deb (default: dpkg-deb)
535
536       path_cpio (default: cpio)
537
538       path_file (default: file)
539
540       path_find (default: find)
541
542       path_xargs (default: xargs)
543
544       path_cat (default: cat)
545
546       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
551       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
556       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
561       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
569       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
575       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
582              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
587       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
595              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
599              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
604       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
610              Note that this option has no effect when -X is used.
611
612

ENVIRONMENT VARIABLES

614       PAGER The default pager to use when the -p/--page option is specified.
615

EXAMPLES

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
621       To extract all files from all `.tar.gz' archives in the current  direc‐
622       tory:
623            aunpack -e *.tar.gz
624
625       To create a zip archive of two files `foo' and `bar':
626            apack myarchive.zip foo bar
627
628       To  display  the  file  `baz'  in the archive `myarchive.zip' through a
629       pager:
630            acat -p myarchive.zip baz
631
632       To list contents of the rar archive `stuff.rar':
633            als stuff.rar
634
635       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
640       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
644       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
648       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

KNOWN BUGS

662       Trying to extract gzip and other compressed files without the  .gz  (or
663       .bz2 etc) extension won't work:
664
665         aunpack: foo: format not known, identifying using file
666         aunpack: foo: format is `gzip'
667         gzip: foo: unknown suffix -- ignored
668
669       This last error above is generated by gzip -d foo.
670
671       If   you   find   a   bug   not   listed  here,  please  report  it  to
672       <oskar@osk.mine.nu>.
673

REPORTING BUGS

675       Report bugs to <oskar@osk.mine.nu>.
676

AUTHOR

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
685       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.
688
689
690
691atool                           August 8, 2009                        ATOOL(1)
Impressum