-.TH IMAGEX "1" "May 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
+.TH WIMLIB-IMAGEX "1" "January 2014" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
.SH NAME
@IMAGEX_PROGNAME@-extract \- Extract files or directories from a WIM image
.SH SYNOPSIS
\fB@IMAGEX_PROGNAME@ extract\fR \fIWIMFILE\fR \fIIMAGE\fR [\fIPATH\fR...] [\fIOPTION\fR...]
+.br
+\fB@IMAGEX_PROGNAME@ extract\fR \fIWIMFILE\fR \fIIMAGE\fR @\fILISTFILE\fR [\fIOPTION\fR...]
.SH DESCRIPTION
\fB@IMAGEX_PROGNAME@ extract\fR extracts one or more files or directory trees
from the specified \fIIMAGE\fR contained in the Windows Imaging (WIM) file
\fIWIMFILE\fR.
+This command is also available as simply \fBwimextract\fR if the appropriate hard
+link or batch file has been installed.
.PP
\fB@IMAGEX_PROGNAME@ extract\fR is intended for extracting only a subset of a
WIM image. If you want to extract or "apply" a full WIM image to a directory or
command to show what images a WIM file contains.
.PP
Each \fIPATH\fR specifies a file or directory tree within the WIM image to
-extract. See \fBPATH_SPECIFICATIONS\fR.
+extract. Alternatively, a single \fILISTFILE\fR beginning with the '@'
+character is taken as a file that itself contains a list of files or directory
+trees to extract. See \fBPATH_SPECIFICATIONS\fR.
.PP
By default, files and directories are extracted to the current directory. Use
\fB--dest-dir\fR to choose an alternate target directory. Alternatively, use
\fB@IMAGEX_PROGNAME@ extract\fR supports extracting files and directory trees
from stand-alone WIMs as well as split WIMs. See \fBSPLIT WIMS\fR.
.SH PATH SPECIFICATIONS
-Each \fIPATH\fR specifies a file or directory tree within the WIM image to
-extract. Each path must be specified as an absolute path starting from the root
-of the WIM image, like those output by the \fB@IMAGEX_PROGNAME@ dir\fR (1)
-command. Path separators may be forward slashes on UNIX, or either forward
-slashes or backward slashes on Windows. The leading slash is optional.
+Except when a single path is specified and prefixd by the '@' character, each
+\fIPATH\fR specifies a file or directory tree within the WIM image to extract.
+Each such path must be specified as an absolute path starting from the root of
+the WIM image, like those output by the \fB@IMAGEX_PROGNAME@ dir\fR (1) command.
+However, path separators may be either forward or backward slashes, and the
+leading slash is optional; also, on Windows, the paths are treated
+case-insensitively, while on UNIX, paths are treated case-sensitively, except
+when overwritten through the \fBWIMLIB_IMAGEX_IGNORE_CASE\fR environmental
+variable, as documented in \fB@IMAGEX_PROGNAME@\fR (1).
.PP
If no \fIPATH\fRs are provided, the default behavior is to extract the full
image, as if the path "/" had been provided.
+.PP
+If a single \fIPATH\fR is provided and is prefixed with the '@' character, it is
+interpreted as the path to a \fILISTFILE\fR which must be a UTF-8 text file that
+contains a list of paths (files or directories) to extract, one per line. In
+each line, leading and trailing whitespace is ignored, and lines beginning with
+the ';' character and otherwise empty lines are ignored. Each path must be
+unquoted and must specify a full path in the WIM image, as described above.
+However, unless \fB--no-wildcards\fR is specified, each path in the list file
+may also contain the wildcard characters '?' and '*'. The '?' character matches
+any character other than a path separator, whereas the '*' character matches
+zero or more non-path-separator characters. Consequently, a single wildcard
+pattern may expand to multiple actual files or directories.
+.PP
+In the \fILISTFILE\fR mode, by default a wildcard pattern that matches no files
+or directories in the WIM image only produces a warning; use
+\fB--strict-wildcards\fR if you want an error instead. Also, when using a list
+file, files and directories not located at the root of the WIM image will be
+extracted to a corresponding subdirectory of the destination directory rather
+than directly to the destination directory itself.
.SH SPLIT WIMS
You may use \fB@IMAGEX_PROGNAME@ extract\fR to extract files or directory trees
from a split WIM. This uses the \fB--refs\fR="\fIGLOB\fR" option in the same
present.
.TP
\fB--ref\fR="\fIGLOB\fR"
-File glob of additional split WIM parts that are part of the split WIM. See
-\fBSPLIT_WIMS\fR.
-.TP
-\fB--verbose\fR
-Print the path of each file or directory within the WIM image as it is
-extracted.
+File glob of additional WIMs or split WIM parts to reference resources from.
+See \fBSPLIT_WIMS\fR. 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--unix-data\fR
See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
\fB--strict-acls\fR
See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
.TP
+\fB--include-invalid-names\fR
+See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
+.TP
\fB--to-stdout\fR
Extract the files to standard output instead of to the filesystem. This can
only be provided if all the specified \fIPATH\fRs are to regular files (not
\fB--dest-dir\fR=\fIDIR\fR
Extract the files and directories to the directory \fIDIR\fR instead of to the
current working directory.
+.TP
+\fB--no-wildcards\fR
+Do not interpret wildcard characters in paths in the \fILISTFILE\fR.
+.TP
+\fB--strict-wildcards\fR
+Fail if any wildcard patterns in \fILISTFILE\fR do not match any files or
+directories in the WIM image. The default behavior is to warn only. This
+option has no effect if \fB--no-wildcards\fR is also specified or if \fIPATH\fRs
+are specified instead of a \fILISTFILE\fR; in those cases, an error is issued if
+any file to extract does not exist.
.SH NOTES
See the documentation \fB@IMAGEX_PROGNAME@ apply\fR (1) for documentation about
-what data and metadata are extracted on UNIX versus on Windows.
+what data and metadata are extracted on UNIX-like systems versus on Windows.
.PP
-On UNIX, one can alternatively mount the WIM image with \fB@IMAGEX_PROGNAME@
-mount\fR and then extract the desired files or directories using any standard
+On UNIX-like systems that support userspace filesystems with FUSE (e.g. Linux),
+one can alternatively mount the WIM image with \fB@IMAGEX_PROGNAME@ mount\fR (1)
+and then extract the desired files or directories using any standard
command-line or graphical program.
.PP
Reparse-point fixups (a.k.a. changing absolute symbolic links and junctions to
.PP
Unlike \fB@IMAGEX_PROGNAME@ apply\fR, \fB@IMAGEX_PROGNAME@ extract\fR does not
support extracting files directly to a NTFS volume using libntfs-3g.
+.PP
+wimlib v1.6.0 and later can extract files from version 3584 WIMs, which usually
+use packed, LZMS-compressed streams and may carry the \fI.esd\fR file extension
+rather than \fI.wim\fR. However, \fI.esd\fR files downloaded directly by the
+Windows 8 web downloader have encrypted segments, and wimlib cannot extract such
+files until they are first decrypted. Furthermore, such files are not designed
+for random access, so extracting individual files from them may be slow.
.SH EXAMPLES
Extract a file from the first image in "boot.wim" to the current directory:
.RS
Extract a file from the first image in "boot.wim" to standard output:
.RS
.PP
-@IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/System32/notepad.exe --to-stdout
+@IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/System32/notepad.exe \\
+.br
+.RS
+--to-stdout
+.RE
.RE
.PP
Extract a file from the first image in "boot.wim" to the specified directory:
.RS
.PP
-@IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/System32/notepad.exe --dest-dir=somedir
+@IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/System32/notepad.exe \\
+.br
+.RS
+--dest-dir=somedir
+.RE
.RE
.PP
Extract the "sources" directory from the first image in "boot.wim" to the
Extract multiple files and directories in one command:
.RS
.PP
-@IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/Fonts /sources /Windows/System32/cmd.exe
+@IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/Fonts \\
+.br
+.RS
+/sources /Windows/System32/cmd.exe
+.RE
+.RE
+.PP
+Extract files using a list file:
+.RS
+.PP
+@IMAGEX_PROGNAME@ extract install.wim 1 @files.txt
.RE
.PP
+ ... where files.txt could be something like:
+.PP
+.RS
+.RS
+.nf
+Windows\\System32\\*.*
+Windows\\System32\\??-??\\*.*
+Windows\\System32\\en-US\\*.*
+.RE
+.RE
+.fi
.SH SEE ALSO
.BR @IMAGEX_PROGNAME@ (1)
.BR @IMAGEX_PROGNAME@-apply (1)