.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 | @\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
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
If no additional arguments are given, the entire WIM image is extracted.
Otherwise, each additional argument is interpreted as a \fIPATH\fR if it does
not begin with the '@' character, or a \fILISTFILE\fR if it does.  Each
\fIPATH\fR specifies a file or directory tree within the WIM image to extract,
whereas each \fILISTFILE\fR specifies a file that itself contains a list of
paths to extract.  See \fBPATHS AND LISTFILES\fR for more details.
.PP
By default, files and directories are extracted to the current directory.  Use
\fB--dest-dir\fR to select a different destination directory.  Alternatively,
use \fB--to-stdout\fR to extract a file to standard output to pipe into another
program.
.PP
A file or directory extracted from a \fIPATH\fR argument is by default extracted
directly into the destination directory, whereas a file or directory extracted
from a \fILISTFILE\fR argument is by default extracted into the destination
directory in such a way that the archive's directory structure is
preserved.  Use \fB--preserve-dir-structure\fR to always get the latter
behavior.
.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 PATHS AND LISTFILES
Each path, including those on the command line and those in listfiles, 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.
.PP
On Windows, by default paths are treated case-insensitively, whereas on
UNIX-like systems, by default paths are treated case-sensitively.  In either
case, the default behavior may be overridden through the
\fBWIMLIB_IMAGEX_IGNORE_CASE\fR environmental variable, as documented in
\fB@IMAGEX_PROGNAME@\fR (1).
.PP
By default, each path may contain the wildcard characters '?' and '*'.  The '?'
character matches any non-path-separator character, whereas the '*' character
matches zero or more non-path-separator characters.  Consequently, a single
wildcard pattern may expand to multiple actual files or directories.  Use the
\fB--no-wildcards\fR option to disable wildcard matching and search for each
path literally.
.PP
Each \fILISTFILE\fR must be a UTF-8 text file that contains a list of paths to
extract, one per line.  Wildcard characters are allowed by default.  The
following demonstrates an example listfile:
.PP
.RS
.nf

; This is a comment (begins with semicolon)
/Users
/Windows/explorer.exe
/Windows/System32/en-US/*

; Both forward and backslashes are valid.
; Don't quote paths containing spaces.
\\Program Files\\A*

; Leading and trailing whitespace is ignored
    \\Windows\\notepad*

.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 an integrity table is
present.
.TP
\fB--ref\fR="\fIGLOB\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--dest-dir\fR=\fIDIR\fR
Extract the files and directories to the directory \fIDIR\fR instead of to the
current working directory.
.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 paths are to regular files (not
directories or reparse points).  If present, alternate data streams are not
extracted.
.TP
\fB--unix-data\fR
See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
.TP
\fB--no-acls\fR
See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
.TP
\fB--strict-acls\fR
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--no-wildcards\fR
Do not interpret wildcard characters in paths.  Each path will be searched for
literally.
.TP
\fB--nullglob\fR
If a wildcard pattern (a.k.a. a "glob") does not match any paths, ignore it and
print a warning instead of failing with an error.  In other words, this option
allows a wildcard pattern to successfully match zero files.  Note that this
applies even if one of the paths does not contain wildcard characters.  Such a
path is still treated as a "wildcard pattern", so with this option it may not
match anything and therefore produce no error.  This option cannot be combined
with \fB--no-wildcards\fR, as that would be meaningless.
.TP
\fB--preserve-dir-structure\fR
When extracting paths, preserve the archive directory structure instead of
extracting the file or directory tree named by each path directly to the
destination directory.  Note: \fB--preserve-dir-structure\fR is already the
default behavior for paths in listfiles, but not paths directly specified on the
command line.
.SH NOTES
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.
.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
.PP
@IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/System32/notepad.exe
.RE
.PP
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 \\
.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 \\
.br
.RS
--dest-dir=somedir
.RE
.RE
.PP
Extract the "sources" directory from the first image in "boot.wim" to the
current directory:
.RS
.PP
@IMAGEX_PROGNAME@ extract boot.wim 1 /sources
.RE
.PP
Extract multiple files and directories in one command:
.RS
.PP
@IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/Fonts \\
.br
.RS
/sources /Windows/System32/cmd.exe
.RE
.RE
.PP
Extract many files to the current directory using a wildcard pattern:
.RS
.PP
@IMAGEX_PROGNAME@ extract install.wim 1 "/Windows/Fonts/*.ttf"
.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)