+++ /dev/null
-.TH WIMLIB-IMAGEX "1" "November 2014" "wimlib-imagex @VERSION@" "User Commands"
-.SH NAME
-wimlib-imagex-capture, wimlib-imagex-append \- Create or append a WIM image
-.SH SYNOPSIS
-\fBwimlib-imagex capture\fR \fISOURCE\fR \fIWIMFILE\fR [\fIIMAGE_NAME\fR \
-[\fIIMAGE_DESCRIPTION\fR]] [\fIOPTION\fR...]
-.br
-\fBwimlib-imagex append\fR \fISOURCE\fR \fIWIMFILE\fR [\fIIMAGE_NAME\fR \
-[\fIIMAGE_DESCRIPTION\fR]] [\fIOPTION\fR...]
-.SH DESCRIPTION
-The \fBwimlib-imagex capture\fR and \fBwimlib-imagex append\fR commands
-create a Windows Imaging (WIM) image from a directory tree. The
-\fBwimlib-imagex capture\fR command creates a new WIM file containing the
-captured image, while the \fBwimlib-imagex append\fR command appends the
-captured image to an existing WIM file.
-These commands are also available as simply \fBwimcapture\fR and \fBwimappend\fR
-if the appropriate hard links or batch files are installed.
-.PP
-Background information: A WIM image is an independent directory tree in a WIM
-file. A WIM file may contain any number of separate images. WIM files are
-single-instancing with regards to file data, so a file is stored only one time
-in the entire WIM, regardless of how many images the file appears in.
-.PP
-\fISOURCE\fR specifies the location of the files to create the new WIM image
-from. If \fISOURCE\fR is a directory, the WIM image is captured from that
-directory (see \fBDIRECTORY CAPTURE (UNIX)\fR or \fBDIRECTORY CAPTURE
-(WINDOWS)\fR). Alternatively, if the \fB--source-list\fR option is specified,
-\fISOURCE\fR is interpreted as a file that itself provides a list of
-files and directories to include in the new WIM image. Still
-alternatively, only on UNIX-like systems, if \fISOURCE\fR is a
-regular file or block device, it is interpreted as an NTFS volume from
-which a WIM image is to be captured using libntfs-3g (see \fBNTFS VOLUME CAPTURE
-(UNIX)\fR).
-.PP
-\fIIMAGE_NAME\fR and \fIIMAGE_DESCRIPTION\fR specify the name and description to
-give the new WIM image. If \fIIMAGE_NAME\fR is not specified, it defaults to
-the base name (excluding path to parent directory) of \fISOURCE\fR, but if this
-name already exists in \fIWIMFILE\fR, a unique suffix is added. Otherwise,
-\fIIMAGE_NAME\fR must be either a name that does not already exist as an image in
-\fIWIMFILE\fR, or the empty string to create an image with no name. If
-\fIIMAGE_DESCRIPTION\fR is not specified, no description is given to the new
-image.
-.PP
-As a special case, if \fIWIMFILE\fR is "-", the \fB--pipable\fR option is
-assumed and the WIM file is written to standard output in a special pipable
-format. See the documentation for \fB--pipable\fR for more details.
-.SH DIRECTORY CAPTURE (UNIX)
-This section documents how \fBwimlib-imagex\fR captures files from a
-directory tree on UNIX-like systems. See \fBDIRECTORY CAPTURE (WINDOWS)\fR for
-the corresponding documentation for Windows.
-.PP
-On UNIX-like systems, when \fISOURCE\fR specifies a directory or a symbolic link
-to a directory, the WIM image will be captured from the directory tree rooted at
-this directory. This directory can be on any type of filesystem, and mount
-points are followed recursively. However, it is important to keep in mind that
-the WIM format was designed for Windows, so it cannot store all possible
-metadata from filesystems used on UNIX-like systems. The main information that
-will \fInot\fR be stored is:
-.IP \[bu] 4
-UNIX file owners, groups, modes, and device IDs (major and minor numbers),
-unless the \fB--unix-data\fR option is specified. By default (without
-\fB--unix-data\fR), files that are neither regular files, directories, nor
-symbolic links, such as device nodes and FIFOs, will be excluded.
-.IP \[bu]
-Extended attributes. This mainly includes extensions to the traditional UNIX
-security model, such as SELinux security labels, POSIX ACLs, and capabilities
-labels.
-.IP \[bu]
-Linux file attributes, as can be changed using the \fBchattr\fR (1) utility.
-.PP
-Notes: Timestamps are stored with 100 nanosecond granularity and include last
-modification time (mtime) and last access time (atime), but not last status
-change time (ctime). Hard links and symbolic links are supported by the WIM
-format and \fIare\fR stored. Symbolic links are turned into "native" Windows
-symbolic links, or "reparse points"; this process is fully reversible, e.g.
-automatically by \fBwimlib-imagex apply\fR, unless the symbolic link target
-contains backslash characters.
-.PP
-Pedantic note: A limitation of the WIM format prevents the unusual case where a
-single symbolic link file itself has multiple names (hard links); in this
-unlikely case, each symbolic link is stored as an independent file.
-.SH NTFS VOLUME CAPTURE (UNIX)
-This section documents how \fBwimlib-imagex\fR captures files directly from
-an NTFS volume image on UNIX-like systems.
-.PP
-On UNIX-like systems, a special image capture mode is entered when \fISOURCE\fR
-is a regular file or block device. In this mode, \fISOURCE\fR is assumed to be
-an NTFS volume or volume image, and \fBwimlib-imagex\fR will capture a WIM
-image containing the full contents of the NTFS volume, including NTFS-specific
-data. This is done using libntfs-3g.
-.PP
-Please note that the NTFS volume capture mode is \fInot\fR entered if
-\fISOURCE\fR is a directory, even if an NTFS filesystem is mounted on
-\fISOURCE\fR using ntfs-3g. You must specify the NTFS volume itself (and it
-must be unmounted, and you must have permission to read from it).
-.PP
-The NTFS volume capture mode attempts to capture as much data and metadata as
-possible, including:
-.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, including symbolic links, junction points, and other reparse
-points.
-.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.
-.PP
-However, the main limitations of this NTFS volume capture mode are:
-.IP \[bu] 4
-Encrypted files are excluded by default. Although ntfs-3g can read their data,
-they need to be stored in the WIM file in a special format that wimlib does not
-yet support (except on Windows, where wimlib can treat the data as opaque and
-hand it off to the appropriate API function).
-.IP \[bu]
-The sparse attribute on sparse files will be saved, but the data stored will be
-the full data of the file rather than the "sparse" data. (The data is, however,
-subject to the WIM format's compression.)
-.SH DIRECTORY CAPTURE (WINDOWS)
-On Windows, \fBwimlib-imagex capture\fR and \fBwimlib-imagex append\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
-\fBwimlib-imagex\fR should be run with Administrator privileges; however,
-non-NTFS filesystems and running without Administrator privileges are also
-supported.
-.PP
-On Windows, \fBwimlib-imagex capture\fR and \fBwimlib-imagex append\fR
-try to archive as much data and metadata as possible, including:
-.IP \[bu] 4
-All data streams of all files.
-.IP \[bu]
-Reparse points, including symbolic links, junction points, and other reparse
-points, if supported by the source filesystem. (Note: see \fB--rpfix\fR and
-\fB--norpfix\fR for documentation on exactly how absolute symbolic links and
-junctions are captured.)
-.IP \[bu]
-File and directory creation, access, and modification timestamps. These are
-stored with Windows NT's native timestamp resolution of 100 nanoseconds.
-.IP \[bu]
-Security descriptors, if supported by the source filesystem and \fB--no-acls\fR
-is not specified. However, beware that unless \fB--strict-acls\fR is specified,
-the security descriptors for individual files or directories may be omitted or
-only partially captured if the user does not have permission to read them, which
-can be a problem if \fBwimlib-imagex\fR is run as a non-Administrator.
-.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.
-.PP
-Note: the capture process is reversible, since when \fBwimlib-imagex
-apply\fR (on Windows) extracts the captured WIM image, it will extract all of
-the above information, at least to the extent supported by the destination
-filesystem. One exception is that since encrypted files are stored as
-encrypted, their data will not be available if restored on a Windows system
-that does not have the decryption key.
-.PP
-Pedantic note: since Windows is not fully compatible with its own filesystem
-(NTFS), on Windows wimlib cannot archive certain files that may exist on a valid
-NTFS filesystem but are inaccessible to the Windows API, for example two files
-with names differing only in case in the same directory, or a file whose name
-contains certain characters considered invalid by Windows. If you run into
-problems archiving such files consider using the \fBNTFS VOLUME CAPTURE
-(UNIX)\fR mode from Linux.
-.SH OPTIONS
-.TP 6
-\fB--boot\fR
-Specifies that the new image is to be made the bootable image of the WIM archive.
-.TP
-\fB--check\fR
-For \fBwimlib-imagex append\fR, before performing the append operation,
-check the integrity of \fIWIMFILE\fR if an integrity table is present.
-Furthermore, include an integrity table in the new WIM file
-(\fBwimlib-imagex capture\fR) or the modified WIM file (\fBwimlib-imagex
-append\fR). If this option is not specified, no integrity table is included in
-a WIM file created with \fBwimlib-imagex capture\fR, while a WIM file
-updated with \fBwimlib-imagex append\fR will be written with an integrity
-table if and only if one was present before.
-.TP
-\fB--compress\fR=\fITYPE\fR[:\fILEVEL\fR]
-Specifies the compression format for 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 ""
-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.
-.TP
-\fB--chunk-size\fR=\fISIZE\fR
-Set the WIM compression chunk size to \fISIZE\fR bytes. Larger chunks mean larger
-LZ77 dictionaries and better compression ratios on sufficiently large files, but
-slower random access. \fBUsing this option is generally not recommended because
-of the compatibility limitations detailed in the next paragraph.\fR But if you
-decide to use this option regardless, you may choose a chunk size that is
-allowed by the compression format. All formats only allow power-of-2 chunk
-sizes. For LZX ("maximum") compression the maximum allowed chunk size is 2^21
-(2097152), for XPRESS ("fast") compression the maximum allowed chunk size is
-2^16 (65536), and for LZMS ("recovery") compression the maximum allowed chunk
-size is 2^30 (1073741824).
-.IP ""
-Beware that Microsoft's implementation has limited support for non-default chunk
-sizes. Depending on the version, their software may refuse to open the WIM, or
-open it and crash, or open it and report the data is invalid, or even extract
-the data incorrectly. In addition, wimlib versions before 1.6.0 do not support
-alternate chunk sizes.
-.TP
-\fB--solid\fR
-Create a "solid" archive that compresses multiple unique streams ("files")
-together, rather than each unique stream ("file") independently. This can
-result in a significantly better compression ratio, but this format greatly
-decreases the performance of random access to the data, as may occur on a WIM
-mounted with \fBwimlib-imagex mount\fR. Also, WIMs created using this
-option use a different version number in their header and are only compatible
-with WIMGAPI Windows 8 and later, and DISM Windows 8.1 and later.
-.IP ""
-The default compression type and chunk size in solid blocks is LZMS with 2^25
-(33554432) byte chunks. This is independent of the WIM's main compression type
-and chunk size.
-.TP
-\fB--solid-chunk-size\fR=\fISIZE\fR
-Like \fB--chunk-size\fR, but set the chunk size used in solid blocks. The
-default is LZMS compression with 2^25 (33554432) byte chunks. This option only
-has an effect when \fB--solid\fR is also specified. For maximum compatibility
-with the Microsoft implementation, do not use either of these options.
-.TP
-\fB--solid-compress\fR=\fITYPE\fR[:\fILEVEL\fR]
-Like \fB--compress\fR, but set the compression type used in solid blocks. The
-default is LZMS compression with 2^25 (33554432) byte chunks. This option only
-has an effect when \fB--solid\fR is also specified. For maximum compatibility
-with the Microsoft implementation, do not use either of these options.
-.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
-For \fBwimlib-imagex append\fR: rebuild the entire WIM rather than appending the new
-data to the end of it. Rebuilding the WIM is slower, but will save a little bit
-of space that would otherwise be left as a hole in the WIM. Also see \fBwimlib-imagex
-optimize\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--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, only 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 ""
-Any unrecognized sections will be ignored, with a warning printed. Sections
-dealing with compression (e.g. [CompressionExclusion]) are not particularly
-important.
-.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 the UNIX owner, group, mode, and device ID (major
-and minor number) of each captured file. As of wimlib v1.7.0, you can backup
-and restore not only the standard UNIX file permission information, but also
-character device nodes, block device nodes, named pipes (FIFOs), and UNIX domain
-sockets.
-.IP
-wimlib stores UNIX data by adding a special tagged metadata item to each
-directory entry of each file that contains this information. This extra
-information is ignored by the Microsoft implementation. Note: UNIX data stored
-by wimlib before v1.7.0 used a different format that is no longer supported. If
-you have old WIM files with UNIX data, apply them with v1.6.2 and recapture them
-with v1.7.0 or later.
-.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 for \fBwimlib-imagex capture\fR is equivalent to
-\fB--rpfix\fR. The default behavior for \fBwimlib-imagex append\fR will be
-\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
-\fBwimlib-imagex capture\fR and \fBwimlib-imagex append\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
-Create a "pipable" WIM, which can be applied fully sequentially, including from
-a pipe. An image in the resulting WIM can be applied with \fBwimlib-imagex
-apply\fR, either normally by specifying the WIM file name, or with
-\fBwimlib-imagex apply -\fR to read the WIM from standard input. See
-\fBwimlib-imagex apply\fR(1) for more details.
-.IP ""
-For append operations, this option will result in a full rebuild of the WIM to
-make it pipable. For capture operations, the captured WIM is simply created as
-pipable. Beware that the more images you add to a pipable WIM, the less
-efficient piping it will be, since more unneeded data will be sent through the
-pipe.
-.IP ""
-When wimlib creates a pipable WIM, it carefully re-arranges the components of
-the WIM so that they can be read sequentially and also makes several other
-modifications. As a result, these "pipable" WIMs are \fInot compatible with
-Microsoft's software\fR, so keep this in mind if you're going to use them. If
-desired, you can use \fBwimlib-imagex optimize --not-pipable\fR to re-write
-a pipable WIM as a regular WIM. (\fBwimlib-imagex export\fR also provides
-the capability to export images from a pipable WIM into a non-pipable WIM, or
-vice versa.)
-.IP ""
-For the most part, wimlib operates on pipable WIMs transparently. You can
-modify them, add or delete images, export images, and even create split pipable
-WIMs. The main disadvantages are that appending is (currently) less efficient
-(\fB--rebuild\fR is always implied), and also they aren't compatible with
-Microsoft's software.
-.IP ""
-\fBwimlib-imagex capture\fR and \fBwimlib-imagex append\fR can both
-write a pipable WIM directly to standard output; this is done automatically if
-\fIWIMFILE\fR is specified as "-". (In that case, \fB--pipable\fR is assumed.)
-.TP
-\fB--not-pipable\fR
-Ensure the resulting WIM is in the normal, non-pipable WIM format. This is the
-default for \fBwimlib-imagex capture\fR, except when writing to standard
-output (\fIWIMFILE\fR specified as "-"), and also for \fBwimlib-imagex
-append\fR, except when appending to a WIM that is already pipable.
-.TP
-\fB--update-of\fR=[\fIWIMFILE\fR:]\fIIMAGE\fR
-Declares 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.
-.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.
-.TP
-\fB--delta-from\fR=\fIWIMFILE\fR
-For \fBwimlib-imagex capture\fR only: capture the new WIM as a "delta" from
-\fIWIMFILE\fR. Any streams that would ordinarily need to be archived in the new
-WIM are omitted if they are 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 streams not present in any of the specified base WIMs.
-.IP ""
-To operate on the resulting delta WIM using other commands such as
-\fBwimlib-imagex apply\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 \fBwimlib-imagex append\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 ""
-Note: unlike "pipable" WIMs (created with the \fB--pipable\fR option), "delta"
-WIMs (created with the \fB--delta-from\fR option) are compatible with
-Microsoft's software. For example, you can use the /ref option of ImageX to
-reference the base WIM(s), similar to above.
-.IP ""
-Additional note: \fBwimlib-imagex\fR 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. This option will, by default,
-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, by
-default, 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.
-.SH NOTES
-\fBwimlib-imagex append\fR does not support appending an image to a split WIM.
-.PP
-It is safe to abort an \fBwimlib-imagex append\fR command partway through;
-however, after doing this, it is recommended to run \fBwimlib-imagex
-optimize\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. (It perhaps is worth
-pointing out that Windows' own default filesystem, NTFS, supports these
-characters, although Windows does not!)
-.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
-wimlib-imagex capture somedir mywim.wim
-.RE
-.PP
-or, if the \fBwimcapture\fR hard link or batch file has been installed, the
-abbreviated form can be used:
-.RS
-.PP
-wimcapture somedir mywim.wim
-.RE
-.PP
-The remaining examples will use the long form, however. Next, append the image
-of a different directory tree to the WIM created above:
-.RS
-.PP
-wimlib-imagex append 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, an integrity table, no messing
-with absolute symbolic links, and an image name and description:
-.RS
-.PP
-wimlib-imagex capture somedir mywim.wim --compress=fast \\
-.RS
---check --norpfix "Some Name" "Some Description"
-.RE
-.RE
-.PP
-Capture an entire NTFS volume into a new WIM file and name the image "Windows
-7". On UNIX-like systems, this requires using the special mode described in
-\fBNTFS VOLUME CAPTURE (UNIX)\fR where \fISOURCE\fR is a file or block device
-containing an NTFS filesystem:
-.RS
-.PP
-wimlib-imagex capture /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
-wimlib-imagex capture E:\\ windows7.wim "Windows 7"
-.RE
-.PP
-Same as above example with capturing an NTFS volume from \fBwimlib-imagex\fR
-running on a UNIX-like system, but capture the WIM in the wimlib-specific
-"pipable" format that can be piped to \fBwimlib-imagex apply\fR:
-.RS
-.PP
-wimlib-imagex capture /dev/sda2 windows7.wim "Windows 7" \\
-.br
-.RS
---pipable
-.RE
-.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. Note that \fB--pipable\fR need not be explicitly
-specified when using standard output as the WIM "file":
-.RS
-.PP
-wimlib-imagex capture /dev/sda2 - "Windows 7" | someprog
-.RE
-.SH SEE ALSO
-.BR wimlib-imagex (1),
-.BR wimlib-imagex-apply (1)
git://wimlib.net / wimlib / blobdiff