@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

1Commands:
2  npx @iarna/tar@1 create <files...>   Create a tarball archive.
3
4                               The files are a list of paths to add to the
5                               tarball. Adding a directory also adds its
6                               children recursively.
7
8                               An entry in files that starts with an @ symbol is
9                               a tar archive whose entries will be added. To add
10                               a file that starts with @, prepend it with ./
11                                                                    [aliases: c]
12  npx @iarna/tar@1 extract [files...]  Extract a tarball archive.
13
14                               The files are a list of paths to extract from the
15                               tarball. If no paths are provided, then all the
16                               entries are extracted. An entry in files that
17                               starts with an @ symbol is a tar archive whose
18                               entries will be added. To add a file that starts
19                               with @, prepend it with ./
20
21                               If the archive is gzipped, then tar will detect
22                               this and unzip it.
23
24                               Note that all directories that are created will
25                               be forced to be writable, readable, and listable
26                               by their owner, to avoid cases where a directory
27                               prevents extraction of child entries by virtue of
28                               its mode.
29
30                               Most extraction errors will cause a warn event to
31                               be emitted. If the cwd is missing, or not a
32                               directory, then the extraction will fail
33                               completely.                          [aliases: x]
34  npx @iarna/tar@1 list [files...]     List the contents of a tarball archive.
35
36                               The files are a list of paths to list from the
37                               tarball. If no paths are provided, then all the
38                               entries are listed. If the archive is gzipped,
39                               then tar will detect this and unzip it.
40

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...>

1Create a tarball archive.
2
3The files are a list of paths to add to the tarball. Adding a directory also
4adds its children recursively.
5
6An entry in files that starts with an @ symbol is a tar archive whose entries
7will be added. To add a file that starts with @, prepend it with ./
8
9Options:
10      --version                           Show version number          [boolean]
11      --help                              Show help                    [boolean]
12  -v, --verbose                                                        [boolean]
13  -f, --file                              Write the tarball archive to the
14                                          specified filename. If not specified
15                                          then it is written to STDOUT. [string]
16      --strict                            Treat warnings as crash-worthy errors.
17                                                      [boolean] [default: false]
18  -C, --cwd, --directory                  The current working directory for
19                                          creating the archive.
20                                     [string] [default: "/mnt/c/code/iarna-tar"]
21      --prefix                            A path portion to prefix onto the
22                                          entries in the archive.       [string]
23  -z, --gzip                              Compress the archive with gzip
24                                                    [boolean] [default: "false"]
25      --portable                          Omit metadata that is system-specific:
26                                          ctime, atime, uid, gid, uname, gname,
27                                          dev, ino, and nlink. Note that mtime
28                                          is still included, because this is
29                                          necessary for other time-based
30                                          operations. Additionally, mode is set
31                                          to a "reasonable default" for most
32                                          unix systems, based on a umask value
33                                          of 0o22.                     [boolean]
34  -P, --preserve-paths, --absolute-names  Allow absolute paths. By default, / is
35                                          stripped from absolute paths.[boolean]
36      --mode                              The mode to set on the created file
37                                          archive                       [string]
38      --recursion                         Recursively archive the contents of
39                                          directories. Disable with
40                                          --no-recursion
41                                                     [boolean] [default: "true"]
42  -L, -h, --dereference                   Set to true to pack the targets of
43                                          symbolic links. Without this option,
44                                          symbolic links are archived as such.
45                                                                       [boolean]
46      --pax                               Suppress pax extended headers. Note
47                                          that this means that long paths and
48                                          linkpaths will be truncated, and large
49                                          or negative numeric values may be
50                                          interpreted incorrectly.
51                                                       [boolean] [default: true]
52  -m, --no-mtime                          Set to true to omit writing mtime
53                                          values for entries. Note that this
54                                          prevents using other mtime-based
55                                          features like tar.update or the
56                                          keepNewer option with the resulting
57                                          tar archive.[boolean] [default: false]
58      --mtime                             Set to a date to force a specific
59                                          mtime for everything added to the
60                                          archive. Overriden by --no-mtime.
61                                          String should be a valid argument for
62                                          the Date object constructor.  [string]

npx @iarna/tar@1 extract [options] <files...>

1Extract a tarball archive.
2
3The files are a list of paths to extract from the tarball. If no paths are
4provided, then all the entries are extracted. An entry in files that starts with
5an @ symbol is a tar archive whose entries will be added. To add a file that
6starts with @, prepend it with ./
7
8If the archive is gzipped, then tar will detect this and unzip it.
9
10Note that all directories that are created will be forced to be writable,
11readable, and listable by their owner, to avoid cases where a directory prevents
12extraction of child entries by virtue of its mode.
13
14Most extraction errors will cause a warn event to be emitted. If the cwd is
15missing, or not a directory, then the extraction will fail completely.
16
17Options:
18      --version                             Show version number        [boolean]
19      --help                                Show help                  [boolean]
20  -v, --verbose                                                        [boolean]
21  -C, --cwd, --directory                    Extract files relative to the
22                                            specified directory.
23                                     [string] [default: "/mnt/c/code/iarna-tar"]
24  -f, --file                                The archive file to extract. If not
25                                            specified one is read from STDIN.
26                                                                        [string]
27      --strict                              Treat warnings as crash-worthy
28                                            errors.   [boolean] [default: false]
29      --newer, --keep-newer,                Set to true to keep the existing
30      --keep-newer-files                    file on disk if it's newer than the
31                                            file in the archive        [boolean]
32  -k, --keep, --keep-existing               Do not overwrite existing files. In
33                                            particular, if a file appears more
34                                            than once in an archive, later
35                                            copies will not overwrite earlier
36                                            copies.                    [boolean]
37  -P, --preserve-paths                      Allow absolute paths, paths
38                                            containing .., and extracting
39                                            through symbolic links. By default,
40                                            / is stripped from absolute paths,
41                                            .. paths are not extracted, and any
42                                            file whose location would be
43                                            modified by a symbolic link is not
44                                            extracted.                 [boolean]
45  -U, --unlink, --unlink-first              Unlink files before creating them.
46                                            Without this option, tar overwrites
47                                            existing files, which preserves
48                                            existing hardlinks. With this
49                                            option, existing hardlinks will be
50                                            broken, as will any symlink that
51                                            would affect the location of an
52                                            extracted file.            [boolean]
53      --strip, --strip-components,          Remove the specified number of
54      --stripComponents                     leading path elements. Pathnames
55                                            with fewer elements will be silently
56                                            skipped. Note that the pathname is
57                                            edited after applying the filter,
58                                            but before security checks. [
59                                                                       [boolean]
60  -p, --preserve-owner                      If true, tar will set the uid and
61                                            gid of extracted entries to the uid
62                                            and gid fields in the archive. This
63                                            defaults to true when run as root,
64                                            and false otherwise. If false, then
65                                            files and directories will be set
66                                            with the owner and group of the user
67                                            running the process. This is similar
68                                            to -p in tar(1), but ACLs and other
69                                            system-specific data is never
70                                            unpacked in this implementation, and
71                                            modes are set by default already.
72                                                                       [boolean]
73      --uid                                 Set to a number to force ownership
74                                            of all extracted files and folders,
75                                            and all implicitly created
76                                            directories, to be owned by the
77                                            specified user id, regardless of the
78                                            uid field in the archive. Cannot be
79                                            used along with preserveOwner.
80                                            Requires also setting a gid option.
81                                                                        [number]
82      --gid                                 Set to a number to force ownership
83                                            of all extracted files and folders,
84                                            and all implicitly created
85                                            directories, to be owned by the
86                                            specified group id, regardless of
87                                            the gid field in the archive. Cannot
88                                            be used along with preserveOwner.
89                                            Requires also setting a uid option.
90                                                                        [number]
91  -m, --no-mtime                            Set to true to omit writing mtime
92                                            value for extracted entries.
93                                                                       [boolean]
94      --no-chmod                            Set to true to omit calling
95                                            fs.chmod() to ensure that the
96                                            extracted file matches the entry
97                                            mode. This also suppresses the call
98                                            to process.umask() to determine the
99                                            default umask value, since tar will
100                                            extract with whatever mode is
101                                            provided, and let the process umask
102                                            apply normally.            [boolean]

npx @iarna/tar@1 list [options] <files...>

1List the contents of a tarball archive.
2
3The files are a list of paths to list from the tarball. If no paths are
4provided, then all the entries are listed. If the archive is gzipped, then tar
5will detect this and unzip it.
6
7Options:
8      --version           Show version number                          [boolean]
9      --help              Show help                                    [boolean]
10  -C, --cwd, --directory  Extract files relative to the specified directory.
11                                     [string] [default: "/mnt/c/code/iarna-tar"]
12  -f, --file              The archive file to list. If not specified, then the
13                          file is read from STDIN.                      [string]
14      --strict            Treat warnings as crash-worthy errors.
15                                                      [boolean] [default: false]