-.TH IMAGEX "1" "April 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 \fI[PATH\fR]... [\fIOPTION\fR]...
-
+\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
-.PP
-
\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
NTFS volume, use \fB@IMAGEX_PROGNAME@ apply\fR (1) instead.
-
+.PP
\fIIMAGE\fR specifies the image in \fIWIMFILE\fR that contains the files or
directory trees to extract. It may be a 1-based index of an image in the WIM or
the name of an image in the WIM. Use the \fB@IMAGEX_PROGNAME@ info\fR (1)
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.
-
+\fB--dest-dir\fR to choose an alternate target directory. Alternatively, use
+\fB--to-stdout\fR to extract a file to standard output to pipe into another
+program.
+.PP
\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 overridden 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
way as in other commands such as \fB@IMAGEX_PROGNAME@ apply\fR. See
\fB@IMAGEX_PROGNAME@ apply\fR (1) for more details.
-
.SH OPTIONS
.TP 6
\fB--check\fR
-When reading \fIWIMFILE\fR, verify its integrity if the integrity table is
+When reading \fIWIMFILE\fR, verify its integrity if an integrity table is
present.
.TP
-\fB--verbose\fR
-Print the path to of each file or directory within the WIM image as it is
-extracted.
-.TP
\fB--ref\fR="\fIGLOB\fR"
-File glob of additional split WIM parts that are part of the split WIM. See
-\fBSPLIT_WIMS\fR.
+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
-Restore the UNIX-specific data captured using \fB@IMAGEX_PROGNAME@ capture\fR
-with the \fB--unix-data\fR option. This option is only available on UNIX.
+See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
.TP
\fB--no-acls\fR
-Do not restore security descriptors on extracted files and directories.
+See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
.TP
\fB--strict-acls\fR
-Fail immediately if the full security descriptor of any file or directory cannot
-be set exactly as specified in the WIM file. The default behavior without this
-option is to fall back to setting a security descriptor with the SACL omitted,
-then only the default inherited security descriptor, if we do not have
-permission to set the desired one.
+See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
+.TP
+\fB--no-attributes\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
directories or reparse points). If present, alternate data streams are not
extracted.
-
+.TP
+\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
-
-\fB@IMAGEX_PROGNAME@ extract\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. Thus, it should provide assurance of data integrity.
-
+See the documentation \fB@IMAGEX_PROGNAME@ apply\fR (1) for documentation about
+what data and metadata are extracted on UNIX-like systems versus on Windows.
+.PP
+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
point within the extraction location) are never done by \fB@IMAGEX_PROGNAME@
extract\fR. Use \fB@IMAGEX_PROGNAME@ apply\fR if you want this behavior.
-
+.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.
-
-Not all data and metadata contained in each WIM \fIPATH\fR will necessarily be
-extracted, since \fB@IMAGEX_PROGNAME@ extract\fR does the best it can given the
-platform (UNIX or Windows) and supported features of the filesystem. The
-documentation for \fB@IMAGEX_PROGNAME@ apply\fR (1) goes into more detail about
-what data and metadata is extracted and what is not.
-
+.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)
.BR @IMAGEX_PROGNAME@-dir (1)
.BR @IMAGEX_PROGNAME@-info (1)
+.BR @IMAGEX_PROGNAME@-mount (1)
git://wimlib.net / wimlib / blobdiff