# bsdtar from libarchive is the default for macOS and Windows
# in Linux
alias tar='command bsdtar'

# find out what kind of tarball it is
file archive.tar
     POSIX tar archive
     POSIX tar archive (GNU)

# most common usage
## create tar; add -a before f for compression
bsdtar -cf a.tar -C srcdir file1 file2 dir1 ...
## list tarball
bsdtar -tvf a.tar ["patterns"]
## extract tarball
bsdtar -xvf a.tar ["patterns"] -C destdir

# use --uid 0 --gid 0 to remove owner information
bsdtar -cf archive.tar --uid 0 --gid 0 files dirs

# move files: -p preserve permission
bsdtar -cf - -C srcdir . | bsdtar -xpf - -C destdir

# synopsis
     tar {-c} [options]	[files | directories]
     tar {-r | -u} -f archive-file [options] [files | directories]
     tar {-t | -x} [options] [patterns]

# modes
-c	create archive, --create
-t	list contents, --list
-x	extract, --extract
-r	append only works for uncompressed tar, --apend
-u	update, only works for uncompressed tar, --update

# options
-a	auto compress based on suffix; c mode only
-z	gzip
-J	bzip2
--zstd	

-v	verbose
-w	--interactive
-f	file name

--exclude pattern
--include pattern

-C	--cd, change to dir before adding/extracting files
-T filename    --files-from, read list of names

--uid id	use provide user id; if --uname is not provided, use the name to match the id
--gid id	provide group id, 0 for root

--uname name	sets user name, the name is not verified
--gname name	provide group name

-k	keep old files; x mode only
-L	--dereference, target of symlink will be archived
-n	--norecurse, do not operate recursively on dir

--no-same-owner	x mode only, default behavior if run as non-root
--same-owner	x mode only, extract owner and group ID, default if run as root

--numeric-owner	use UID and GID rather than username or group name. on create, do not store names
-O	x: extract to std out; t: to stderr
--options options
	key=vlue
	zstd:compression-level
-P	--absolute-paths; preserve pathnames including /

-p	--preserve-permissions, x mode only, default if tar is run as root
--no-same-permissions	xmode only, default behavior if run as non-root

tar cvfJ files.tar.xz dir1 dir2 file3
tar xvfJ files.tar.xz -C /specific/path/ etc/foo.txt # extract single file to specific path
tar tvfJ files.tar.xz # list files inside of tarball

bzcat file.tar.bz2 | zstd > file.tar.zst # convert from bz2 to zstd
# similarly, zstdcat, xzcat

tar --zstd cvf file.tar.zst dir #zstd
tar c -I'zstd -19 -T0' vf file.tar.zst dir1 dir2
tar cvf - dir | zstd -19 -T0 > file.tar.zst

c	create an archive
f   filename	the name of the archive file
t	table of contents: tell me what's in an archive
v	verbose: tell me what's going on
x	extract from an archive
z	compress through gzip
j compress through bzip2 - bz2 extension
J compress through xz
a automatic compress and decompress based on extension # tar axf
tar --delete tar/file file # delete a file from tar
r # add new file to tar
u # update a file inside tar - does NOT work with compressed file

###
First option must be a mode specifier:
  c Create  r Add/Replace  t List  u Update  x Extract
Common Options:
  b #  Use # 512-byte records per I/O block
  f <filename>  Location of archive (default \\.\tape0)
  v    Verbose
  w    Interactive
Create: tar c [options] [<file> | <dir> | @<archive> | -C <dir> ]
  <file>, <dir>  add these items to archive
  z, j, J, --lzma  Compress archive with gzip/bzip2/xz/lzma
  --format {ustar|pax|cpio|shar}  Select archive format
  --exclude <pattern>  Skip files that match pattern
  -C <dir>  Change to <dir> before processing remaining files
  @<archive>  Add entries from <archive> to output
List: tar t [options] [<patterns>]
  <patterns>  If specified, list only entries that match
Extract: tar x [options] [<patterns>]
  <patterns>  If specified, extract only entries that match
  k    Keep (don't overwrite) existing files
  m    Don't restore modification times
  -O    Write entries to stdout, don't restore to disk
  p    Restore permissions (including ACLs, owner, file flags)