Asynchronous Tar implemented in node
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Tar-async is an async approach to Tar in node.

Tar-async does not directly use the filesystem at all. This makes it really easy to use for practically anything. All that's required to tar something is a filename and data.

No compression is used, so an external compression library is necessary. This is by design and not likely to be implemented.



var Tar = require('tar-async'), // or require('tar-async').Tar or require('tar-async/tar')
	tape = new Tar({output: require('fs').createWriteStream('out.tar')});

tape.append('test.txt', 'Woohoo!! Tar me up Scotty!', function () {

Simple huh? A Tar instance is an EventEmitter, and emits these events: 'end', 'data' (and maybe 'error' in the future)


var Untar = require('tar-async/untar'), // or require('tar-async').Untar
	fs = require('fs'),
	untar = new Untar(function (err, header, fileStream) {
		fileStream.on('data', function (data) {


Untar is a Writable Stream, so it's pretty easy to asynchronously untar something.


Ok, so you want more detail. Here ya go:



Supported options include:

  • recordsPerBlock- number of records in a block, default is 20 (don't change unless you know what you're doing)
  • consolidate- default false; whether to consolidate everything into a single directory
  • normalize- default true; whether to normalize each file's path
  • output- default null; writable stream to stream output to
  • allowPipe- default false; allow Stream.pipe (this will cache the stream to get the size)

Tar.append(filepath, input, opts, callback):

  • filepath- filepath for file when extracted
  • input- string or Buffer
  • opts- optional options
    • mode- permissions on the file (default 777)
    • mtime- last modified time in seconds (default current time)
    • uid- owner id (default 0)
    • gid- group id (default 0)
    • size- size of output (default input.length; changing this could lead to bad results)
  • callback- optional callback; no parameters; called when a record is written


Untar(opts, callback)

  • opts
    • fileTypes- if not defined, defaults to normal and contiguous files; these are the options (any single one or an array of multiple ones)
      • 'normal'- normal file
      • 'hard-link'- hard link
      • 'symbolic-link'- symbolic link
      • 'character-special'- device files that moves data by characters; this type of file usually has a majorNumber and minorNumber
      • 'block-special'- device files that moves data in blocks; this type of file usually has a majorNumber and minorNumber
      • 'directory'- directory
      • 'fifo'- named pipe; doesn't have data
      • 'contiguous-file'- same as file, but it's allocated contiguously on disk
  • callback- callback each time a record is read; parameters are
    • err- only used when checksums don't match
    • header- header data (see header.js for details
    • fileStream- Readable Stream; chunks will be emitted as Buffer objects