mtar

README

mtar

mtar is a simple-ish tool for creating tar files with arbitrary src-to-archive path mappings and regexp filters.

You can download and install mtar using the go tool by running

$ go get -u go.spiff.io/mtar

Usage text can be read at https://godoc.org/go.spiff.io/mtar or by running mtar -h.

LICENSE

mtar is licensed under the BSD two-clause license. This is readable at the top of its source file(s) and in the LICENSE.txt file.

Documentation

Overview

Mtar is a simple tar program to create tar files with arbitrary path mappings from the source filesystem to tar paths. It only supports regular files, directories, and symlinks.

Download and install with

go get -u go.spiff.io/mtar

Usage:

mtar [-h|--help] [FILE|OPTION]

Writes a tar file to standard output.

FILE may be a filepath for a file, symlink, or directory. If FILE
contains a ':', the text after the colon is the path to write to the tar
file. For example, the following paths behave differently:

  SRC
      Add file SRC to the tar file as-is.
  SRC:
      Add file SRC to the tar file as-is.
  SRC:DEST
      Add file SRC as DEST to the tar file.

To read a file from standard input, you can set '-' as the SRC. If no
DEST is given for this, it will default to dev/stdin (relative). File
permissions and ownership are taken from fd 1, so overriding them may be
necessary. If the link or dir option is set, - can be used to synthesize
a file entry.

In the case of SRC: and SRC:DEST, you can also pass an additional :OPTS
with either (i.e., SRC::OPTS or SRC:DEST:OPTS), where FLAGS are
comma-separated strings that set options. The following options are
available (all option names are case-sensitive):

  norec
    For directory entries, do not recursively add files from the
    directory. This will cause only the directory itself to appear as
    an entry.
  dir
    Force file to become a dir entry. Implies norec.
  link=LINK
    Force file to become a symlink pointing to LINK.
  ref=LINK
    Force file to become a hard link pointing to LINK.
  nouser
    Strip user information from the file.
  uid=UID | owner=USERNAME
    Set the owner's uid and/or username for the file entry.
  gid=GID | group=GROUPNAME
    Set the gid and/or the group name for the file entry.
  mode=MODE
    Set the file mode to MODE (may be hex, octal, or an integer -- octal
    must begin with a 0, hex with 0x).
  mtime=TIME | atime=TIME | ctime=TIME
    Sets the mod time, access time, or changed time to TIME. May be an
    RFC3339 timestamp or an integer timestamp (since the Unix epoch) in
    seconds, milliseconds (>=12 digits), or microseconds (>=15 digits).

Any whitespace preceding an option is trimmed. Whitespace is not trimmed
before or after the '=' symbol for options that take values. Commas are
not currently permitted inside options.

In addition, options may be passed in the middle of file arguments to
control archive creation:

  -h | --help
    When passed as the first argument, print this usage text.
  -D
    Prevent duplicate entries with the same name. (default)
  -d
    Allow duplicate entries with the same name.
  -U
    Do not assign user information to files.
  -u
    Assign user information to files. (default)
  -Fformat | -F format
    Set the tar header format to use. May be one of the following
    formats:
      * 'pax', '2001', 'posix.1-2001' (default)
        Modern POSIX tar format.
      * 'ustar', '1988', 'posix.1-1988'
        The tar format written by most tar programs by default.
        Does not support files over 8GiB.
      * 'gnu'
        A format specific to GNU tar archives.
        Should not be chosen unless absolutely required.
  -Cdir | -C dir
    Change to directory (relative to PWD at all times; -C. will reset
    the current directory) for subsequent file additions.
  -OREGEX | -O REGEX
    Add a filter to reject output paths, after mapping, that do not
    match the REGEX.
  -oREGEX | -o REGEX
    Select only output paths, after mapping, that match the REGEX.
  -IREGEX | -I REGEX
    Add a filter to reject input paths (as passed) that match the REGEX.
  -iREGEX | -i REGEX
    Add a filter to select only input paths that match the REGEX.
  -Ri, -Ro, -R
    Reset input, output, or all filters, respectively.
  -A
    Read one or more tar streams from standard input and concatenate them
    to the output.