--- /dev/null
+.TH WIMCAPTURE "1" "August 2016" "wimlib 1.10.0" "User Commands"
+.SH NAME
+wimcapture, wimappend \- Capture or append a WIM image
+.SH SYNOPSIS
+\fBwimcapture\fR \fISOURCE\fR \fIWIMFILE\fR [\fIIMAGE_NAME\fR \ [\fIIMAGE_DESC\fR]] [\fIOPTION\fR...]
+.br
+\fBwimappend\fR \fISOURCE\fR \fIWIMFILE\fR [\fIIMAGE_NAME\fR \ [\fIIMAGE_DESC\fR]] [\fIOPTION\fR...]
+.SH DESCRIPTION
+The \fBwimcapture\fR (equivalently: \fBwimlib-imagex capture\fR) and
+\fBwimappend\fR (equivalently: \fBwimlib-imagex append\fR) commands create
+("capture") a new Windows Imaging (WIM) image. \fBwimcapture\fR creates a new
+WIM archive \fIWIMFILE\fR to contain the new image, while \fBwimappend\fR adds
+the image to the existing WIM archive \fIWIMFILE\fR.
+.PP
+\fISOURCE\fR specifies the location of the files from which to create the WIM
+image. If \fISOURCE\fR is a directory or a symbolic link pointing to a
+directory, then the image is captured from that directory as per \fBDIRECTORY
+CAPTURE (UNIX)\fR or \fBDIRECTORY CAPTURE (WINDOWS)\fR. Alternatively, if
+\fB--source-list\fR is specified, then \fISOURCE\fR is interpreted as a file
+containing a list of files and directories to include in the image. Still
+alternatively, if \fISOURCE\fR is a UNIX block device, then an image is captured
+from the NTFS volume on it as per \fBNTFS VOLUME CAPTURE (UNIX)\fR.
+.PP
+\fIIMAGE_NAME\fR and \fIIMAGE_DESC\fR specify the name and description to give
+the new image. If \fIIMAGE_NAME\fR is unspecified, it defaults to the filename
+component of \fISOURCE\fR, appending a unique suffix if needed. Otherwise,
+\fIIMAGE_NAME\fR must be either a name not already used by an image in
+\fIWIMFILE\fR, or the empty string to create an unnamed image. If
+\fIIMAGE_DESC\fR is unspecified then the new image is given no description.
+.PP
+If \fIWIMFILE\fR is specified as "-", then the \fB--pipable\fR option is assumed
+and a pipable WIM is written to standard output (this is a wimlib extension).
+.SH DIRECTORY CAPTURE (UNIX)
+On UNIX-like systems, if \fISOURCE\fR specifies a directory or a symbolic link
+to a directory, then the WIM image will be captured from that directory. The
+directory can be on any type of filesystem, and mountpoints are followed. In
+this mode, the following types of information are captured:
+.IP \[bu] 4
+Directories and regular files, and the contents of regular files
+.IP \[bu]
+Hard links
+.IP \[bu]
+Symbolic links (translated losslessly to Windows reparse points)
+.IP \[bu]
+Last modification times (mtime) and last access times (atime) with 100
+nanosecond granularity
+.IP \[bu]
+Files that appear to be sparse will be flagged as such, but their full data will
+still be stored, subject to the usual compression.
+.IP \[bu]
+With \fB--unix-data\fR: standard UNIX file permissions (owner, group, and mode)
+.IP \[bu]
+With \fB--unix-data\fR: device nodes, named pipes, and sockets
+.IP \[bu]
+With \fB--unix-data\fR: extended attributes (Linux only)
+.PP
+There is no support for storing last status change times (ctimes), or hard link
+information for symlinks (each symlink will be stored as a separate file).
+Also, filenames and symlink targets which are not valid UTF-8 with the addition
+of surrogate codepoints are unsupported. Note that if you have a filesystem
+containing filenames in another multibyte encoding, such as ISO-8859-1, and you
+wish to archive it with wimlib, you may be able to mount it with an option which
+causes its filenames to be presented as UTF-8.
+.SH NTFS VOLUME CAPTURE (UNIX)
+On UNIX-like systems, \fISOURCE\fR may also be specified as a block device (e.g.
+/dev/sda3) containing an unmounted NTFS volume. In this mode, \fBwimcapture\fR
+uses libntfs-3g to capture a WIM image from root directory of the NTFS volume.
+In this mode, as much data and metadata as possible is captured, including
+NTFS-specific and Windows-specific metadata:
+.IP \[bu] 4
+All data streams of all unencrypted files, including the unnamed data stream as
+well as all named data streams.
+.IP \[bu]
+Reparse points. See \fBREPARSE POINTS AND SYMLINKS\fR for details.
+.IP \[bu]
+File and directory creation, access, and modification timestamps, using the
+native NTFS resolution of 100 nanoseconds.
+.IP \[bu]
+Windows security descriptors, including all components (owner, group, DACL, and
+SACL).
+.IP \[bu]
+DOS/Windows file attribute flags.
+.IP \[bu]
+All names of all files, including names in the Win32 namespace, DOS namespace,
+Win32+DOS namespace, and POSIX namespace. This includes hard links.
+.IP \[bu]
+Object IDs.
+.PP
+However, the main limitations of this mode are:
+.IP \[bu] 4
+Encrypted files are excluded.
+.IP \[bu]
+Sparse files will be flagged as such, but their full data will still be stored,
+subject to the usual compression.
+.IP \[bu]
+Some types of reparse points are transparently dereferenced by Windows but not
+by NTFS-3G. See \fBREPARSE POINTS AND SYMLINKS\fR.
+.PP
+Note that this mode uses libntfs-3g directly, without going through the
+\fBntfs-3g\fR(8) driver. Hence, there is no special support for capturing a WIM
+image from a directory on which an NTFS filesystem has been mounted using
+\fBntfs-3g\fR(8); you have to unmount it first. There is also no support for
+capturing a subdirectory of the NTFS volume; you can only capture the full
+volume.
+.SH DIRECTORY CAPTURE (WINDOWS)
+On Windows, \fBwimcapture\fR and \fBwimappend\fR natively support
+Windows-specific and NTFS-specific data. They therefore act similarly to the
+corresponding commands of Microsoft's ImageX or DISM. For best results, the
+directory being captured should be on an NTFS volume and the program should be
+run with Administrator privileges; however, non-NTFS filesystems and running
+without Administrator privileges are also supported, subject to limitations.
+.PP
+On Windows, \fBwimcapture\fR and \fBwimappend\fR try to capture as much data and
+metadata as possible, including:
+.IP \[bu] 4
+All data streams of all files.
+.IP \[bu]
+Reparse points, if supported by the source filesystem. See \fBREPARSE POINTS
+AND SYMLINKS\fR for details.
+.IP \[bu]
+File and directory creation, access, and modification timestamps. These are
+stored with Windows' native timestamp resolution of 100 nanoseconds.
+.IP \[bu]
+Security descriptors, if supported by the source filesystem and \fB--no-acls\fR
+is not specified. Note: when not running as an Administrator, security
+descriptors may be only partially captured (see \fB--strict-acls\fR).
+.IP \[bu]
+File attributes, including hidden, sparse, compressed, encrypted, etc.
+Encrypted files will be stored in encrypted form rather than in plain text.
+Transparently compressed files will be read as uncompressed and stored subject
+to the WIM's own compression. There is no special handling for storing sparse
+files, but they are likely to compress to a small size.
+.IP \[bu]
+DOS names (8.3) names of files; however, the failure to read them is not
+considered an error condition.
+.IP \[bu]
+Hard links, if supported by the source filesystem.
+.IP \[bu]
+Object IDs, if supported by the source filesystem.
+.PP
+There is no support yet for capturing NTFS extended attributes.
+.SH REPARSE POINTS AND SYMLINKS
+A "symbolic link" (or "symlink") is a special file which "points to" some other
+file or directory. On Windows, a "reparse point" is a generalization of a
+symlink which allows access to a file or directory to be redirected in a more
+complex way. Windows uses reparse points to implement symlinks and sometimes
+uses them for various other features as well. Normally, applications can choose
+whether they want to "dereference" reparse points and symlinks or not.
+.PP
+The default behavior of \fBwimcapture\fR is that reparse points and symlinks are
+\fInot\fR dereferenced, meaning that the reparse points or symlinks themselves
+are stored in the archive rather than the files or data they point to. There is
+a \fB--dereference\fR option, but it is currently only supported by the UNIX
+version of \fBwimcapture\fR on UNIX filesystems (it's not yet implemented for
+Windows filesystems).
+.PP
+Windows also treats certain types of reparse points specially. For example,
+Windows applications reading from deduplicated, WIM-backed, or system-compressed
+files always see the dereferenced data, even if they ask not to. Therefore,
+\fBwimcapture\fR on Windows will store these files dereferenced, not as reparse
+points. But \fBwimcapture\fR on UNIX in NTFS-3G mode cannot dereference these
+files and will store them as reparse points instead. This difference can be
+significant in certain situations, e.g. when capturing deduplicated files which,
+to be readable after extraction, require that the chunk store also be present.
+.SH OPTIONS
+.TP 6
+\fB--boot\fR
+Mark the new image as the "bootable" image of the WIM. The "bootable" image is
+the image which the Windows bootloader will use when loading Windows PE from the
+WIM.
+.TP
+\fB--check\fR
+Include extra integrity information in the resulting WIM. With \fBwimappend\fR,
+also check the integrity of the WIM before appending to it.
+.TP
+\fB--compress\fR=\fITYPE\fR[:\fILEVEL\fR]
+With \fBwimcapture\fR, use the specified compression format in the new WIM file.
+\fITYPE\fR may be "none", "XPRESS" (alias: "fast"), "LZX" (alias: "maximum"), or
+"LZMS" (alias: "recovery"). \fITYPE\fR is matched case-insensitively. The
+default is "LZX".
+.IP ""
+You can optionally also specify an integer compression \fILEVEL\fR. The
+compression level specifies how hard the compression algorithm for the specified
+compression \fITYPE\fR will work to compress the data. The values are scaled so
+that 20 is quick compression, 50 is medium compression, and 100 is high
+compression. However, you can choose any value and not just these particular
+values. The default is 50.
+.IP ""
+This option only affects the compression type used in non-solid WIM resources.
+If you are creating a solid WIM (using the \fB--solid\fR option), then you
+probably want \fB--solid-compress\fR instead.
+.IP ""
+Be careful if you choose LZMS compression. It is not compatible with wimlib
+before v1.6.0, WIMGAPI before Windows 8, DISM before Windows 8.1, and 7-Zip
+before v15.12. Also note that choosing LZMS compression does not automatically
+imply solid-mode compression, as it does with DISM. Use \fB--solid\fR if you
+want to create a solid WIM, or "ESD file".
+.TP
+\fB--chunk-size\fR=\fISIZE\fR
+With \fBwimcapture\fR, use a compression chunk size of \fISIZE\fR bytes. A
+larger compression chunk size results in a better compression ratio. wimlib
+supports different chunk sizes depending on the compression type:
+.RS
+.IP \[bu] 2
+XPRESS: 4K, 8K, 16K, 32K, 64K
+.IP \[bu]
+LZX: 32K, 64K, 128K, 256K, 512K, 1M, 2M
+.IP \[bu]
+LZMS: 32K, 64K, 128K, 256K, 512K, 1M, 2M, 4M, 8M, 16M, 32M, 64M, 128M, 256M, 512M, 1G
+.RE
+.IP ""
+You can provide the full number (e.g. 32768), or you can use one of the K, M, or
+G suffixes. KiB, MiB, and GiB are also accepted.
+.IP ""
+This option only affects the chunk size used in non-solid WIM resources. If you
+are creating a solid WIM (using the \fB--solid\fR option), then you probably
+want \fB--solid-chunk-size\fR instead.
+.IP ""
+Use this option with caution if compatibility with Microsoft's WIM software is
+desired, since their software has limited support for non-default chunk sizes.
+.TP
+\fB--solid\fR
+With \fBwimcapture\fR, create a "solid" WIM file that compresses files together
+rather than independently. This results in a significantly better compression
+ratio, but it comes at the cost of slow compression with very high memory usage,
+reduced compatibility, and slow random access to the resulting WIM file.
+.IP ""
+By default this enables solid LZMS compression, thereby creating a file
+equivalent to one created with DISM's \fB/compress\fR:\fIrecovery\fR option.
+Such files are also called "ESD files" and were first supported by WIMGAPI in
+Windows 8, by DISM in Windows 8.1, and by 7-Zip 15.12.
+.TP
+\fB--solid-compress\fR=\fITYPE\fR[:\fILEVEL\fR]
+Like \fB--compress\fR, but set the compression type used in solid resources.
+The default is LZMS compression. This option only has an effect when
+\fB--solid\fR is also specified.
+.TP
+\fB--solid-chunk-size\fR=\fISIZE\fR
+Like \fB--chunk-size\fR, but set the chunk size used in solid resources. The
+default, assuming LZMS compression, is 64MiB (67108864); this requires about
+640MiB of memory per thread. This option only has an effect when \fB--solid\fR
+is also specified. Note: Microsoft's WIM software is not compatible with LZMS
+chunk sizes larger than 64MiB.
+.TP
+\fB--threads\fR=\fINUM_THREADS\fR
+Number of threads to use for compressing data. Default: autodetect (number of
+available CPUs).
+.TP
+\fB--rebuild\fR
+With \fBwimappend\fR, rebuild the entire WIM rather than appending the new data
+to the end of it. Rebuilding the WIM is slower, but will save some space that
+would otherwise be left as a hole in the WIM. Also see \fBwimoptimize\fR(1).
+.TP
+\fB--flags\fR=\fIEDITIONID\fR
+Specify a string to use in the <FLAGS> element of the XML data for the new
+image.
+.TP
+\fB--image-property\fR \fINAME\fR=\fIVALUE\fR
+Assign an arbitrary property to the new image in the XML document of the WIM.
+\fIVALUE\fR is the string to set as the property value. \fINAME\fR is the name
+of the image property, for example "NAME", "DESCRIPTION", or "TOTALBYTES". The
+name can contain forward slashes to indicate a nested XML element; for example,
+"WINDOWS/VERSION/BUILD" indicates the BUILD element nested within the VERSION
+element nested within the WINDOWS element. A bracketed number can be used to
+indicate one of several identically-named elements; for example,
+"WINDOWS/LANGUAGES/LANGUAGE[2]" indicates the second "LANGUAGE" element nested
+within the "WINDOWS/LANGUAGES" element. When adding a list of elements in this
+way, they must be specified in sequential order. Note that element names are
+case-sensitive. This option may be specified multiple times.
+.TP
+\fB--dereference\fR
+(UNIX-like systems only) Follow symbolic links and archive the files they point
+to, rather than archiving the links themselves.
+.TP
+\fB--config\fR=\fIFILE\fR
+Specifies a configuration file (UTF-8 or UTF-16LE encoded; plain ASCII also
+works) for capturing the new image. The configuration file specifies files that
+are to be treated specially during the image capture.
+.IP ""
+The format of the configuration file is INI-style; that is, it is arranged in
+bracketed sections. Currently, the following sections are recognized:
+.RS
+.IP \[bu] 4
+[ExclusionList] --- contains a list of path globs to exclude from capture. If
+a directory is matched, both the directory and its contents are excluded.
+.IP \[bu]
+[ExclusionException] --- contains a list of path globs to include in the
+capture, even when the file or directory also matches a glob in [ExclusionList].
+.IP \[bu]
+[PrepopulateList] --- this does not affect capture, but if the image is applied
+later with \fB--wimboot\fR, these are globs of files that shall be extracted
+normally, not as WIMBoot "pointer files". If a directory is matched, all files
+and subdirectories are also matched recursively.
+.RE
+.IP ""
+Path globs may contain the '*' and '?' meta-characters. Relative globs (e.g.
+*.mp3) match against a filename in any directory. Absolute globs (e.g.
+/dir/file), are treated as paths starting at the main directory being captured,
+or the root of the NTFS volume for NTFS volume capture mode. Do not use drive
+letters in the paths; they will be ignored. Path separators may be either
+forwards slashes or backwards slashes.
+.IP ""
+Lines beginning with the '#' or ';' characters are treated as comments and
+ignored. Globs with whitespace in them need not be quoted; however, if they
+are, both double and single quotes are accepted.
+.IP ""
+If this option is not specified the following default configuration file is
+used:
+.IP ""
+.RS
+.RS
+.nf
+[ExclusionList]
+\\$ntfs.log
+\\hiberfil.sys
+\\pagefile.sys
+\\swapfile.sys
+\\System Volume Information
+\\RECYCLER
+\\Windows\\CSC
+.RE
+.RE
+.fi
+.IP ""
+However, special behavior applies if \fB--wimboot\fR is also specified. By
+default, with \fB--wimboot\fR specified, the file
+Windows/System32/WimBootCompress.ini in the directory being captured will be
+used as the configuration file. However, this can be overridden using
+\fB--config\fR; and this also causes the specified configuration file to be
+saved in the WIM image as Windows/System32/WimBootCompress.ini, overriding any
+that may be present on the filesystem.
+.TP
+\fB--unix-data\fR
+(UNIX-like systems only) Store UNIX-specific metadata and special files. This
+includes: standard UNIX file permissions (owner, group, and mode); device nodes,
+named pipes, and sockets; and extended attributes (Linux only). This
+information can later be restored by \fBwimapply\fR with the \fB--unix-data\fR
+option.
+.IP
+UNIX-specific information is ignored by Microsoft's WIM software and by the
+Windows version of wimlib.
+.TP
+\fB--no-acls\fR
+Do not capture files' security descriptors.
+.TP
+\fB--strict-acls\fR
+Fail immediately if the full security descriptor of any file cannot be read. On
+Windows, the default behavior without this option is to first try omitting the
+SACL from the security descriptor, then to try omitting the security descriptor
+entirely. The purpose of this is to capture as much data as possible without
+always requiring Administrator privileges. However, if you desire that all
+security descriptors be captured exactly, you may wish to provide this option,
+although the Administrator should have permission to read everything anyway.
+.TP
+\fB--rpfix\fR, \fB--norpfix\fR
+Set whether to fix targets of absolute symbolic links (reparse points in Windows
+terminology) or not. When enabled (\fB--rpfix\fR), absolute symbolic links that
+point inside the directory tree being captured will be adjusted to be absolute
+relative to the root of the directory tree being captured. When disabled
+(\fB--norpfix\fR), absolute symbolic links will be captured exactly as is.
+.IP ""
+The default behavior of \fBwimcapture\fR is equivalent to \fB--rpfix\fR. The
+default behavior of \fBwimappend\fR is equivalent to \fB--rpfix\fR if reparse
+point fixups have previously been done on \fIWIMFILE\fR, otherwise
+\fB--norpfix\fR.
+.IP ""
+In the case of a multi-source capture, (\fB--source-list\fR specified), passing
+\fB--norpfix\fR is recommended. Otherwise, reparse point fixups will be
+disabled on all capture sources destined for non-root locations in the WIM
+image, while capture sources destined for the WIM root will get the default
+behavior from the previous paragraph.
+.TP
+\fB--source-list\fR
+\fBwimcapture\fR and \fBwimappend\fR support creating a WIM image from multiple
+separate files or directories. When \fB--source-list\fR is specified, the
+\fISOURCE\fR argument specifies the name of a text file, each line of which is
+either 1 or 2 whitespace separated file paths. The first file path, the source,
+specifies the path to a file or directory to capture into the WIM image. It may
+be either absolute or relative to the current working directory. The second
+file path, if provided, is the target and specifies the path in the WIM image
+that this file or directory will be saved as. Leading and trailing slashes in
+the target are ignored, except if it consists entirely of slashes (e.g. "/"),
+which indicates that the directory is to become the root of the WIM image. If
+omitted, the target string defaults to the same as the source string.
+.IP ""
+An example source list file is as follows:
+.IP ""
+.RS
+.RS
+.nf
+# Make the WIM image from the 'winpe' directory
+winpe /
+
+# Send the 'overlay' directory to '/overlay' in the WIM image
+overlay /overlay
+
+# Overlay a separate directory directly on the root of the WIM image.
+/data/stuff /
+.RE
+.RE
+.fi
+.IP ""
+Subdirectories in the WIM are created as needed. Multiple source directories
+may share the same target, which implies an overlay. In the event that this
+results a nondirectory file being added to the WIM image multiple times, the
+last version (as listed in the source list file) overrides any earlier version.
+.IP ""
+File paths containing whitespace may be quoted with either single quotes or
+double quotes. Quotes may not be escaped.
+.IP ""
+Lines consisting only of whitespace and lines beginning with '#' preceded by
+optional whitespace are ignored.
+.IP ""
+As a special case, if \fISOURCE\fR is "-", the source list is read from standard
+input rather than an external file.
+.IP ""
+The NTFS volume capture mode on UNIX-like systems cannot be used with
+\fB--source-list\fR, as only capturing a full NTFS volume is supported.
+.TP
+\fB--pipable\fR
+With \fBwimcapture\fR, create a wimlib-specific "pipable" WIM which can be
+captured and applied fully sequentially. If \fIWIMFILE\fR is specified as "-",
+then the pipable WIM is written directly to standard output; otherwise, it is
+written to disk as usual. The image in the pipable WIM can be later be applied
+with \fBwimapply\fR, either from disk or from standard input. A typical use of
+pipable WIMs might involve streaming the WIM image to a remote server when
+capturing it and/or streaming the WIM image from a remote server when applying
+it.
+.IP ""
+Generally, all the \fBwimlib-imagex\fR commands work on both pipable and
+non-pipable WIMs. \fBwimoptimize\fR and \fBwimexport\fR may also be used to
+convert between pipable WIMs and non-pipable WIMs. However, there are a few
+limitations of pipable WIMs:
+.RS
+.IP \[bu] 4
+Pipable WIMs are a wimlib extension which are \fInot\fR compatible with
+Microsoft's WIM software or with other programs such as 7-Zip.
+.IP \[bu]
+Using \fBwimappend\fR, multiple images may be added to a pipable WIM. This is
+supported, though it is less efficient than doing so with non-pipable WIMs
+because a pipable WIM is fully rebuilt each time it is appended to; and when
+piping such a WIM to \fBwimapply\fR to extract an image, some unneeded data will
+be sent over the pipe.
+.IP \[bu]
+Although a pipable WIM image may be updated using \fBwimupdate\fR, it requires a
+full rebuild of the WIM file, making it less efficient than updating a
+non-pipable WIM.
+.IP \[bu]
+Solid pipable WIMs are not yet supported.
+.RE
+.TP
+\fB--not-pipable\fR
+With \fBwimappend\fR, rebuild the WIM file in the non-pipable (regular) format.
+This option is only useful if you happen to be adding an image to a pipable WIM
+(see \fB--pipable\fR) which you want in non-pipable format instead. Note that
+\fBwimoptimize\fR(1) can also be used to convert between non-pipable and pipable
+WIMs.
+.TP
+\fB--update-of\fR=[\fIWIMFILE\fR:]\fIIMAGE\fR
+Hint that the image being captured or appended from \fISOURCE\fR is mostly the
+same as the existing image \fIIMAGE\fR in \fIWIMFILE\fR, but captured at a later
+point in time, possibly with some modifications in the intervening time. This
+is designed to be used in incremental backups of the same filesystem or
+directory tree. \fIIMAGE\fR can be a 1-based index or name of an existing image
+in \fIWIMFILE\fR. It can also be a negative integer to index backwards into the
+images (e.g. -1 means the last existing image in \fIWIMFILE\fR).
+.IP ""
+When this option is provided, the capture or append of the new image will be
+optimized by not reading files that, based on metadata such as timestamps,
+appear not to have been modified since they were archived in the existing
+\fIIMAGE\fR. Barring manipulation of timestamps, this option only affects
+performance and does not change the resulting WIM image (but see note below).
+.IP ""
+As shown, the full syntax for the argument to this option is to specify the WIM
+file, a colon, and the image; for example, "--update-of mywim.wim:1". However,
+the WIM file and colon may be omitted, in which case the WIM file will default
+to the WIM file being appended to for append operations, or the WIM file from
+which a delta is being taken (only if \fB--delta-from\fR is specified exactly
+once) for capture operations.
+.IP ""
+Note: in the Windows version of wimlib, it has been observed that
+\fB--update-of\fR mode is not completely reliable at detecting changes in file
+contents, sometimes causing the old contents of a few files to be archived
+rather than the current contents. The cause of this problem is that Windows
+does not immediately update a file's last modification timestamp after every
+write to that file. Unfortunately, there is no known way for applications like
+wimlib to automatically work around this bug. Manual workarounds are possible;
+theoretically, taking any action that causes the problematic files to be closed,
+such as restarting applications or the computer itself, should cause the files'
+last modification timestamps to be updated. Also note that wimlib compares file
+sizes as well as timestamps in determining whether a file has changed, which
+helps make the problem less likely to occur; and the problem does not occur on
+other operating systems such as Linux which maintain files' last modification
+timestamps correctly.
+.TP
+\fB--delta-from\fR=\fIWIMFILE\fR
+With \fBwimcapture\fR, capture the new WIM as a "delta" from \fIWIMFILE\fR. Any
+file data that would ordinarily need to be archived in the new WIM is omitted if
+it is already present in the \fIWIMFILE\fR on which the delta is being based.
+The new WIM will still contain a full copy of the image metadata, but this is
+typically only a small fraction of a WIM's total size.
+.IP ""
+This option can be specified multiple times, in which case the resulting delta
+WIM will only contain file data not present in any of the specified base WIMs.
+.IP ""
+To operate on the resulting delta WIM using other commands such as
+\fBwimapply\fR, you must specify the delta WIM as the WIM file to operate on,
+but also reference the base WIM(s) using the \fB--ref\fR option. Beware: to
+retain the proper functioning of the delta WIM, you can only add, not delete,
+files and images to the base WIM(s) following the capture of a delta from it.
+.IP ""
+\fB--delta-from\fR may be combined with \fB--update-of\fR to increase the
+speed of capturing a delta WIM.
+.IP ""
+As an example, consider the following backup and restore sequence:
+.IP ""
+.RS
+.nf
+(initial backup)
+
+$ wimcapture /some/directory bkup-base.wim
+
+(some days later, create second backup as delta from first)
+
+$ wimcapture /some/directory bkup-2013-08-20.dwm \\
+ --update-of bkup-base.wim:-1 --delta-from bkup-base.wim
+
+(restoring the second backup)
+
+$ wimapply bkup-2013-08-20.dwm --ref=bkup-base.wim 1 \\
+ /some/directory
+.RE
+.fi
+.IP ""
+However, note that as an alternative to the above sequence that used a delta
+WIM, the second backup could have simply been appended to the WIM as new image
+using \fBwimappend\fR. Delta WIMs should be used only if it's desired to base
+the backups or images on a separate, large file that is rarely modified.
+.IP ""
+Delta WIMs are compatible with Microsoft's WIM software. For example, you can
+use the /ref option of ImageX to reference the base WIM(s), similar to above.
+.IP ""
+Additional note: wimlib is generalized enough that you can in fact combine
+\fB--pipable\fR and \fB--delta-from\fR to create pipable delta WIMs. In such
+cases, the base WIM(s) must be captured as pipable as well as the delta WIM, and
+when applying an image, the base WIM(s) must be sent over the pipe after the
+delta WIM.
+.TP
+\fB--wimboot\fR
+Mark the image as WIMBoot-compatible. See Microsoft's documentation for more
+information about WIMBoot. With \fBwimcapture\fR this option will set the
+compression type to XPRESS and the chunk size to 4096 bytes; these can, however,
+still be overridden through the \fB--compress\fR and \fB--chunk-size\fR
+parameters, respectively. In addition, this option will set the configuration
+file to \fISOURCE\fR\\Windows\\System32\\WimBootCompress.ini if present and
+accessible; however, this may still be overridden through the \fB--config\fR
+parameter.
+.TP
+\fB--unsafe-compact\fR
+With \fBwimappend\fR, compact the WIM archive in-place and append any new data,
+eliminating "holes". This is efficient, but in general this option should
+\fInot\fR be used because a failed or interrupted compaction will corrupt the
+WIM archive. For more information, see the documentation for this option to
+\fBwimoptimize\fR(1).
+.TP
+\fB--snapshot\fR
+Create a temporary filesystem snapshot of the source directory and capture the
+files from it. Currently, this option is only supported on Windows, where it
+uses the Volume Shadow Copy Service (VSS). Using this option, you can create a
+consistent backup of the system volume of a running Windows system without
+running into problems with locked files. For the VSS snapshot to be
+successfully created, \fBwimlib-imagex\fR must be run as an Administrator, and
+it cannot be run in WoW64 mode (i.e. if Windows is 64-bit, then
+\fBwimlib-imagex\fR must be 64-bit as well).
+.SH NOTES
+\fBwimappend\fR does not support appending an image to a split WIM.
+.PP
+Except when using \fB--unsafe-compact\fR, it is safe to abort a \fBwimappend\fR
+command partway through; however, after doing this, it is recommended to run
+\fBwimoptimize\fR to remove any data that was appended to the physical WIM file
+but not yet incorporated into the structure of the WIM, unless the WIM was being
+fully rebuilt (e.g. with \fB--rebuild\fR), in which case you should delete the
+temporary file left over.
+.PP
+\fBwimlib-imagex\fR creates WIMs compatible with Microsoft's software (WIMGAPI,
+ImageX, DISM), with some caveats:
+.IP \[bu] 4
+With \fBwimlib-imagex\fR on UNIX-like systems, it is possible to create a WIM
+image containing files with names differing only in case, or files with names
+containing the characters ':', '*', '?', '"', '<', '>', '|', or '\\', which are
+valid on POSIX-compliant filesystems but not Windows. Be warned that such files
+will not be extracted by default by the Windows version of \fBwimlib-imagex\fR,
+and (even worse) Microsoft's ImageX can be confused by such names and quit
+extracting the image partway through.
+.IP \[bu]
+Pipable WIMs are incompatible with Microsoft's software. Pipable WIMs are
+created only if \fIWIMFILE\fR was specified as "-" (standard output) or if
+the \fB--pipable\fR flag was specified.
+.IP \[bu]
+WIMs captured with a non-default chunk size (with the \fB--chunk-size\fR option)
+or as solid archives (with the \fB--solid\fR option) or with LZMS compression
+(with \fB--compress\fR=LZMS or \fB--compress\fR=recovery) have varying levels of
+compatibility with Microsoft's software. Generally, more recent versions of
+Microsoft's software are more compatible.
+.SH EXAMPLES
+First example: Create a new WIM 'mywim.wim' with LZX ("maximum") compression
+that will contain a captured image of the directory tree 'somedir'. Note that
+the image name need not be specified and will default to 'somedir':
+.RS
+.PP
+wimcapture somedir mywim.wim
+.RE
+.PP
+Next, append the image of a different directory tree to the WIM created above:
+.RS
+.PP
+wimappend anotherdir mywim.wim
+.RE
+.PP
+Easy enough, and the above examples of imaging directory trees work on both
+UNIX-like systems and Windows. Next, capture a WIM with several non-default
+options, including XPRESS ("fast") compression, extra integrity information, no
+messing with absolute symbolic links, and an image name and description:
+.RS
+.PP
+wimcapture somedir mywim.wim --compress=fast \\
+.RS
+--check --norpfix "Some Name" "Some Description"
+.RE
+.RE
+.PP
+On a UNIX-like system, capture a full NTFS volume into a new WIM using the
+\fBNTFS VOLUME CAPTURE (UNIX)\fR mode, and name the image "Windows 7":
+.RS
+.PP
+wimcapture /dev/sda2 windows7.wim "Windows 7"
+.RE
+.PP
+or, on Windows, to capture a full NTFS volume you instead need to specify the
+root directory of the mounted volume, for example:
+.RS
+.PP
+wimcapture E:\\ windows7.wim "Windows 7"
+.RE
+.PP
+Same as UNIX example above, but capture the WIM in the wimlib-specific "pipable"
+format that can be piped to \fBwimapply\fR:
+.RS
+.PP
+wimcapture /dev/sda2 windows7.wim "Windows 7" --pipable
+.RE
+.PP
+Same as above, but instead of writing the pipable WIM to the file
+"windows7.wim", write it directly to standard output through a pipe into some
+other program "someprog", which could, for example, be a program or script that
+streams the data to a server:
+.RS
+.PP
+wimcapture /dev/sda2 - "Windows 7" | someprog
+.RE
+.SH SEE ALSO
+.BR wimlib-imagex (1),
+.BR wimapply (1)
+.BR wimoptimize (1)
git://wimlib.net / wimlib / blobdiff