Interface TarOptions

For WriteEntry objects, the absolute path to the entry on the filesystem. By default, this is resolve(cwd, entry.path), but it can be overridden explicitly.

Set to true or an object with settings for zlib.BrotliCompress() to create a brotli-compressed archive

When extracting, this will cause the archive to be treated as a brotli-compressed file if set to true or a ZlibOptions object.

If set false, then brotli options will not be used.

If this, the gzip, and zstd options are left undefined, then tar will attempt to infer the brotli compression status, but can only do so based on the filename. If the filename ends in .tbr or .tar.br, and the first 512 bytes are not a valid tar header, then brotli decompression will be attempted.

Call chmod() to ensure that extracted files match the entry's mode field. Without this field set, all mode fields in archive entries are a best effort attempt only.

Setting this necessitates a call to the deprecated process.umask() method to determine the default umask value, unless a processUmask config is provided as well.

If not set, tar will attempt to create file system entries with whatever mode is provided, and let the implicit process umask apply normally, but if a file already exists to be written to, then its existing mode will not be modified.

When setting chmod: true, it is highly recommend to set the TarOptions#processUmask option as well, to avoid the call to the deprecated (and thread-unsafe) process.umask() method.

The effective current working directory for this tar command

Map that tracks which directories already exist, for extraction

Default mode for directories. Used for all implicitly created directories, and any directories in the archive that do not have a mode field.

The tar file to be read and/or written. When this is set, a stream is not returned. Asynchronous commands will return a promise indicating when the operation is completed, and synchronous commands will return immediately.

A function that is called with (path, stat) when creating an archive, or (path, entry) when extracting. Return true to process the file/entry, or false to exclude it.

default mode for files

Pack the targets of symbolic links rather than the link itself.

Mostly for testing, but potentially useful in some cases. Forcibly trigger a chown on every entry, no matter what.

When extracting, force all created files and directories, and all implicitly created directories, to be owned by the specified group id, regardless of the gid field in the archive.

Cannot be used along with preserveOwner. Requires also setting the uid option.

When creating a tar archive, this can be used to compress it as well. Set to true to use the default gzip options, or customize them as needed.

When reading, if this is unset, then the compression status will be inferred from the archive data. This is generally best, unless you are sure of the compression settings in use to create the archive, and want to fail if the archive doesn't match expectations.

Number of concurrent jobs to run when creating archives.

Defaults to 4.

When extracting, do not overwrite existing files at all.

A Map object containing the device and inode value for any file whose nlink value is greater than 1, to identify hard links when creating archives.

The maximum depth of subfolders to extract into. This defaults to 1024. Anything deeper than the limit will raise a warning and skip the entry. Set to Infinity to remove the limitation.

maximum supported size of meta entries. Defaults to 1MB

maximum buffer size for fs.read() operations.

The mode to set on any created file archive, defaults to 0o666 masked by the process umask, often resulting in 0o644.

This does not affect the mode fields of individual entries, or the mode status of extracted entries on the filesystem.

Set to a Date object to force a specific mtime value for everything written to an archive.

This is useful when creating archives that are intended to be deterministic based on their contents, irrespective of the file's last modification time.

Overridden by noMtime.

A cache of mtime values, to avoid having to stat the same file repeatedly.

When extracting, keep the existing file on disk if it's newer than the file in the archive.

When creating archives, do not recursively archive the contents of directories. By default, archiving a directory archives all of its contents as well.

When extracting, do not set the mtime value for extracted entries to match the mtime in the archive.

When creating archives, do not store the mtime value in the entry. Note that this prevents properly using other mtime-based features (such as tar.update or the newer option) with the resulting archive.

Suppress Pax extended headers when creating archives. Note that this means long paths and linkpaths will be truncated, and large or negative numeric values may be interpreted incorrectly.

When parsing/listing archives, entry streams are by default resumed (set into "flowing" mode) immediately after the call to onReadEntry(). Set noResume: true to suppress this behavior.

Note that when this is set, the stream will never complete until the data is consumed somehow.

Set automatically in extract operations, since the entry is piped to a file system entry right away. Only relevant when parsing.

Used with Parser stream interface, to attach and take over when the stream is completely parsed. If this is set, then the prefinish, finish, and end events will not fire, and are the responsibility of the ondone method to emit properly.

ambiguous deprecated name for onReadEntry

When extracting or listing archives, this method will be called with each entry that is not excluded by a filter.

Important when listing archives synchronously from a file, because there is otherwise no way to interact with the data!

A function that gets called for any warning encountered.

Note: if strict is set, then the warning will throw, and this method will not be called.

When creating, updating, or replacing within archives, this method will be called with each WriteEntry that is created.

When creating archives, omit any metadata that is system-specific: ctime, atime, uid, gid, uname, gname, dev, ino, and nlink. Note that mtime is still included, because this is necessary for other time-based operations such as tar.update. Additionally, mode is set to a "reasonable default" for mose unix systems, based on an effective umask of 0o22.

This also defaults the portable option in the gzip configs when creating a compressed archive, in order to produce deterministic archives that are not operating-system specific.

A path portion to prefix onto the entries added to an archive.

When extracting, set the uid and gid of extracted entries to the uid and gid fields in the archive. Defaults to true when run as root, and false otherwise.

If false, then files and directories will be set with the owner and group of the user running the process. This is similar to -p in tar(1), but ACLs and other system-specific data is never unpacked in this implementation, and modes are set by default already.

When creating archives, preserve absolute and .. paths in the archive, rather than sanitizing them under the cwd.

When extracting, allow absolute paths, paths containing .., and extracting through symbolic links. By default, the root / is stripped from absolute paths (eg, turning /x/y/z into x/y/z), paths containing .. are not extracted, and any file whose location would be modified by a symbolic link is not extracted.

WARNING This is almost always unsafe, and must NEVER be used on archives from untrusted sources, such as user input, and every entry must be validated to ensure it is safe to write. Even if the input is not malicious, mistakes can cause a lot of damage!

When setting the TarOptions#chmod option to true, you may provide a value here to avoid having to call the deprecated and thread-unsafe process.umask() method.

This has no effect with chmod is not set to true, as mode values are not set explicitly anyway. If chmod is set to true, and a value is not provided here, then process.umask() must be called, which will result in deprecation warnings.

The most common values for this are 0o22 (resulting in directories created with mode 0o755 and files with 0o644 by default) and 0o2 (resulting in directores created with mode 0o775 and files 0o664, so they are group-writable).

A map object containing the results of fs.readdir() calls.

A cache of all lstat results, for use in creating archives.

Treat warnings as crash-worthy errors. Defaults false.

When extracting, strip the specified number of path portions from the entry path. For example, with {strip: 2}, the entry a/b/c/d would be extracted to {cwd}/c/d.

Any entry whose entire path is stripped will be excluded.

Perform all I/O operations synchronously. If the stream is ended immediately, then it will be processed entirely synchronously.

When extracting, provide a function that takes an entry object, and returns a stream, or any falsey value. If a stream is provided, then that stream's data will be written instead of the contents of the archive entry. If a falsey value is provided, then the entry is written to disk as normal.

To exclude items from extraction, use the filter option.

Note that using an asynchronous stream type with the transform option will cause undefined behavior in synchronous extractions. MiniPass-based streams are designed for this use case.

When extracting, force all created files and directories, and all implicitly created directories, to be owned by the specified user id, regardless of the uid field in the archive.

Cannot be used along with preserveOwner. Requires also setting the gid option.

Filter modes of entries being unpacked, like process.umask()

When extracting, unlink files before creating them. Without this option, tar overwrites existing files, which preserves existing hardlinks. With this option, existing hardlinks will be broken, as will any symlink that would affect the location of an extracted file.

Automatically set to true on Windows systems.

When extracting, causes behavior where filenames containing <|>?: characters are converted to windows-compatible escape sequences in the created filesystem entries.

When packing, causes behavior where paths replace \ with /, and filenames containing the windows-compatible escaped forms of <|>?: are converted to actual <|>?: characters in the archive.

Set to true or an object with settings for zstd.compress() to create a zstd-compressed archive

When extracting, this will cause the archive to be treated as a zstd-compressed file if set to true or a ZlibOptions object.

If set false, then zstd options will not be used.

If this, the gzip, and brotli options are left undefined, then tar will attempt to infer the zstd compression status, but can only do so based on the filename. If the filename ends in .tzst or .tar.zst, and the first 512 bytes are not a valid tar header, then zstd decompression will be attempted.