wimlib.net Git - wimlib/blob - doc/imagex-extract.1.in

   1 .TH WIMLIB-IMAGEX "1" "December 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
   2 .SH NAME
   3 @IMAGEX_PROGNAME@-extract \- Extract files or directories from a WIM image
   4 .SH SYNOPSIS
   5 \fB@IMAGEX_PROGNAME@ extract\fR \fIWIMFILE\fR \fIIMAGE\fR [\fIPATH\fR...]  [\fIOPTION\fR...]
   6 .br
   7 \fB@IMAGEX_PROGNAME@ extract\fR \fIWIMFILE\fR \fIIMAGE\fR @\fILISTFILE\fR  [\fIOPTION\fR...]
   8 .SH DESCRIPTION
   9 \fB@IMAGEX_PROGNAME@ extract\fR extracts one or more files or directory trees
  10 from the specified \fIIMAGE\fR contained in the Windows Imaging (WIM) file
  11 \fIWIMFILE\fR.
  12 This command is also available as simply \fBwimextract\fR if the appropriate hard
  13 link or batch file has been installed.
  14 .PP
  15 \fB@IMAGEX_PROGNAME@ extract\fR is intended for extracting only a subset of a
  16 WIM image.  If you want to extract or "apply" a full WIM image to a directory or
  17 NTFS volume, use \fB@IMAGEX_PROGNAME@ apply\fR (1) instead.
  18 .PP
  19 \fIIMAGE\fR specifies the image in \fIWIMFILE\fR that contains the files or
  20 directory trees to extract.  It may be a 1-based index of an image in the WIM or
  21 the name of an image in the WIM.  Use the \fB@IMAGEX_PROGNAME@ info\fR (1)
  22 command to show what images a WIM file contains.
  23 .PP
  24 Each \fIPATH\fR specifies a file or directory tree within the WIM image to
  25 extract.  Alternatively, a single \fILISTFILE\fR beginning with the '@'
  26 character is taken as a file that itself contains a list of files or directory
  27 trees to extract.  See \fBPATH_SPECIFICATIONS\fR.
  28 .PP
  29 By default, files and directories are extracted to the current directory.  Use
  30 \fB--dest-dir\fR to choose an alternate target directory.  Alternatively, use
  31 \fB--to-stdout\fR to extract a file to standard output to pipe into another
  32 program.
  33 .PP
  34 \fB@IMAGEX_PROGNAME@ extract\fR supports extracting files and directory trees
  35 from stand-alone WIMs as well as split WIMs.  See \fBSPLIT WIMS\fR.
  36 .SH PATH SPECIFICATIONS
  37 Except when a single path is specified and prefixd by the '@' character, each
  38 \fIPATH\fR specifies a file or directory tree within the WIM image to extract.
  39 Each such path must be specified as an absolute path starting from the root of
  40 the WIM image, like those output by the \fB@IMAGEX_PROGNAME@ dir\fR (1) command.
  41 However, path separators may be either forward or backward slashes, and the
  42 leading slash is optional; also, on Windows, the paths are treated
  43 case-insensitively, while on UNIX, paths are treated case-sensitively.
  44 .PP
  45 If no \fIPATH\fRs are provided, the default behavior is to extract the full
  46 image, as if the path "/" had been provided.
  47 .PP
  48 If a single \fIPATH\fR is provided and is prefixed with the '@' character, it is
  49 interpreted as the path to a \fILISTFILE\fR which must be a UTF-8 text file that
  50 contains a list of paths (files or directories) to extract, one per line.  In
  51 each line, leading and trailing whitespace is ignored, and lines beginning with
  52 the ';' character and otherwise empty lines are ignored.  Each path must be
  53 unquoted and must specify a full path in the WIM image, as described above.
  54 However, unless \fB--no-wildcards\fR is specified, each path in the list file
  55 may also contain the wildcard characters '?' and '*', and therefore may expand
  56 to multiple actual files or directories.  By default, paths or wildcards that
  57 match no wildcards only produce a warning; use \fB--strict-wildcards\fR if you
  58 want an error instead.  Also, when using a list file, files and directories not
  59 located at the root of the WIM image will be extracted to a corresponding
  60 subdirectory of the destination directory rather than directly to the
  61 destination directory itself.
  62 .SH SPLIT WIMS
  63 You may use \fB@IMAGEX_PROGNAME@ extract\fR to extract files or directory trees
  64 from a split WIM.  This uses the \fB--refs\fR="\fIGLOB\fR" option in the same
  65 way as in other commands such as \fB@IMAGEX_PROGNAME@ apply\fR.  See
  66 \fB@IMAGEX_PROGNAME@ apply\fR (1) for more details.
  67 .SH OPTIONS
  68 .TP 6
  69 \fB--check\fR
  70 When reading \fIWIMFILE\fR, verify its integrity if an integrity table is
  71 present.
  72 .TP
  73 \fB--ref\fR="\fIGLOB\fR"
  74 File glob of additional WIMs or split WIM parts to reference resources from.
  75 See \fBSPLIT_WIMS\fR.  Note: \fIGLOB\fR is listed in quotes because it is
  76 interpreted by \fB@IMAGEX_PROGNAME@\fR and may need to be quoted to protect
  77 against shell expansion.
  78 .TP
  79 \fB--unix-data\fR
  80 See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
  81 .TP
  82 \fB--no-acls\fR
  83 See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
  84 .TP
  85 \fB--strict-acls\fR
  86 See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
  87 .TP
  88 \fB--include-invalid-names\fR
  89 See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
  90 .TP
  91 \fB--to-stdout\fR
  92 Extract the files to standard output instead of to the filesystem.  This can
  93 only be provided if all the specified \fIPATH\fRs are to regular files (not
  94 directories or reparse points).  If present, alternate data streams are not
  95 extracted.
  96 .TP
  97 \fB--dest-dir\fR=\fIDIR\fR
  98 Extract the files and directories to the directory \fIDIR\fR instead of to the
  99 current working directory.
 100 .TP
 101 \fB--no-wildcards\fR
 102 Do not interpret wildcard characters in paths in the \fILISTFILE\fR.
 103 .TP
 104 \fB--strict-wildcards\fR
 105 Fail if any wildcards or paths in \fILISTFILE\fR do not match any files in the
 106 WIM image.  The default behavior is to warn only.
 107 .TP
 108 \fB--case-insensitive-wildcards\fR
 109 Treat the wildcards or paths in \fILISTFILE\fR as case-insensitive.  On Windows
 110 this is already the default behavior, but on UNIX-like systems it is not.
 111 .SH NOTES
 112 See the documentation \fB@IMAGEX_PROGNAME@ apply\fR (1) for documentation about
 113 what data and metadata are extracted on UNIX-like systems versus on Windows.
 114 .PP
 115 On UNIX-like systems that support userspace filesystems with FUSE (e.g. Linux),
 116 one can alternatively mount the WIM image with \fB@IMAGEX_PROGNAME@ mount\fR (1)
 117 and then extract the desired files or directories using any standard
 118 command-line or graphical program.
 119 .PP
 120 Reparse-point fixups (a.k.a. changing absolute symbolic links and junctions to
 121 point within the extraction location) are never done by \fB@IMAGEX_PROGNAME@
 122 extract\fR.  Use \fB@IMAGEX_PROGNAME@ apply\fR if you want this behavior.
 123 .PP
 124 Unlike \fB@IMAGEX_PROGNAME@ apply\fR, \fB@IMAGEX_PROGNAME@ extract\fR does not
 125 support extracting files directly to a NTFS volume using libntfs-3g.
 126 .PP
 127 wimlib v1.6.0 and later can extract files from version 3584 WIMs, which usually
 128 use packed, LZMS-compressed streams and may carry the \fI.esd\fR file extension
 129 rather than \fI.wim\fR.  However, \fI.esd\fR files downloaded directly by the
 130 Windows 8 web downloader have encrypted segments, and wimlib cannot extract such
 131 files until they are first decrypted.  Furthermore, such files are not designed
 132 for random access, so extracting individual files from them may be slow.
 133 .SH EXAMPLES
 134 Extract a file from the first image in "boot.wim" to the current directory:
 135 .RS
 136 .PP
 137 @IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/System32/notepad.exe
 138 .RE
 139 .PP
 140 Extract a file from the first image in "boot.wim" to standard output:
 141 .RS
 142 .PP
 143 @IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/System32/notepad.exe \\
 144 .br
 145 .RS
 146 --to-stdout
 147 .RE
 148 .RE
 149 .PP
 150 Extract a file from the first image in "boot.wim" to the specified directory:
 151 .RS
 152 .PP
 153 @IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/System32/notepad.exe \\
 154 .br
 155 .RS
 156 --dest-dir=somedir
 157 .RE
 158 .RE
 159 .PP
 160 Extract the "sources" directory from the first image in "boot.wim" to the
 161 current directory:
 162 .RS
 163 .PP
 164 @IMAGEX_PROGNAME@ extract boot.wim 1 /sources
 165 .RE
 166 .PP
 167 Extract multiple files and directories in one command:
 168 .RS
 169 .PP
 170 @IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/Fonts \\
 171 .br
 172 .RS
 173 /sources /Windows/System32/cmd.exe
 174 .RE
 175 .RE
 176 .PP
 177 Extract files using a list file:
 178 .RS
 179 .PP
 180 @IMAGEX_PROGNAME@ extract install.wim 1 @files.txt
 181 .RE
 182 .PP
 183  ...  where files.txt could be something like:
 184 .PP
 185 .RS
 186 .RS
 187 .nf
 188 Windows\\System32\\*.*
 189 Windows\\System32\\??-??\\*.*
 190 Windows\\System32\\en-US\\*.*
 191 .RE
 192 .RE
 193 .fi
 194 .SH SEE ALSO
 195 .BR @IMAGEX_PROGNAME@ (1)
 196 .BR @IMAGEX_PROGNAME@-apply (1)
 197 .BR @IMAGEX_PROGNAME@-dir (1)
 198 .BR @IMAGEX_PROGNAME@-info (1)
 199 .BR @IMAGEX_PROGNAME@-mount (1)