X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=doc%2Fimagex-extract.1.in;h=9a9e1592032593a150be23fb4cf997fbe182494b;hp=fceb86f732b7d27bca492a21fa8ed1344e44bf25;hb=2f1f50993984f88df675f0c3302cf4fa52982f05;hpb=4a7d507821b3134360b4c1243e650d781bf38dc0 diff --git a/doc/imagex-extract.1.in b/doc/imagex-extract.1.in index fceb86f7..9a9e1592 100644 --- a/doc/imagex-extract.1.in +++ b/doc/imagex-extract.1.in @@ -1,68 +1,86 @@ -.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 -.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. 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--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 to 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). @@ -73,6 +91,12 @@ 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--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 @@ -82,23 +106,38 @@ extracted. \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. - -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 +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 @@ -109,13 +148,21 @@ Extract a file from the first image in "boot.wim" to the current directory: 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 @@ -128,10 +175,30 @@ current directory: 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)