This command is designed to extract, or "apply", one or more full WIM images.
If you instead want to extract only certain files or directories contained in a
WIM image, consider using \fB@IMAGEX_PROGNAME@ extract\fR or
-\fB@IMAGEX_PROGNAME@ mount\fR instead.
+\fB@IMAGEX_PROGNAME@ mount\fR instead. (\fB@IMAGEX_PROGNAME@ mount\fR is not
+supported on Windows.)
.PP
\fIIMAGE\fR specifies the WIM image in \fIWIMFILE\fR to extract. It may be a
1-based index of an image in \fIWIMFILE\fR, the name of an image in
File creation timestamps.
.PP
Notes: Unsupported data and metadata is simply not extracted, but
-\fB@IMAGEX_PROGNAME@\fR always warns you when the contents of the WIM image
-can't be exactly represented when extracted. Last access and last modification
-timestamps are specified to 100 nanosecond granularity in the WIM file, but will
-only be extracted to the highest precision supported by the underlying operating
-system, C library, and filesystem.
+\fB@IMAGEX_PROGNAME@\fR will attempt to warn you when the contents of the WIM
+image can't be exactly represented when extracted. Last access and last
+modification timestamps are specified to 100 nanosecond granularity in the WIM
+file, but will only be extracted to the highest precision supported by the
+underlying operating system, C library, and filesystem. Compressed files will
+be extracted as uncompressed, while encrypted files will not be extracted at
+all.
.SH NTFS VOLUME EXTRACTION (UNIX)
This section documents how \fB@IMAGEX_PROGNAME@ apply\fR extracts a WIM image
directly to an NTFS volume image on UNIX-like systems. See \fBDIRECTORY EXTRACTION
All names of all files, including names in the Win32 namespace, DOS namespace,
Win32+DOS namespace, and POSIX namespace. This includes hard links.
.PP
-Currently, the only known limitation (in terms of exactly extracting all data
-and metadata) is that the extraction of encrypted files is not expected to work
-properly.
+However, there are also several known limitations of the NTFS volume extraction
+mode:
+.IP \[bu] 4
+Encrypted files will not be extracted.
+.IP \[bu]
+Although sparse file attributes will be applied, the full data will be extracted
+to each sparse file, so extracted "sparse" files may not actually contain any
+sparse regions.
.PP
-Since all (or almost all) information from the WIM image is restored in this
+Regardless, since almost all information from the WIM image is restored in this
mode, it is possible to restore an image of an actual Windows installation using
\fB@IMAGEX_PROGNAME@\fR on UNIX-like systems in addition to with
\fB@IMAGEX_PROGNAME@\fR on Windows. In the examples at the end of this manual
.PP
Additional notes about extracting files on Windows:
.IP \[bu] 4
-\fB@IMAGEX_PROGNAME@\fR will always issue a warning when it is unable to extract
-the exact metadata and data of the WIM image, for example due to features
-mentioned above not being supported by the target filesystem.
+\fB@IMAGEX_PROGNAME@\fR will issue a warning when it is unable to extract the
+exact metadata and data of the WIM image, for example due to features mentioned
+above not being supported by the target filesystem.
.IP \[bu]
Since encrypted files (with FILE_ATTRIBUTE_ENCRYPTED) are not stored in
plaintext in the WIM image, \fB@IMAGEX_PROGNAME@\fR cannot restore encrypted
-files to filesystems not supporting encryption. (The current behavior is to
-just extract the encrypted data anyway.) Furthermore, even if encrypted files
-are restored to a filesystem that supports encryption, they will only be
-decryptable if the decryption key is available.
+files to filesystems not supporting encryption. Therefore, such files are not
+extracted. Furthermore, even if encrypted files are restored to a filesystem
+that supports encryption, they will only be decryptable if the decryption key is
+available.
.IP \[bu]
Files with names that cannot be represented on Windows will not
be extracted by default; see \fB--include-invalid-names\fR.
most Windows software and may not be able to be deleted easily.
.SH SPLIT WIMS
You may use \fB@IMAGEX_PROGNAME@ apply\fR to apply images from a split WIM. The
-\fIWIMFILE\fR argument is used to specify the first part of the split WIM, and
-the \fB--refs\fR="\fIGLOB\fR" option is used to provide a shell-style file glob
-that specifies the additional parts of the split WIM. \fIGLOB\fR is expected to
-be a single string on the command line, so \fIGLOB\fR must be quoted so that it
-is protected against shell expansion. \fIGLOB\fR must expand to all parts of
-the split WIM, except optionally the first part which may either omitted or
-included in the glob (but the first part MUST be specified as \fIWIMFILE\fR as
-well).
-.PP
-Here's an example. The names for the split WIMs usually go something like:
+\fIWIMFILE\fR argument must specify the first part of the split WIM, while the
+additional parts of the split WIM must be specified in one or more
+\fB--ref\fR="\fIGLOB\fR" options. Since globbing is built into the \fB--ref\fR
+option, typically only one \fB--ref\fR option is necessary. For example, the
+names for the split WIM parts usually go something like:
.RS
.PP
.nf
present.
.TP
\fB--ref\fR="\fIGLOB\fR"
-File glob of additional split WIM parts that are part of the split WIM being
-applied. See \fBSPLIT_WIMS\fR.
+File glob of additional WIMs or split WIM parts to reference resources from.
+See \fBSPLIT_WIMS\fR. This option can be specified multiple times. Note:
+\fIGLOB\fR is listed in quotes because it is interpreted by
+\fB@IMAGEX_PROGNAME@\fR and may need to be quoted to protect against shell
+expansion.
.TP
\fB--rpfix\fR, \fB--norpfix\fR
Set whether to fix targets of absolute symbolic links (reparse points in Windows
\fB@IMAGEX_PROGNAME@\fR):
.RS
.PP
-@IMAGEX_PROGNAME@ capture src - | @IMAGEX_PROGNAME@ apply - 1 dst
+@IMAGEX_PROGNAME@ capture src - | @IMAGEX_PROGNAME@ apply - dst
.RE
.PP
.SH SEE ALSO