Fri, 23 Nov 2007 16:25:22 -0500
[svn] Improve the error reporting to be more user-friendly, at least in many of
the really basic cases.
19 | 1 | dtrx - Intelligent archive extraction |
2 | ===================================== | |
18
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
3 | |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
4 | Introduction |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
5 | ------------ |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
6 | |
19 | 7 | dtrx extracts archives in a number of different formats; it currently |
37 | 8 | supports tar, zip, cpio, rpm, deb, gem, 7z, and cab files. It can also |
9 | decompress files compressed with gzip, bzip2, lzma, or compress. | |
18
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
10 | |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
11 | In addition to providing one command to handle many different archive |
19 | 12 | types, dtrx also aids the user by extracting contents consistently. By |
18
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
13 | default, everything will be written to a dedicated directory that's named |
19 | 14 | after the archive. dtrx will also change the permissions to ensure that the |
18
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
15 | owner can read and write all those files. |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
16 | |
37 | 17 | Requirements |
18 | ------------ | |
19 | ||
20 | If you have Python 2.4, this should work out of the box. If you're stuck | |
21 | on Python 2.3, you can use this if you install the `subprocess module`_. | |
22 | You'll need the usual tools for the archive types you want to extract: for | |
23 | example, if you're extracting zip files, you'll need zipinfo and unzip. | |
24 | ||
25 | .. _`subprocess module`: http://www.lysator.liu.se/~astrand/popen5/ | |
26 | ||
27 | Installation | |
28 | ------------ | |
29 | ||
30 | You can just put scripts/dtrx wherever is convenient for you, but if you | |
31 | want to install the program system-wide, you can also run:: | |
32 | ||
33 | # python setup.py install | |
34 | ||
19 | 35 | Running dtrx |
36 | ------------ | |
18
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
37 | |
19 | 38 | To run dtrx, simply call it with the archive(s) you wish to extract as |
18
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
39 | arguments. For example:: |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
40 | |
37 | 41 | $ dtrx coreutils-5.*.tar.gz |
18
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
42 | |
19 | 43 | dtrx supports a number of options to mandate specific behavior: |
18
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
44 | |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
45 | -r, --recursive |
19 | 46 | With this option, dtrx will search inside the archives you specify to see |
18
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
47 | if any of the contents are themselves archives, and extract those as |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
48 | well. |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
49 | |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
50 | -o, --overwrite |
19 | 51 | Normally, dtrx will avoid extracting into a directory that already exists, |
18
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
52 | and instead try to find an alternative name to use. If this option is |
19 | 53 | listed, dtrx will use the default directory name no matter what. |
18
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
54 | |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
55 | -f, --flat |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
56 | Extract archive contents into the current directory, instead of their |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
57 | own dedicated directory. This is handy if you have multiple archive |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
58 | files which all need to be extracted into the same directory structure. |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
59 | Note that existing files may be overwritten with this option. |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
60 | |
24 | 61 | -n, --noninteractive |
62 | dtrx will normally ask the user how to handle certain corner cases, such | |
63 | as how to handle an archive that only contains one file. This option | |
37 | 64 | suppresses those questions; dtrx will instead use sane, conservative |
65 | defaults. | |
24 | 66 | |
19 | 67 | -l, -t, --list, --table |
68 | Don't extract the archives; just list their contents on standard output. | |
69 | ||
37 | 70 | -m, --metadata |
71 | Extract the metadata from .deb and .gem archives, instead of their normal | |
72 | contents. | |
73 | ||
18
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
74 | -q, --quiet |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
75 | Suppress warning messages. Listing this option twice will cause the |
19 | 76 | dtrx to be silent if at all possible. |
18
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
77 | |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
78 | -v, --verbose |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
79 | Print more information about x's behavior. You can list this option up |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
80 | to three times for more information. |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
81 | |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
82 | --help |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
83 | Display basic help. |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
84 | |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
85 | --version |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
86 | Display x's version, copyright, and license information. |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
87 | |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
88 | Other Useful Information |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
89 | ------------------------ |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
90 | |
28
4d88f2231d33
[svn] Change all the license notices from GPLv2 to GPLv3.
brett
parents:
24
diff
changeset
|
91 | dtrx 5.0 is copyright (c) 2006, 2007 `Brett Smith`_. Feel free to send |
19 | 92 | comments, bug reports, patches, and so on. You can find the latest version |
93 | of dtrx on `its home page`_. | |
18
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
94 | |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
95 | .. _`Brett Smith`: mailto:brettcsmith@brettcsmith.org |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
96 | .. _`its home page`: http://www.brettcsmith.org/2006/x/ |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
97 | |
19 | 98 | dtrx is free software; you can redistribute it and/or modify it under the |
18
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
99 | terms of the GNU General Public License as published by the Free Software |
28
4d88f2231d33
[svn] Change all the license notices from GPLv2 to GPLv3.
brett
parents:
24
diff
changeset
|
100 | Foundation; either version 3 of the License, or (at your option) any later |
18
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
101 | version. |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
102 | |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
103 | This program is distributed in the hope that it will be useful, but WITHOUT |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
104 | ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
105 | FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
106 | more details. |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
107 | |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
108 | You should have received a copy of the GNU General Public License along |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
109 | with this program; if not, write to the Free Software Foundation, Inc., 51 |
1600807a32bd
[svn] Add basic documentation, and make this version 3.0.
brett
parents:
diff
changeset
|
110 | Franklin Street, 5th Floor, Boston, MA, 02111. |