« back to all changes in this revision
Viewing changes to atool.1.in
- browse files at revision 3
- compare with another revision
- download diff
- download tarball
- view history from revision 3
- Committer: Bazaar Package Importer
- Author(s): Stephane Jourdois
- Date: 2004-10-03 14:38:13 UTC
- mfrom: (1.1.1 upstream)
- Revision ID: james.westby@ubuntu.com-20041003143813-p4iwzd0lrc6twk0l
Tags: 0.29.0-2
* Use rar as unpacker for rar archives by default (Closes: #273009).
* Remove Suggests: unrar, as atool supports unrar-nonfree and rar, but
not unrar.
* Remove Suggests: unrar, as atool supports unrar-nonfree and rar, but
not unrar.
- files added:
- Makefile.in
- debian/patches
- files removed:
- Makefile
- acat
- als
- apack
- aunpack
- files modified:
- ChangeLog
added
removed
atool.1.in
1
.TH atool 1 "July 1, 2004"
2
.\" Read this file with groff -man -Tascii atool.1
3
.SH NAME
4
atool \- A script for managing file archives of various types
5
.SH SYNOPSIS
6
.B atool
7
.RI [ OPTION ]... " ARCHIVE " [ FILE ]...
8
.br
9
.B aunpack
10
.RI [ OPTION ]... " ARCHIVE " [ FILE ]...
11
.br
12
.B apack
13
.RI [ OPTION ]... " ARCHIVE " [ FILE ]...
14
.br
15
.B als
16
.RI [ OPTION ]... " ARCHIVE " [ FILE ]...
17
.br
18
.B acat
19
.RI [ OPTION ]... " ARCHIVE " [ FILE ]...
20
.br
21
.B adiff
22
.RI [ OPTION ]... " ARCHIVE " "" ARCHIVE
23
.SH DESCRIPTION
24
This manual page document describes the \fBatool\fP commands.
25
These commands are used for managing file archives of various
26
types, such as tar and Zip archives. Each command can be
27
executed individually or by giving the appropriate options
28
to \fBatool\fP (see \fBOPTIONS\fP below).
29
.PP
30
\fBaunpack\fP extracts files from an archive. Often one wants
31
to extract all files in an archive to a single subdirectory.
32
However, some archives contain multiple files in their root
33
directories. The aunpack program overcomes this problem by
34
first extracting files to a unique (temporary) directory, and
35
then moving its contents back if possible. This also prevents
36
local files from being overwritten by mistake.
37
.PP
38
\fBapack\fP creates archives (or compresses files). If no file
39
arguments are specified, filenames to add are read from standard in.
40
.PP
41
\fBals\fP lists files in an archive.
42
.PP
43
\fBacat\fP extracts files in an archive to standard out.
44
.PP
45
\fBadiff\fP generates a diff between two archives using
46
diff(1).
47
.PP
48
Unless the \fB\-\-format\fP (\fB\-f\fP) option is provided,
49
the archive format is determined by the archive file extension. I.e.
50
an extension ".tar.gz" or ".tgz" means tar+gzip format. Note that
51
the extensions are checked in the order listed in the section
52
\fBARCHIVE TYPES\fP below, which is why a file with extension ".tar.gz"
53
is considered to a be tar+gzip archive, not a gzip compressed file.
54
.SH OPTIONS
55
These programs follow the usual GNU command line syntax, with long
56
options starting with two dashes (`-').
57
A summary of options is included below.
58
.TP
59
.B \-l, \-\-list
60
List files in archive.
61
This option is automaticly assumed when \fBals\fP is executed.
62
.TP
63
.B \-x, \-\-extract
64
Extract files from archive.
65
This option is automaticly assumed when \fBaunpack\fP is executed.
66
.TP
67
.B \-X, \-\-extract-to\fR=\fIPATH\fR
68
Extract files from archive to the specified directory. When
69
unpacking compressed files, PATH may refer to either a filename
70
or an existing directory.
71
.TP
72
.B \-a, \-\-add
73
Create archive.
74
This option is automaticly assumed when \fBapack\fP is executed.
75
.TP
76
.B \-c, \-\-cat
77
Extract a file from archive to standard out (displaying it on
78
screen).
79
This option is automaticly assumed when \fBacat\fP is executed.
80
.TP
81
.B \-d, \-\-diff
82
Extract two archives and use diff(1) to generate differencies
83
between them.
84
This option is automaticly assumed when \fBadiff\fP is executed.
85
.TP
86
.B \-e, \-\-each
87
For each argument, execute the specified command. This can be used
88
to quickly extract, list or create multiple archives (see \fBEXAMPLES\fR
89
below). This option can not be used with the cat command.
90
.TP
91
.B \-F, \-\-format\fR=\fIEXTENSION\fR
92
Specify archive format manually (see \fBARCHIVE TYPES\fR below).
93
.TP
94
.B \-S, \-\-simulate
95
Run atool in simulation mode. No changes to the filesystem
96
(i.e. writes) will be made, and all commands that would be
97
executed are displayed instead. This option can't be combined
98
with \fB\-\-explain\fP (since it implies that already).
99
100
Note that it is not guaranteed that the commands printed in
101
simulation mode will be the same as those executed in non-
102
simulation mode. This is because some operations depend on
103
what files archives contain, and atool can at this time
104
only determine that by extracting archives.
105
.TP
106
.B \-E, \-\-explain
107
Display commands executed by atool. This option can't be combined
108
with \fB\-\-simulate\fP.
109
.TP
110
.B \-p, \-\-page
111
Run output through a pager, usually \fBpager\fP unless the environment
112
variable \fBPAGER\fP is set.
113
.TP
114
.B \-f, \-\-force
115
When extracting from files, allow overwriting of local files.
116
When creating an archive, allow the archive file to be overwritten
117
if it already exists. Note that it is possible to add files to
118
existing RAR and Zip archives (this is not possible for many
119
other formats).
120
.TP
121
.B \-D, \-\-subdir
122
When extracting archives, always create a new directory for
123
the archive even if the archive only contains one file in
124
its root directory.
125
.TP
126
.B \-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
.TP
133
.B \-q, \-\-quiet
134
Decrease verbosity level by one. This is subtracted from the
135
default verbosity level, or the level specified
136
with \fB\-\-verbosity\fP. This option may be specified more than
137
once to make atool even less verbose.
138
.TP
139
.B \-v, \-\-verbose
140
Increase verbosity level by one. This is added to the
141
default verbosity level, or the level specified
142
with \fB\-\-verbosity\fP. This option may be specified more than
143
once to make atool even more verbose.
144
.TP
145
.B \-V, \-\-verbosity\fR=\fILEVEL\fR
146
Specify verbosity level. The default level is 1,
147
which means "normal verbosity" - e.g. when creating and
148
extracting from archives, files will be listed.
149
.TP
150
.B \-\-config\fR=\fIFILE\fR
151
Load configuration from the specified file. When using this
152
option, the system-wide and user-wide configuration files
153
will not be loaded. If the specified file does not exist or
154
can not be read, atool will terminate with an error message.
155
.TP
156
.B \-\-save\-outdir\fR=\fIFILE\fR
157
When extracting files, save the name of the directory which
158
the archive was extracted to to the specified file. If the
159
command was not `extract', or the archive was not extracted to
160
a new directory, then nothing will be written to the specified
161
file. If multiple archives were specified (with -e), then
162
only the last directory that files were extracted to will be
163
written to FILE.
164
165
This option is used internally (see \fBEXAMPLES\fR below).
166
.TP
167
.B \-\-help
168
Show summary of options.
169
.TP
170
.B \-\-version
171
Output version information and exit.
172
.SH ARCHIVE TYPES
173
Unless the \-f (\-\-format) option is provided, the archive format
174
is determined by the archive file extension. I.e. an extension
175
".tar.gz" or ".tgz" means tar+gzip format. Note that the extensions
176
are checked in the other listed above, which is why a file
177
with extension ".tar.gz" is considered to a tar+gzip archive,
178
not a gzip archive.
179
.PP
180
The diff command is supported whenever the extract command is
181
supported.
182
.PP
183
The supported archive types are:
184
.TP
185
.RI \fBtar+gzip\fP " " ( .tar.gz ", " .tgz )
186
All commands are supported.
187
.TP
188
.RI \fBtar+bzip\fP " " ( .tar.bz ", " .tbz )
189
All commands are supported.
190
.TP
191
.RI \fBtar+bzip2\fP " " ( .tar.bz2 ", " .tbz2 )
192
All commands are supported.
193
.TP
194
.RI \fBtar+compress\fP " " ( .tar.Z ", " .tZ )
195
All commands are supported.
196
.TP
197
.RI \fBtar\fP " " ( .tar )
198
All commands are supported.
199
.TP
200
.RI \fBzip\fP " " ( .zip )
201
All commands are supported.
202
.TP
203
.RI \fBjar\fP " " ( .jar ", " .war )
204
List, extract, and add commands are supported.
205
Cat is supported if use_jar_program is disabled.
206
.TP
207
.RI \fBrar\fP " " ( .rar )
208
All commands are supported.
209
.TP
210
.RI \fBlha\fP " " ( .lha ", " .lzh )
211
All commands are supported.
212
.TP
213
.RI \fBace\fP " " ( .ace )
214
Extract and list commands are supported.
215
.TP
216
.RI \fBar\fP " " ( .a )
217
All commands are supported.
218
.TP
219
.RI \fBarj\fP " " ( .arj )
220
List, extract and add commands are supported.
221
.TP
222
.RI \fBarc\fP " " ( .arc )
223
All command are supported.
224
(Note that arc outputs an extra newline when the cat command is used.)
225
.TP
226
.RI \fBrpm\fP " " ( .rpm )
227
Extract and list commands are supported.
228
.TP
229
.RI \fBgzip\fP " " ( .gz )
230
Cat, extract, and add commands are supported.
231
.TP
232
.RI \fBbzip\fP " " ( .bz )
233
Cat, extract, and add commands are supported.
234
.TP
235
.RI \fBbzip2\fP " " ( .bz2 )
236
Cat, extract, and add commands are supported.
237
.TP
238
.RI \fBcompress\fP " " ( .Z )
239
Cat, extract, and add commands are supported.
240
.SH CONFIGURATION
241
Since version 0.8.0, atool can read custom configuration files.
242
First, hardcoded defaults in the atool program file are evaluated.
243
Then system-wide configuration values are loaded from
244
\fI/etc/atool.conf\fR if that file exists. Finally, per-user
245
configuration values are loaded from \fI.atoolrc\fR in the current
246
user's home directory.
247
.PP
248
The format of the configuration files is simple:
249
.IP
250
variable value
251
.PP
252
Here \fBvariable\fR is a variable listed below, and \fBvalue\fR is the
253
value to associate the variable with. \fBvariable\fR and \fBvalue\fR
254
should be separated with at least one whitespace (space, tab etc). Empty
255
lines and lines beginning with # are discarded.
256
.PP
257
A value of `1' means that the option is enabled, and `0'
258
that it is disabled. Strings should not be quoted, as they start at
259
the first non-whitespace character and end at the end of the line.
260
.PP
261
The options are:
262
.TP
263
.B use_tar_bzip2_option \fR(default: 1)\fR
264
Enable this if you use GNU tar and it supports the \fB\--bzip2\fP option
265
for filtering bzip2'ed files through bzip2. Versions 1.13.6
266
or later of GNU tar support \fB\--bzip2\fP. Therefore, if you use
267
GNU tar earlier than 1.13.6, you will need to disable this option.
268
269
This used to be \fBuse_tar_j_option\fP but using --bzip2 is more portable.
270
.TP
271
.B use_tar_z_option \fR(default: 1)\fR
272
Enable this if you use GNU tar and it supports the \fB-z\fP option
273
for filtering gzipped files through gzip. You will need to disable
274
this and \fIuse_tar_j_option\fR if you don't use GNU tar.
275
276
Disabling these two options doesn't mean that atool can't
277
extract bzip2/gzip files. If disabled, atool use a pipe to
278
send output from bzip2/gzip to tar instead.
279
280
If possible, these options should be enabled since error
281
management is better when filtering is done by tar.
282
.TP
283
.B use_gzip_for_z \fR(default: 1)\fR
284
Enable this if you want to use gzip instead of uncompress when
285
decompressing compress'ed files (`.Z' files).
286
.TP
287
.B use_rar_for_unpack \fR(default: 0)\fR
288
Enable this if you want to always use rar instead of unrar
289
when possible. This makes atool use the rar command
290
(path_rar) even when listing and extracting RAR files.
291
.TP
292
.B use_arc_for_unpack \fR(default: 0)\fR
293
Enable this if you want to always use arc instead of nomarch
294
when possible. This makes atool use the arc command
295
(path_arc) even when listing and extracting ARC files.
296
.TP
297
.B use_arj_for_unpack \fR(default: 0)\fR
298
Enable this if you want to always use arj instead of unarj
299
when possible. This makes atool use the arj command
300
(path_arj) even when listing and extracting ARJ files.
301
.TP
302
.B use_find_cpio_print0 \fR(default: 1)\fR
303
Enable this if find supports the -print0 option and cpio supports
304
the -0 option. Without it, it is impossible/harder to make cpio
305
archives of files with newline characters in their names.
306
.TP
307
.B strip_unknown_ext \fR(default: 1)\fR
308
Certain types of files are actually archives, but their extensions
309
doesn't tell so. Examples are Open Office documents (Zip files) and
310
Gnumeric documents (gzip'ed files). Since the extensions of those
311
filenames are unknown to atool, they would not be stripped with
312
this option set to 0. The output file in that case would be something
313
like Unpack-XYZW. Setting this option to 1 will cause the extension
314
to be stripped instead.
315
.TP
316
.B use_jar \fR(default: 0)\fR
317
Enable this if you want to use jar for managing jar
318
archives. If you disable this option, zip will be
319
used (which should work just as well, and probably be
320
faster too).
321
322
This option is disabled by default since extracting
323
files to standard out (`cat') is not supported by jar.
324
.TP
325
.B use_file \fR(default: 1)\fR
326
Enable this if you want atool to identify file types
327
using file(1) for those files with an unrecognized
328
extension (or none at all).
329
330
Note that tar-archives compressed with a file compressor
331
(such as gzip, bzip2 and so on) can't be identified this way.
332
For this reason, files packed with gzip and other file
333
compressors are not identified either.
334
.TP
335
.B tmpdir_name \fR(default: Unpack-%04d)\fR
336
atool extracts to a temporary directory created in the current
337
directory so that no files are overwritten. This variable
338
controlls what name that temporary directory should have.
339
340
The `%d' string in this variable will be replaced with a random
341
number between 0 and 9999. It is possible change the format
342
of this number by using something else than `%d' - see printf(3).
343
.TP
344
.B path_pager \fR(default: pager)\fR
345
.TP
346
.B path_jar \fR(default: jar)\fR
347
.TP
348
.B path_tar \fR(default: tar)\fR
349
.TP
350
.B path_zip \fR(default: zip)\fR
351
.TP
352
.B path_unzip \fR(default: unzip)\fR
353
.TP
354
.B path_gzip \fR(default: gzip)\fR
355
.TP
356
.B path_bzip \fR(default: bzip)\fR
357
.TP
358
.B path_bzip2 \fR(default: bzip2)\fR
359
.TP
360
.B path_compress \fR(default: compress)\fR
361
.TP
362
.B path_lzop \fR(default: lzop)\fR
363
.TP
364
.B path_rar \fR(default: rar)\fR
365
.TP
366
.B path_unrar \fR(default: unrar)\fR
367
.TP
368
.B path_lha \fR(default: lha)\fR
369
.TP
370
.B path_unace \fR(default: unace)\fR
371
.TP
372
.B path_ar \fR(default: ar)\fR
373
.TP
374
.B path_arj \fR(default: arj)\fR
375
.TP
376
.B path_unarj \fR(default: unarj)\fR
377
.TP
378
.B path_arc \fR(default: arc)\fR
379
.TP
380
.B path_nomarch \fR(default: nomarch)\fR
381
.TP
382
.B path_rpm \fR(default: rpm)\fR
383
.TP
384
.B path_rpm2cpio \fR(default: rpm2cpio)\fR
385
.TP
386
.B path_cpio \fR(default: cpio)\fR
387
.TP
388
.B path_file \fR(default: file)\fR
389
.TP
390
.B path_find \fR(default: find)\fR
391
.TP
392
.B path_xargs \fR(default: xargs)\fR
393
.TP
394
.B path_cat \fR(default: cat)\fR
395
.TP
396
.B path_diff \fR(default: diff)\fR
397
These are all paths to the corresponding programs. It is usually
398
best to leave them as is, because that way their locations can be
399
looked up from the PATH variable.
400
.TP
401
.B args_diff \fR(default: -ru)\fR
402
This variable specifies command line arguments to pass to the
403
diff command (as specified by path_diff) when using adiff. Space
404
characters separate arguments in this string.
405
.TP
406
.B path_syscfg \fR(default: /etc/atool.conf)\fR
407
(This variable can only be set in the atool program file.)
408
This variable specifies the directory where the system-wide
409
configuration file is located.
410
.TP
411
.B path_usercfg \fR(default: .atoolrc)\fR
412
(This variable can only be set in the atool program file
413
and system-wide configuration file.)
414
This variable specifies where the user configuration file
415
is located. Note that if this filename is relative (i.e. doesn't
416
being with `/'), it will be relative to the current user's home
417
directory (as determined by the HOME environment variable).
418
.TP
419
.B default_verbosity \fR(default: 1)\fR
420
This is the default verbosity of atool. By using -q and -v
421
options, the verbosity level can be raised and lowered.
422
Level 1 means "normal verbosity" - e.g. when creating and
423
extracting from archives, files will be listed.
424
.TP
425
.B show_extracted \fR(default: 1)\fR
426
If this is set to 1, the aunpack command will always show
427
what file or directory that was extracted. Otherwise
428
that will only be printed if the archive was extracted to
429
an unexpected location (as a result of local files already
430
existing or the archive having multiple files in its root
431
directory).
432
433
This can be quite useful in combinatiaon with `default_verbosity 0'.
434
Note that this option will have no effect when the -X option is used
435
with aunpack, and it has no effect on compressed files.
436
.TP
437
.B keep_compressed \fR(default: 1)\fR
438
When compressing a file with gzip or bzip2, the original (uncompressed)
439
file is usually deleted once it has been compressed. I.e. if you
440
compress a file "test" you will end up with only one file, "test.gz".
441
With this option set to 1, you will make atool keep the original file
442
as well. The original behaviour is achieved by setting this option to 0.
443
444
This option also has an equivalent effect on uncompressing compressed
445
files. When set to 1, the original (compressed) file will be kept.
446
Otherwise it will be deleted.
447
448
Note however that this option has no effect when packing up a compressed
449
file with the -X option (for specifying an output directory or file). In
450
that case the original file is always kept.
451
.TP
452
.B decompress_to_cwd \fR(default: 1)\fR
453
When decompressing a file with commands such as gzip or bzip2, the
454
decompressed file is usually placed in the same directory as the
455
compressed file. With this option set to 1, the decompressed file is
456
instead placed in the current working directory.
457
458
Note that this option has no effect when -X is used.
459
460
.SH ENVIRONMENT VARIABLES
461
.B PAGER
462
The default pager to use when the -p/--page option is specified.
463
.SH EXAMPLES
464
To extract all files from archive `foobar.tar.gz' to a subdirectory
465
(or the current directory if it only contains one file):
466
.br
467
\fBaunpack foobar.tar.gz\fP
468
.PP
469
To extract all files from all `.tar.gz' archives in the
470
current directory:
471
.br
472
\fBaunpack -e *.tar.gz\fP
473
.PP
474
To create a zip archive of two files `foo' and `bar':
475
.br
476
\fBapack myarchive.zip foo bar\fP
477
.PP
478
To display the file `baz' in the archive `myarchive.zip'
479
through a pager:
480
.br
481
\fBacat -p myarchive.zip baz\fP
482
.PP
483
To list contents of the rar archive `stuff.rar':
484
.br
485
\fBals stuff.rar\fP
486
.PP
487
To create three archives, `dir1.tar.gz', `dir2.tar.gz' and `dir3.tar.gz',
488
so that the first one contains all files in dir1, the second all
489
in dir2 and the third all dir3:
490
.br
491
\fBapack -e -F .tar.gz dir1 dir2 dir3\fP
492
.PP
493
To show all differences between version 2.4.17 and 2.4.18 of the kernel:
494
.br
495
\fBadiff linux-2.4.17.tar.gz linux-2.4.18.tar.gz\fP
496
.PP
497
Here's a shell function that will make the aunpack command change into the
498
directory where files were extracted:
499
.br
500
\fBaunpack () {\fP
501
.br
502
\fB TMP=`mktemp /tmp/aunpack.XXXXXXXXXX`\fP
503
.br
504
\fB atool -x --save-outdir=$TMP "$@"\fP
505
.br
506
\fB DIR="`cat $TMP`"\fP
507
.br
508
\fB [ "$DIR" != "" -a -d "$DIR" ] && cd "$DIR"\fP
509
.br
510
\fB rm $TMP\fP
511
.br
512
\fB}\fP
513
.br
514
If you don't have the mktemp program, you can replace the second line with
515
(note however that this is not entirely safe)
516
.br
517
\fB TMP="/tmp/atool_outdir.$$"\fP
518
.PP
519
.SH KNOWN BUGS
520
Trying to extract gzip and other compressed files without the .gz (or .bz2
521
etc) extension won't work:
522
.PP
523
aunpack: foo: format not known, identifying using file
524
aunpack: foo: format is `gzip'
525
gzip: foo: unknown suffix -- ignored
526
.PP
527
This last error above is generated by \fBgzip -d foo\fP.
528
.PP
529
If you find a bug not listed here, please report it to <@PACKAGE_BUGREPORT@>.
530
.SH AUTHOR
531
atool was written by Oskar Liljeblad.
Loggerhead is a web-based interface for Breezy
Version: 2.0.1