Skip to content

Commit

Permalink
not maintaining benches atm, still fast tho
Browse files Browse the repository at this point in the history
  • Loading branch information
mafintosh committed Jun 17, 2023
1 parent 6d66143 commit e91a3b7
Showing 1 changed file with 23 additions and 34 deletions.
57 changes: 23 additions & 34 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,22 +1,20 @@
# tar-fs

filesystem bindings for [tar-stream](https://github.com/mafintosh/tar-stream).
Filesystem bindings for [tar-stream](https://github.com/mafintosh/tar-stream).

```
npm install tar-fs
```

[![build status](https://secure.travis-ci.org/mafintosh/tar-fs.png)](http://travis-ci.org/mafintosh/tar-fs)

## Usage

tar-fs allows you to pack directories into tarballs and extract tarballs into directories.

It doesn't gunzip for you, so if you want to extract a `.tar.gz` with this you'll need to use something like [gunzip-maybe](https://github.com/mafintosh/gunzip-maybe) in addition to this.

``` js
var tar = require('tar-fs')
var fs = require('fs')
const tar = require('tar-fs')
const fs = require('fs')

// packing a directory
tar.pack('./my-directory').pipe(fs.createWriteStream('my-tarball.tar'))
Expand All @@ -30,20 +28,20 @@ is also an alias for `filter`. Additionally you get `header` if you use ignore w
That way you could also filter by metadata.

``` js
var pack = tar.pack('./my-directory', {
ignore: function(name) {
const pack = tar.pack('./my-directory', {
ignore (name) {
return path.extname(name) === '.bin' // ignore .bin files when packing
}
})

var extract = tar.extract('./my-other-directory', {
ignore: function(name) {
const extract = tar.extract('./my-other-directory', {
ignore (name) {
return path.extname(name) === '.bin' // ignore .bin files inside the tarball when extracing
}
})

var extractFilesDirs = tar.extract('./my-other-other-directory', {
ignore: function(_, header) {
const extractFilesDirs = tar.extract('./my-other-other-directory', {
ignore (_, header) {
// pass files & directories, ignore e.g. symlinks
return header.type !== 'file' && header.type !== 'directory'
}
Expand All @@ -53,23 +51,23 @@ var extractFilesDirs = tar.extract('./my-other-other-directory', {
You can also specify which entries to pack using the `entries` option

```js
var pack = tar.pack('./my-directory', {
const pack = tar.pack('./my-directory', {
entries: ['file1', 'subdir/file2'] // only the specific entries will be packed
})
```

If you want to modify the headers when packing/extracting add a map function to the options

``` js
var pack = tar.pack('./my-directory', {
map: function(header) {
const pack = tar.pack('./my-directory', {
map (header) {
header.name = 'prefixed/'+header.name
return header
}
})

var extract = tar.extract('./my-directory', {
map: function(header) {
const extract = tar.extract('./my-directory', {
map (header) {
header.name = 'another-prefix/'+header.name
return header
}
Expand All @@ -79,31 +77,31 @@ var extract = tar.extract('./my-directory', {
Similarly you can use `mapStream` incase you wanna modify the input/output file streams

``` js
var pack = tar.pack('./my-directory', {
mapStream: function(fileStream, header) {
const pack = tar.pack('./my-directory', {
mapStream (fileStream, header) {
// NOTE: the returned stream HAS to have the same length as the input stream.
// If not make sure to update the size in the header passed in here.
if (path.extname(header.name) === '.js') {
return fileStream.pipe(someTransform)
}
return fileStream;
return fileStream
}
})

var extract = tar.extract('./my-directory', {
mapStream: function(fileStream, header) {
const extract = tar.extract('./my-directory', {
mapStream (fileStream, header) {
if (path.extname(header.name) === '.js') {
return fileStream.pipe(someTransform)
}
return fileStream;
return fileStream
}
})
```

Set `options.fmode` and `options.dmode` to ensure that files/directories extracted have the corresponding modes

``` js
var extract = tar.extract('./my-directory', {
const extract = tar.extract('./my-directory', {
dmode: parseInt(555, 8), // all dirs should be readable
fmode: parseInt(444, 8) // all files should be readable
})
Expand Down Expand Up @@ -140,9 +138,9 @@ leave the pack stream open for further entries (see
and use `pack` to pass an existing pack stream.

``` js
var mypack = tar.pack('./my-directory', {
const mypack = tar.pack('./my-directory', {
finalize: false,
finish: function(sameAsMypack) {
finish (sameAsMypack) {
mypack.entry({name: 'generated-file.txt'}, "hello")
tar.pack('./other-directory', {
pack: sameAsMypack
Expand All @@ -151,15 +149,6 @@ var mypack = tar.pack('./my-directory', {
})
```


## Performance

Packing and extracting a 6.1 GB with 2496 directories and 2398 files yields the following results on my Macbook Air.
[See the benchmark here](https://gist.github.com/mafintosh/8102201)

* tar-fs: 34.261 seconds
* [node-tar](https://github.com/isaacs/node-tar): 366.123 seconds (or 10x slower)

## License

MIT

0 comments on commit e91a3b7

Please sign in to comment.