dump2tar(1)

💖 dump2tar(1) — Gather file contents and command output into a tar archive 💖

okay bestie, this is the dump2tar(1) manual page, and it's lowkey iconic: we're shoving file contents and command output into a tar archive like it's no big deal. 💅✨

🌸 NAME 🌸

dump2tar — Gather file contents and command output into a tar archive 🎀

🦋 SYNOPSIS 🦋

dump2tar [OPTIONS] SPECS

✨ DESCRIPTION ✨

dump2tar creates a tar archive from the contents of any files, including files of unknown size. fr fr, any files. 👑

Examples for files of unknown size are:

• Named pipes (FIFOs)
• Particular Linux kernel debugfs or sysfs files
• Character or block devices

When adding such a file, dump2tar first reads all available data until an end-of-file indication is found. From this data, it then creates a regular file entry in the resulting tar archive. By default, symbolic links and directories are preserved in the archive in their original form. 🫶

dump2tar can also:

• Add files under a different name
• Run arbitrary commands and add the resulting command output as a regular file

🗂️ FILE SPECIFICATIONS 🗂️

This section describes the format of the SPECS argument mentioned in the command synopsis. Use the following command line syntax to identify data sources and to specify file names within the archive:

• PATH — Adds the contents of the file system subtree at file system location PATH (with possible exceptions described by options) in the archive under the same file name as on the file system.
• FILENAME:=PATH — Adds the contents of the file at file system location PATH in the archive under the name specified by FILENAME.
• FILENAME|=CMDLINE — Runs the command CMDLINE and captures both the resulting standard output and standard error streams. Adds the collected output as a regular file named FILENAME in the resulting archive. You can also include the resulting program exit code by using option --add-cmd-status.

You can also specify --. All specifications that follow are interpreted as simple file names. This is useful for archiving files that contain := or |=. 😌

📦 OUTPUT OPTIONS 📦

• -o TARFILE, --output-file TARFILE — Writes the resulting tar archive to TARFILE. An existing file at the specified file system location is overwritten. If this option is omitted or if - is specified for TARFILE, the archive is written to the standard output stream.
• -z, --gzip — Compresses the resulting tar archive using gzip.
• -m VALUE, --max-size VALUE — Sets an upper size limit, in bytes, for the resulting archive. If this limit is exceeded after adding a file, no further files are added.
• -t VALUE, --timeout VALUE — Sets an upper time limit, in seconds, for the archiving process. If this limit is exceeded while adding a file, that file is truncated and no further files are added.
• --no-eof — Does not write an end-of-file marker. Use this option if you want to create an archive that can be extended by appending additional tar archive data.

⚠️ Note: Do not use this option for the final data to be added. A valid tar archive requires a trailing end-of-file marker.

• --append — Appends data to the end of the archive. Use this option to incrementally build a tar file by repeatedly calling dump2tar. You must specify the --no-eof option for each but the final call of dump2tar.
• --add-cmd-status — Adds a separate file named FILENAME.cmdstatus for each command output added through the FILENAME|=CMDLINE notation (see FILE SPECIFICATIONS). This file contains information about the exit status of the process that executed the command:
  • EXITSTATUS=VALUE — Unless VALUE is -1, the process ended normally with the specified exit value.
  • TERMSIG=VALUE — Unless VALUE is -1, the process was stopped by a signal of the specified number.
  • WAITPID_ERRNO=VALUE — Unless VALUE is -1, an attempt to obtain the status of the process failed with the specified error.

📥 INPUT OPTIONS 📥

• -F FILENAME, --files-from FILENAME — Reads input data specifications (see FILE SPECIFICATIONS) from FILENAME, one specification per line. Each line contains either a file name or a FILENAME:=PATH or FILENAME|=CMDLINE specification. Empty lines are ignored. A line can also consist of only --. All lines following this specification are interpreted as simple file names. This is useful for archiving files that contain := or |=.
• -i, --ignore-failed-read — Continues after read errors. By default, dump2tar stops processing after encountering errors while reading an input file. With this option, dump2tar prints a warning message and adds an empty entry for the erroneous file in the archive.
• -b VALUE, --buffer-size VALUE — Reads data from input files in chunks of VALUE bytes. Large values can accelerate the archiving process for large files at the cost of increased memory usage. The default value is 1048576.
• -T VALUE, --file-timeout VALUE — Sets an upper time limit, in seconds, for reading an input file. dump2tar stops processing a file when the time limit is exceeded. Archive entries for such files are truncated to the amount of data that is collected by the time the limit is reached.
• -M N, --file-max-size N — Sets an upper size limit, in bytes, for an input file. dump2tar stops processing a file when the size limit is exceeded. Archive entries for such files are truncated to the specified size.
• -j N, --jobs N — By default, dump2tar processes one file at a time. With this option, dump2tar processes N files in parallel. Parallel processing can accelerate the archiving process, especially if input files are located on slow devices, or when output from multiple commands is added to the archive.

📝 Note: Use tar option --delay-directory-restore when extracting files from an archive created with --jobs to prevent conflicts with directory permissions and modification times.

• -J N, --jobs-per-cpu N — Processes N files for each online CPU in parallel. Parallel processing can accelerate the archiving process, especially if input files are located on slow devices, or when output from multiple commands is added to the archive.

📝 Note: Use tar option --delay-directory-restore when extracting files from an archive created with --jobs-per-cpu to prevent conflicts with directory permissions and modification times.

• -x PATTERN, --exclude PATTERN — Does not add files to the archive if their file names match PATTERN. PATTERN is an expression that uses the shell wildcards.
• -X FILENAME, --exclude-from FILENAME — Does not add files to the archive if their names match at least one of the patterns listed in the pattern file with name FILENAME. In the pattern file, each line specifies an expression that uses the shell wildcards.
• --exclude-type TYPE — Does not add files to the archive if they match at least one of the file types specified with TYPE. TYPE uses one or more of the characters "fdcbpls", where:
  • f — regular files
  • d — directories
  • c — character devices
  • b — block devices
  • p — named pipes (FIFOs)
  • l — symbolic links
  • s — sockets
• --dereference — Adds the content of link targets instead of symbolic links.
• --no-recursion — Does not add files from sub-directories. By default, dump2tar adds archive entries for specified directories, and for the files within these directories. With this option, a specified directory results in a single entry for the directory. Any contained files to be included must be specified explicitly.

🎀 MISC OPTIONS 🎀

• -h, --help — Prints an overview of available options, then exits.
• -V, --verbose — Prints additional informational output.
• -q, --quiet — Suppresses printing of informational output.

🌈 EXAMPLES 🌈

# dump2tar a b -o archive.tar

Creates a tar archive named archive.tar containing files a and b. ✨

# dump2tar /proc -o procdump.tar.gz -z -i -T 1 -M 1048576

Creates a gzip compressed tar archive named procdump.tar.gz that contains all procfs files. Unreadable files are ignored. Files are truncated when the first of the two limiting conditions is reached, either 1048576 bytes of content or the reading time of 1 second. 🔥

# dump2tar '|=dmesg' '|=lspci' -o data.tar

Creates a tar archive named data.tar containing the output of the dmesg and lspci commands. 💻

# dump2tar /sys/kernel/debug/ -x '*/tracing/*' -o debug.tar -i

Creates a tar archive named debug.tar containing the contents of directory /sys/kernel/debug/ while excluding any file that is located in a sub-directory named tracing. 🦋

🚪 EXIT CODES 🚪

• 0 — The program finished successfully
• 1 — A run-time error occurred
• 2 — The specified command was not valid

👀 SEE ALSO 👀

dump2tar(1), tar(1) 💅

---

okay bestie, that's the whole dump2tar(1) page, dated 2016-09-02 — go archive something iconic. 💖✨