1# deco file extraction framework
2
3deco is a Un*x program, written in C, that is able to extract various file
4formats using small “extractor wrapper” scripts.
5
6
7
8## Features
9
10
11### Consistent command line interface
12
13Instead of having to remember e. g.
14
15    tar xjf 1.tar.bz2
16    unrar x 2.rar
17    flac -d 3.flac
18    dpkg-deb --extract 4.deb
19
20you say
21
22    deco 1.tar.bz2 2.rar 3.flac 4.deb
23
24and deco extracts them all, provided you’ve also installed the
25[deco-archive package](https://github.com/peha/deco-archive).
26
27
28### Consistent behavior
29
30#### Where to extract
31
32Some extractors extract in the current working directory, others use the
33directory the archive resides in. deco extracts relative to the current working
34directory, unless you give it the `-a` (“absolute”) option.
35
36#### Delete archive?
37
38Some extractors delete the archive after successful extraction, others don’t.
39deco preserves the archive after successful extraction, unless you give it the
40`-u` (“unlink”) option.
41
42#### Quiet or verbose
43
44Some extractors process the archive verbosely by default and expect you to
45specify that quiet behavior is wanted. Others do the opposite. deco extracts
46quietly, unless you give it the `-v` (“verbose”) option.
47
48#### Partial content
49
50Some extractors will leave the partial content extracted so far around if
51extraction fails. Others will delete it. deco will keep partial content, unless
52you give it the `-c` (“clean”) option.
53
54#### Unknown file extensions
55
56Some extractors refuse to even try extracting anything with an unknown
57extension. deco can force an extractor to handle a file with any name. Use the
58`-e` (“extension”) option: `deco -e gz myarchive`
59
60#### Sanitized permissions
61
62There are extractors that create files with strange permissions. deco can reset
63these to sensible defaults implied by your current umask.
64
65#### No tarbombs
66
67When you extract an archive that contains multiple files at its top level, you
68usually want them to be placed in a directory of their own. However, if the
69archive contains only one file or one big directory, that behavior would be
70annoying. The deco extraction algorithm does the right thing automatically:
71generally, if and only if archive.foo contains multiple files at its top level,
72a new directory called archive/ is created and the archive gets extracted there.
73
74#### No overwriting
75
76deco never overwrites files, nor does it need to prompt you for manual conflict
77resolution. If the file to be extracted is named foo and a file by that name
78already exists, the new file will be extracted as 1-foo, if that name also
79exists, 2-foo, and so on.  Since at the top level only one new file or directory
80is created, at most this one file will have its name changed like that.
81
82
83### Modular design
84
85As all the heavy lifting is done in the core algorithm, [adding support for new
86archive formats requires very little work](API.md).
87
88
89
90## Installation
91
921. **Configure:**  Edit config.mk to change compiler/linker settings, the
93   location to install at, or the location where deco looks for extractor
94   wrappers.
95
962. **Build:**  Run `make`. If you have trouble building on BSD, try removing
97   -D_XOPEN_SOURCE=600 from CPPFLAGS in config.mk.
98
993. **Install:**  Run `make install`. (You will probably need to do this as the
100   superuser.) To add support for popular archive formats, also install
101   [deco-archive](https://github.com/peha/deco-archive).
102
1034. **Use:**  Run `deco` to see the usage message.
104
105
106
107## Links
108
109
110### Extractor wrappers for deco
111
112- [deco-archive](https://github.com/peha/deco-archive): support for popular
113  archive formats
114- [deco-diskimage](http://www.daeghnao.com/deco-diskimage/): support for filesystem disk images
115
116
117### Similar programs
118
119- [archery](http://pturing.firehead.org/software/archery/)
120- [atool](http://www.nongnu.org/atool/)
121- [ax](http://www.noah.org/wiki/Ax_Archive_Extract)
122- [bloat](http://www.bloat.org.uk/)
123- [dtrx](http://brettcsmith.org/2007/dtrx/)
124- [e](http://martin.ankerl.com/2006/08/11/program-e-extract-any-archive),
125  and [a modified version](http://blog.thoughtfolder.com/2008-02-01-the-script-i-use-every-day.html)
126- [libarchive](https://github.com/libarchive/libarchive)
127- [unarc](http://membled.com/work/apps/unarc/)
128- [unfoo](http://obsoleet.org/code/unfoo/)
129- [unp](http://packages.debian.org/unstable/source/unp)
130
131
132
133## Credits
134
135Copyright 2007-2015 Peter Hartlich. [Licensed under the terms of the GNU General
136Public License, version 3.](LICENSE)
137
138
139### Thanks to:
140
141- Zoë Stephenson for several bug reports
142- Reuben Thomas for the Makefile uninstall target, suggesting that the usage
143  message include deco’s version, and reporting various problems
144- Steve Milner for the concept of what is now the `subdirectory` file
145- Dirk Jagdmann for reporting the problem with extracting large files
146- Michael Schwendt for diagnosing a crash when handling archive formats that
147  always extract to a subdirectory
148