Skip to content

Commit c1faa9f

Browse files
isaacslukekarrys
authored andcommitted
docs: add examples/explanation of using tar.t
Fix: #308 Fix: #307
1 parent 065e385 commit c1faa9f

File tree

1 file changed

+36
-8
lines changed

1 file changed

+36
-8
lines changed

README.md

+36-8
Original file line numberDiff line numberDiff line change
@@ -209,6 +209,19 @@ tar.t({
209209
})
210210
```
211211

212+
For example, to just get the list of filenames from an archive:
213+
214+
```js
215+
const getEntryFilenames = async tarballFilename => {
216+
const filenames = []
217+
await tar.t({
218+
file: tarballFilename,
219+
onentry: entry => filenames.push(entry.path),
220+
})
221+
return filenames
222+
}
223+
```
224+
212225
To replicate `cat my-tarball.tgz | tar t` do:
213226

214227
```js
@@ -223,6 +236,18 @@ When the function returns, it's already done. Sync methods without a
223236
file argument return a sync stream, which flushes immediately. But,
224237
of course, it still won't be done until you `.end()` it.
225238

239+
```js
240+
const getEntryFilenamesSync = tarballFilename => {
241+
const filenames = []
242+
tar.t({
243+
file: tarballFilename,
244+
onentry: entry => filenames.push(entry.path),
245+
sync: true,
246+
})
247+
return filenames
248+
}
249+
```
250+
226251
To filter entries, add `filter: <function>` to the options.
227252
Tar-creating methods call the filter with `filter(path, stat)`.
228253
Tar-reading methods (including extraction) call the filter with
@@ -429,15 +454,18 @@ no paths are provided, then all the entries are listed.
429454

430455
If the archive is gzipped, then tar will detect this and unzip it.
431456

432-
Returns an event emitter that emits `entry` events with
433-
`tar.ReadEntry` objects. However, they don't emit `'data'` or `'end'`
434-
events. (If you want to get actual readable entries, use the
435-
`tar.Parse` class instead.)
457+
If the `file` option is _not_ provided, then returns an event emitter that
458+
emits `entry` events with `tar.ReadEntry` objects. However, they don't
459+
emit `'data'` or `'end'` events. (If you want to get actual readable
460+
entries, use the `tar.Parse` class instead.)
461+
462+
If a `file` option _is_ provided, then the return value will be a promise
463+
that resolves when the file has been fully traversed in async mode, or
464+
`undefined` if `sync: true` is set. Thus, you _must_ specify an `onentry`
465+
method in order to do anything useful with the data it parses.
436466

437467
The following options are supported:
438468

439-
- `cwd` Extract files relative to the specified directory. Defaults
440-
to `process.cwd()`. [Alias: `C`]
441469
- `file` The archive file to list. If not specified, then a
442470
Writable stream is returned where the archive data should be
443471
written. [Alias: `f`]
@@ -449,8 +477,8 @@ The following options are supported:
449477
entry being listed. Return `true` to emit the entry from the
450478
archive, or `false` to skip it.
451479
- `onentry` A function that gets called with `(entry)` for each entry
452-
that passes the filter. This is important for when both `file` and
453-
`sync` are set, because it will be called synchronously.
480+
that passes the filter. This is important for when `file` is set,
481+
because there is no other way to do anything useful with this method.
454482
- `maxReadSize` The maximum buffer size for `fs.read()` operations.
455483
Defaults to 16 MB.
456484
- `noResume` By default, `entry` streams are resumed immediately after

0 commit comments

Comments
 (0)