-.TH IMAGEX "1" "May 2012" "imagex (wimlib) wimlib @VERSION@" "User Commands"
+.TH IMAGEX "1" "January 2013" "imagex (wimlib) wimlib @VERSION@" "User Commands"
.SH NAME
-imagex apply \- Extract one image, or all images, from a WIM archive
+imagex-apply \- Extract one image, or all images, from a WIM archive
.SH SYNOPSIS
\fBimagex apply\fR \fIWIMFILE\fR \fIIMAGE\fR \fITARGET\fR [\fIOPTION\fR]...
\fBimagex apply\fR extracts an image, or all images, from the Windows Imaging
(WIM) file \fIWIMFILE\fR.
-\fIIMAGE\fR specifies the image to extract. It may be a 1-based index of an
+\fIIMAGE\fR specifies the WIM image to extract. It may be a 1-based index of an
image in the WIM, the name of an image in the WIM, or the keyword "all" to
indicate that all images are to be extracted. Use the \fBimagex info\fR (1)
command to show what images a WIM file contains.
-\fBTARGET\fR specifies where to extract the WIM image(s) to. If \fBTARGET\fR
+\fITARGET\fR specifies where to extract the WIM image(s) to. If \fITARGET\fR
specifies a directory, the WIM image(s) are extracted to that directory. If
-\fBTARGET\fR specifies a non-existent file, a directory is created in that
-location and the WIM image(s) are extracted to that directory. If \fBTARGET\fR
+\fITARGET\fR specifies a non-existent file, a directory is created in that
+location and the WIM image(s) are extracted to that directory. If \fITARGET\fR
specifies a regular file or block device, it is interpreted as a NTFS volume to
which the WIM image is to be extracted.
+\fBimagex apply\fR supports applying images from stand-alone WIMs as well as
+split WIMs. See \fBSPLIT WIMS\fR.
+
.SH NORMAL MODE
-The normal extraction mode is entered when \fBTARGET\fR is a directory or
-non-existent file. If a single WIM image is being extracted, it will be
-extracted with the root of the image corresponding to the directory named by
-\fBTARGET\fR; or, if the keyword \fBall\fR is given, the images are extracted
-into subdirectories of \fITARGET\fR that will be named after the image names,
-falling back to the image indices if there is an image with no name.
+The normal extraction mode is entered when \fITARGET\fR is a directory or
+non-existent file. If a single WIM image is being extracted, it is extracted
+with the root directory of the image corresponding to the directory named by
+\fITARGET\fR; or, if the keyword \fBall\fR is given, the images are extracted
+into subdirectories of \fITARGET\fR that are be named after the image names,
+falling back to the image index for an image with no name. \fITARGET\fR can
+specify a directory on any type of filesystem.
-In the normal mode of extraction, the following information will be extracted
-from the WIM image(s):
+In the normal mode of extraction, the following information is extracted from
+the WIM image(s):
.IP \[bu] 4
-The default (unnamed) data streams of each file
+The default (unnamed) data stream of each file
.IP \[bu]
-Hard links, if supported by the underlying filesystem
+Hard links
.IP \[bu]
File and directory creation, access, and modification timestamps to the nearest
microsecond, if supported by the underlying filesystem
.SH NTFS MODE
-A special extraction mode is entered when \fBTARGET\fR is a regular file or
-block device. \fBTARGET\fR is interpreted as an NTFS volume and opened using
-libntfs-3g. If successful, the WIM image is extracted to the root of the NTFS
-volume in a special mode that preserves all, or almost all, information
-contained in the WIM. \fBIMAGE\fR may not be "all" for this action.
+A special extraction mode is entered when \fITARGET\fR is a regular file or
+block device. If this is the case, \fITARGET\fR is interpreted as an NTFS
+volume and opened using libntfs-3g. If successful, the WIM image is extracted
+to the root of the NTFS volume in a special mode that preserves all information
+contained in the WIM image. \fIIMAGE\fR may not be "all" for this action.
The NTFS volume does not need to be empty, although it's expected that it be
empty for the intended use cases. A new NTFS filesystem can be created using
The NTFS extraction mode is not available if wimlib was compiled using the
--without-ntfs-3g option.
+Please note that the NTFS extraction mode is \fInot\fR entered if \fITARGET\fR
+is a directory, even if a NTFS filesystem is mounted on \fITARGET\fR. You must
+specify the NTFS volume itself (and it must be unmounted, and you must have
+permission to write to it).
+
In the NTFS extraction mode, the following information will be extracted from
the WIM image:
.PP
-In the NTFS extraction mode, we restore enough information from the WIM that it
-is possible, in most cases, to restore or install an image of an actual Windows
-installation. In the examples at the end of this manual page, we show an example
-of applying an image from the "install.wim" file contained in the installation
-media for Windows Vista, Windows 7, and Windows 8 in the "sources" directory.
+Since all information from the WIM image is restored in the NTFS extraction
+mode, it is possible to restore an image of an actual Windows installation. In
+the examples at the end of this manual page, there is an example of applying an
+image from the "install.wim" file contained in the installation media for
+Windows Vista, Windows 7, and Windows 8 in the "sources" directory.
-In order to actually boot Windows from an applied image, you must understand the
-boot process of Windows versions Vista and later. Basically, it is the
+But in order to actually boot Windows from an applied image, you must understand
+the boot process of Windows versions Vista and later. Basically, it is the
following:
.nr step 1 1
bootable flag on it, and have a master boot record that loads the bootable
partition (Windows' MBR does, and SYSLINUX provides an equivalent MBR).
+.SH SPLIT WIMS
+
+You may use \fBimagex 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).
+
+Here's an example. The names for the split WIMs usually go something like:
+
+.RS
+.PP
+.nf
+mywim.swm
+mywim2.swm
+mywim3.swm
+mywim4.swm
+mywim5.swm
+.RE
+
+To apply the first image of this split WIM to the directory "dir", run:
+.PP
+.RS
+imagex apply mywim.swm 1 dir --ref="mywim*.swm"
+.RE
+.PP
+
.SH OPTIONS
.TP 6
\fB--check\fR
.TP
\fB--hardlink\fR
When extracting a file from the WIM that is identical to a file that has already
-extracted, create a hard link using \fBlink\fR (3) rather than creating a
-separate file. This option causes all identical files to be hard-linked,
-overriding the hard link groups that are specified in the WIM image(s). In the
-case of extracting all images from the WIM, files may be hard-linked even if
-they are in different WIM images. This option is not available in the NTFS
-extraction mode.
+extracted, create a hard link rather than creating a separate file. This option
+causes all identical files to be hard-linked, overriding the hard link groups
+that are specified in the WIM image(s). In the case of extracting all images
+from the WIM, files may be hard-linked even if they are in different WIM images.
+This option is not available in the NTFS extraction mode.
.TP
\fB--symlink\fR
This option is similar to \fB--hardlink\fR, except symbolic links are created
\fB--verbose\fR
Print the path to of each file or directory within the WIM image as it is
extracted, and some additional informational messages.
+.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.
+
+.SH NOTES
+
+\fBimagex apply\fR calculates the SHA1 message digest of every file stream it
+extracts and verifies that it is the same as the SHA1 message digest provided in
+the WIM file. It is an error if the message digests don't match. It's also
+considered to be an error if any WIM resources cannot be found in the stream
+lookup table. So you can be fairly certain that the file streams are extracted
+correctly, even though \fBimagex apply\fR don't have a \fB/verify\fR option like
+Microsoft's version of imagex does. Please note that this is separate from the
+integrity table of the WIM, which provides SHA1 message digests over raw chunks
+of the entire WIM file and is checked separately if the \fB--check\fR option is
+specified.
+
+You cannot use \fBimagex apply\fR to apply a WIM from a pipe (such as standard
+input) because the WIM file format is not designed for this.
.SH EXAMPLES
.SS Normal extraction mode
.RE
.PP
.SS NTFS extraction mode
-Verbosely apply a WIM image to a NTFS filesystem image:
+Apply a WIM image to a NTFS filesystem image:
.RS
.PP
-imagex apply mywim.wim 1 fsimage.ntfs --verbose
+imagex apply mywim.wim 1 fsimage.ntfs
.RE
.PP
Create a new NTFS filesystem on the partition /dev/sda2 and apply the first
git://wimlib.net / wimlib / blobdiff