@iarna/tar
v1.0.2
Published
A simple tar CLI based on node-tar -- highly compatible, very fast, can produce idempotent tar outputs when using "portable" mode. Intended for use in environments without a tar binary (ie, Windows), particularly for portable package.json run scripts.
Downloads
5
Readme
@iarna/tar
A simple tar CLI based on node-tar -- highly compatible, very fast, can produce idempotent tar outputs when using "portable" mode.
Intended for use in environments without a tar binary (ie, Windows), particularly for portable package.json run scripts.
USAGE
Commands:
npx @iarna/tar@1 create <files...> Create a tarball archive.
The files are a list of paths to add to the
tarball. Adding a directory also adds its
children recursively.
An entry in files that starts with an @ symbol is
a tar archive whose entries will be added. To add
a file that starts with @, prepend it with ./
[aliases: c]
npx @iarna/tar@1 extract [files...] Extract a tarball archive.
The files are a list of paths to extract from the
tarball. If no paths are provided, then all the
entries are extracted. An entry in files that
starts with an @ symbol is a tar archive whose
entries will be added. To add a file that starts
with @, prepend it with ./
If the archive is gzipped, then tar will detect
this and unzip it.
Note that all directories that are created will
be forced to be writable, readable, and listable
by their owner, to avoid cases where a directory
prevents extraction of child entries by virtue of
its mode.
Most extraction errors will cause a warn event to
be emitted. If the cwd is missing, or not a
directory, then the extraction will fail
completely. [aliases: x]
npx @iarna/tar@1 list [files...] List the contents of a tarball archive.
The files are a list of paths to list from the
tarball. If no paths are provided, then all the
entries are listed. If the archive is gzipped,
then tar will detect this and unzip it.
This is a thin wrapper around node-tar -- basically just the docs converted into yargs options so you can use it as a cli. A few extra aliases to match GNU tar.
npx @iarna/tar@1 create [options] <files...>
Create a tarball archive.
The files are a list of paths to add to the tarball. Adding a directory also
adds its children recursively.
An entry in files that starts with an @ symbol is a tar archive whose entries
will be added. To add a file that starts with @, prepend it with ./
Options:
--version Show version number [boolean]
--help Show help [boolean]
-v, --verbose [boolean]
-f, --file Write the tarball archive to the
specified filename. If not specified
then it is written to STDOUT. [string]
--strict Treat warnings as crash-worthy errors.
[boolean] [default: false]
-C, --cwd, --directory The current working directory for
creating the archive.
[string] [default: "/mnt/c/code/iarna-tar"]
--prefix A path portion to prefix onto the
entries in the archive. [string]
-z, --gzip Compress the archive with gzip
[boolean] [default: "false"]
--portable Omit 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. Additionally, mode is set
to a "reasonable default" for most
unix systems, based on a umask value
of 0o22. [boolean]
-P, --preserve-paths, --absolute-names Allow absolute paths. By default, / is
stripped from absolute paths.[boolean]
--mode The mode to set on the created file
archive [string]
--recursion Recursively archive the contents of
directories. Disable with
--no-recursion
[boolean] [default: "true"]
-L, -h, --dereference Set to true to pack the targets of
symbolic links. Without this option,
symbolic links are archived as such.
[boolean]
--pax Suppress pax extended headers. Note
that this means that long paths and
linkpaths will be truncated, and large
or negative numeric values may be
interpreted incorrectly.
[boolean] [default: true]
-m, --no-mtime Set to true to omit writing mtime
values for entries. Note that this
prevents using other mtime-based
features like tar.update or the
keepNewer option with the resulting
tar archive.[boolean] [default: false]
--mtime Set to a date to force a specific
mtime for everything added to the
archive. Overriden by --no-mtime.
String should be a valid argument for
the Date object constructor. [string]npx @iarna/tar@1 extract [options] <files...>
Extract a tarball archive.
The files are a list of paths to extract from the tarball. If no paths are
provided, then all the entries are extracted. An entry in files that starts with
an @ symbol is a tar archive whose entries will be added. To add a file that
starts with @, prepend it with ./
If the archive is gzipped, then tar will detect this and unzip it.
Note that all directories that are created will be forced to be writable,
readable, and listable by their owner, to avoid cases where a directory prevents
extraction of child entries by virtue of its mode.
Most extraction errors will cause a warn event to be emitted. If the cwd is
missing, or not a directory, then the extraction will fail completely.
Options:
--version Show version number [boolean]
--help Show help [boolean]
-v, --verbose [boolean]
-C, --cwd, --directory Extract files relative to the
specified directory.
[string] [default: "/mnt/c/code/iarna-tar"]
-f, --file The archive file to extract. If not
specified one is read from STDIN.
[string]
--strict Treat warnings as crash-worthy
errors. [boolean] [default: false]
--newer, --keep-newer, Set to true to keep the existing
--keep-newer-files file on disk if it's newer than the
file in the archive [boolean]
-k, --keep, --keep-existing Do not overwrite existing files. In
particular, if a file appears more
than once in an archive, later
copies will not overwrite earlier
copies. [boolean]
-P, --preserve-paths Allow absolute paths, paths
containing .., and extracting
through symbolic links. By default,
/ is stripped from absolute paths,
.. paths are not extracted, and any
file whose location would be
modified by a symbolic link is not
extracted. [boolean]
-U, --unlink, --unlink-first 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. [boolean]
--strip, --strip-components, Remove the specified number of
--stripComponents leading path elements. Pathnames
with fewer elements will be silently
skipped. Note that the pathname is
edited after applying the filter,
but before security checks. [
[boolean]
-p, --preserve-owner If true, tar will set the uid and
gid of extracted entries to the uid
and gid fields in the archive. This
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.
[boolean]
--uid Set to a number to force ownership
of all extracted files and folders,
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 a gid option.
[number]
--gid Set to a number to force ownership
of all extracted files and folders,
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 a uid option.
[number]
-m, --no-mtime Set to true to omit writing mtime
value for extracted entries.
[boolean]
--no-chmod Set to true to omit calling
fs.chmod() to ensure that the
extracted file matches the entry
mode. This also suppresses the call
to process.umask() to determine the
default umask value, since tar will
extract with whatever mode is
provided, and let the process umask
apply normally. [boolean]npx @iarna/tar@1 list [options] <files...>
List the contents of a tarball archive.
The files are a list of paths to list from the tarball. If no paths are
provided, then all the entries are listed. If the archive is gzipped, then tar
will detect this and unzip it.
Options:
--version Show version number [boolean]
--help Show help [boolean]
-C, --cwd, --directory Extract files relative to the specified directory.
[string] [default: "/mnt/c/code/iarna-tar"]
-f, --file The archive file to list. If not specified, then the
file is read from STDIN. [string]
--strict Treat warnings as crash-worthy errors.
[boolean] [default: false]