X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=doc%2Fimagex-extract.1.in;h=a7dfd0758d01057f2d2ee5788fc4f2413a33d553;hp=cf49abd1f51b57a0302d20e5b43a1fe8b3ee32c5;hb=be9a6f902c595bd33b4d2e7ec864e9171020dd3a;hpb=b6f6a919c8291da9cf2a9ea72ec7f8e47fbd79cf diff --git a/doc/imagex-extract.1.in b/doc/imagex-extract.1.in index cf49abd1..a7dfd075 100644 --- a/doc/imagex-extract.1.in +++ b/doc/imagex-extract.1.in @@ -1,12 +1,14 @@ -.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...] +\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 @@ -17,27 +19,66 @@ 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. +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. Path separators may be forward slashes on UNIX, or either forward -slashes or backward slashes on Windows. The leading slash is optional. 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 @@ -50,11 +91,19 @@ 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. +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 @@ -66,24 +115,38 @@ 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 -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 @@ -92,6 +155,13 @@ 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 @@ -102,13 +172,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 @@ -121,9 +199,36 @@ 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 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)