1 | # Archiver v0.10.1 [![Build Status](https://travis-ci.org/ctalkington/node-archiver.svg?branch=master)](https://travis-ci.org/ctalkington/node-archiver)
|
2 |
|
3 | a streaming interface for archive generation
|
4 |
|
5 | [![NPM](https://nodei.co/npm/archiver.png)](https://nodei.co/npm/archiver/)
|
6 |
|
7 | ## Install
|
8 |
|
9 | ```bash
|
10 | npm install archiver --save
|
11 | ```
|
12 |
|
13 | You can also use `npm install https://github.com/ctalkington/node-archiver/archive/master.tar.gz` to test upcoming versions.
|
14 |
|
15 | ## Archiver
|
16 |
|
17 | #### create(format, options)
|
18 |
|
19 | Creates an Archiver instance based on the format (zip, tar, etc) passed. Parameters can be passed directly to `Archiver` constructor for convenience.
|
20 |
|
21 | #### registerFormat(format, module)
|
22 |
|
23 | Registers an archive format. Format modules are essentially transform streams with a few required methods. They will be further documented once a formal spec is in place.
|
24 |
|
25 | ### Instance Methods
|
26 |
|
27 | Inherits [Transform Stream](http://nodejs.org/api/stream.html#stream_class_stream_transform) methods.
|
28 |
|
29 | #### append(input, data)
|
30 |
|
31 | Appends an input source (text string, buffer, or stream) to the instance. When the instance has received, processed, and emitted the input, the `entry` event is fired.
|
32 |
|
33 | Replaced `#addFile` in v0.5.
|
34 |
|
35 | ```js
|
36 | archive.append('string', { name:'string.txt' });
|
37 | archive.append(new Buffer('string'), { name:'buffer.txt' });
|
38 | archive.append(fs.createReadStream('mydir/file.txt'), { name:'stream.txt' });
|
39 | archive.append(null, { name:'dir/' });
|
40 | ```
|
41 |
|
42 | #### bulk(mappings)
|
43 |
|
44 | Appends multiple entries from passed array of src-dest mappings. A lazystream wrapper is used to prevent issues with open file limits.
|
45 |
|
46 | Globbing patterns are supported through use of the [file-utils](https://github.com/SBoudrias/file-utils) package. Please note that multiple src files to single dest file (ie concat) is not supported.
|
47 |
|
48 | The `data` property can be set (per src-dest mapping) to define data for matched entries.
|
49 |
|
50 | ```js
|
51 | archive.bulk([
|
52 | { src: ['mydir/**'], data: { date: new Date() } },
|
53 | { expand: true, cwd: 'mydir', src: ['**'], dest: 'newdir' }
|
54 | ]);
|
55 | ```
|
56 |
|
57 | For more detail on this feature, please see [BULK.md](https://github.com/ctalkington/node-archiver/blob/master/BULK.md).
|
58 |
|
59 | #### file(filepath, data)
|
60 |
|
61 | Appends a file given its filepath using a lazystream wrapper to prevent issues with open file limits. When the instance has received, processed, and emitted the file, the `entry` event is fired.
|
62 |
|
63 | ```js
|
64 | archive.file('mydir/file.txt', { name:'file.txt' });
|
65 | ```
|
66 |
|
67 | #### finalize()
|
68 |
|
69 | Finalizes the instance. You should listen for the `end`/`close`/`finish` of the destination stream to properly detect completion.
|
70 |
|
71 | #### pointer()
|
72 |
|
73 | Returns the current byte length emitted by archiver. Use this in your end callback to log generated size.
|
74 |
|
75 | ## Events
|
76 |
|
77 | Inherits [Transform Stream](http://nodejs.org/api/stream.html#stream_class_stream_transform) events.
|
78 |
|
79 | #### entry
|
80 |
|
81 | Fired when the input has been received, processed, and emitted. Passes entry data as first argument.
|
82 |
|
83 | ## Zip
|
84 |
|
85 | ### Options
|
86 |
|
87 | #### comment `string`
|
88 |
|
89 | Sets the zip comment.
|
90 |
|
91 | #### forceUTC `boolean`
|
92 |
|
93 | If true, forces the entry date to UTC. Helps with testing across timezones.
|
94 |
|
95 | #### store `boolean`
|
96 |
|
97 | If true, all entry contents will be archived without compression by default.
|
98 |
|
99 | #### zlib `object`
|
100 |
|
101 | Passed to node's [zlib](http://nodejs.org/api/zlib.html#zlib_options) module to control compression. Options may vary by node version.
|
102 |
|
103 | ### Entry Data
|
104 |
|
105 | #### name `string` `required`
|
106 |
|
107 | Sets the entry name including internal path.
|
108 |
|
109 | #### date `string|Date`
|
110 |
|
111 | Sets the entry date. This can be any valid date string or instance. Defaults to current time in locale.
|
112 |
|
113 | #### store `boolean`
|
114 |
|
115 | If true, entry contents will be archived without compression.
|
116 |
|
117 | #### comment `string`
|
118 |
|
119 | Sets the entry comment.
|
120 |
|
121 | #### mode `number`
|
122 |
|
123 | Sets the entry permissions. Defaults to octal 0755 (directory) or 0644 (file).
|
124 |
|
125 | ## Tar
|
126 |
|
127 | ### Options
|
128 |
|
129 | #### gzip `boolean`
|
130 |
|
131 | Compresses the tar archive using gzip, default is false.
|
132 |
|
133 | #### gzipOptions `object`
|
134 |
|
135 | Passed to node's [zlib](http://nodejs.org/api/zlib.html#zlib_options) module to control compression. Options may vary by node version.
|
136 |
|
137 | ### Entry Data
|
138 |
|
139 | #### name `string` `required`
|
140 |
|
141 | Sets the entry name including internal path.
|
142 |
|
143 | #### date `string|Date`
|
144 |
|
145 | Sets the entry date. This can be any valid date string or instance. Defaults to current time in locale.
|
146 |
|
147 | #### mode `number`
|
148 |
|
149 | Sets the entry permissions. Defaults to octal 0755 (directory) or 0644 (file).
|
150 |
|
151 | ## Libraries
|
152 |
|
153 | Archiver makes use of several libraries/modules to avoid duplication of efforts.
|
154 |
|
155 | - [zip-stream](https://npmjs.org/package/zip-stream)
|
156 | - [tar-stream](https://npmjs.org/package/tar-stream)
|
157 |
|
158 | ## Things of Interest
|
159 |
|
160 | - [Examples](https://github.com/ctalkington/node-archiver/blob/master/examples)
|
161 | - [Changelog](https://github.com/ctalkington/node-archiver/releases)
|
162 | - [Contributing](https://github.com/ctalkington/node-archiver/blob/master/CONTRIBUTING.md)
|
163 | - [MIT License](https://github.com/ctalkington/node-archiver/blob/master/LICENSE-MIT) |
\ | No newline at end of file |