-.TH IMAGEX "1" "August 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...]
+\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 is installed.
+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
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.
+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 choose an alternate target directory. Alternatively, use
-\fB--to-stdout\fR to extract a file to standard output to pipe into another
+\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 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. 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.
-.PP
-If no \fIPATH\fRs are provided, the default behavior is to extract the full
-image, as if the path "/" had been provided.
+.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
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.
+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--verbose\fR
-Print the path of each file or directory within the WIM image as it is
+\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
\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--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.
+\fB--no-wildcards\fR
+Do not interpret wildcard characters in paths. Each path will be searched for
+literally.
.TP
-\fB--dest-dir\fR=\fIDIR\fR
-Extract the files and directories to the directory \fIDIR\fR instead of to the
-current working directory.
+\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 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 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)
git://wimlib.net / wimlib / blobdiff