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

   1 .TH WIMLIB-IMAGEX "1" "May 2015" "wimlib 1.8.1" "User Commands"
   2 .SH NAME
   3 wimlib-imagex-extract \- Extract files or directories from a WIM image
   4 .SH SYNOPSIS
   5 \fBwimlib-imagex extract\fR \fIWIMFILE\fR \fIIMAGE\fR [(\fIPATH\fR | @\fILISTFILE\fR)...]  [\fIOPTION\fR...]
   6 .SH DESCRIPTION
   7 \fBwimlib-imagex extract\fR extracts one or more files or directory trees
   8 from the specified \fIIMAGE\fR contained in the Windows Imaging (WIM) file
   9 \fIWIMFILE\fR.
  10 This command is also available as simply \fBwimextract\fR if the appropriate hard
  11 link or batch file has been installed.
  12 .PP
  13 \fBwimlib-imagex extract\fR is intended for extracting only a subset of a
  14 WIM image.  If you want to extract or "apply" a full WIM image to a directory or
  15 NTFS volume, use \fBwimlib-imagex apply\fR (1) instead.
  16 .PP
  17 \fIIMAGE\fR specifies the image in \fIWIMFILE\fR that contains the files or
  18 directory trees to extract.  It may be a 1-based index of an image in the WIM or
  19 the name of an image in the WIM.  Use the \fBwimlib-imagex info\fR (1)
  20 command to show what images a WIM file contains.
  21 .PP
  22 If no additional arguments are given, the entire WIM image is extracted.
  23 Otherwise, each additional argument is interpreted as a \fIPATH\fR if it does
  24 not begin with the '@' character, or a \fILISTFILE\fR if it does.  Each
  25 \fIPATH\fR specifies a file or directory tree within the WIM image to extract,
  26 whereas each \fILISTFILE\fR specifies a file that itself contains a list of
  27 paths to extract.  See \fBPATHS AND LISTFILES\fR for more details.
  28 .PP
  29 By default, files and directories are extracted to the current directory.  Use
  30 \fB--dest-dir\fR to select a different destination directory.  Alternatively,
  31 use \fB--to-stdout\fR to extract a file to standard output to pipe into another
  32 program.
  33 .PP
  34 A file or directory extracted from a \fIPATH\fR argument is by default extracted
  35 directly into the destination directory, whereas a file or directory extracted
  36 from a \fILISTFILE\fR argument is by default extracted into the destination
  37 directory in such a way that the archive's directory structure is
  38 preserved.  Use \fB--preserve-dir-structure\fR to always get the latter
  39 behavior.
  40 .PP
  41 \fBwimlib-imagex extract\fR supports extracting files and directory trees
  42 from stand-alone WIMs as well as split WIMs.  See \fBSPLIT WIMS\fR.
  43 .SH PATHS AND LISTFILES
  44 Each path, including those on the command line and those in listfiles, must be
  45 specified as an absolute path starting from the root of the WIM image, like
  46 those output by the \fBwimlib-imagex dir\fR (1) command.  However, path
  47 separators may be either forward or backward slashes, and the leading slash is
  48 optional.
  49 .PP
  50 On Windows, by default paths are treated case-insensitively, whereas on
  51 UNIX-like systems, by default paths are treated case-sensitively.  In either
  52 case, the default behavior may be overridden through the
  53 \fBWIMLIB_IMAGEX_IGNORE_CASE\fR environmental variable, as documented in
  54 \fBwimlib-imagex\fR (1).
  55 .PP
  56 By default, each path may contain the wildcard characters '?' and '*'.  The '?'
  57 character matches any non-path-separator character, whereas the '*' character
  58 matches zero or more non-path-separator characters.  Consequently, a single
  59 wildcard path, or "glob", may expand to multiple actual files or directories.
  60 Use the \fB--no-globs\fR option to disable wildcard matching and search for each
  61 path literally.
  62 .PP
  63 Each \fILISTFILE\fR must be a text file (UTF-8 or UTF-16LE encoded; plain ASCII
  64 is also fine) that
  65 contains a list of paths to extract, one per line.  Wildcard characters are
  66 allowed by default.  The following demonstrates an example listfile:
  67 .PP
  68 .RS
  69 .nf
  70
  71 ; This is a comment (begins with semicolon)
  72 # This is also a comment (begins with number sign)
  73 /Users
  74 /Windows/explorer.exe
  75 /Windows/System32/en-US/*
  76
  77 ; Both forward and backslashes are valid.
  78 ; It's not necessary to quote paths containing internal spaces.
  79 \\Program Files\\A*
  80
  81 ; Leading and trailing whitespace is ignored
  82     \\Windows\\notepad*
  83
  84 .SH SPLIT WIMS
  85 You may use \fBwimlib-imagex extract\fR to extract files or directory trees
  86 from a split WIM.  This uses the \fB--refs\fR="\fIGLOB\fR" option in the same
  87 way as in other commands such as \fBwimlib-imagex apply\fR.  See
  88 \fBwimlib-imagex apply\fR (1) for more details.
  89 .SH OPTIONS
  90 .TP 6
  91 \fB--check\fR
  92 When reading \fIWIMFILE\fR, verify its integrity if an integrity table is
  93 present.
  94 .TP
  95 \fB--ref\fR="\fIGLOB\fR"
  96 File glob of additional WIMs or split WIM parts to reference resources from.
  97 See \fBSPLIT_WIMS\fR.  Note: \fIGLOB\fR is listed in quotes because it is
  98 interpreted by \fBwimlib-imagex\fR and may need to be quoted to protect
  99 against shell expansion.
 100 .TP
 101 \fB--dest-dir\fR=\fIDIR\fR
 102 Extract the files and directories to the directory \fIDIR\fR instead of to the
 103 current working directory.
 104 .TP
 105 \fB--to-stdout\fR
 106 Extract the files to standard output instead of to the filesystem.  This can
 107 only be provided if all the specified paths are to regular files (not
 108 directories or reparse points).  If present, alternate data streams are not
 109 extracted.
 110 .TP
 111 \fB--unix-data\fR
 112 See the documentation for this option in \fBwimlib-imagex-apply\fR (1).
 113 .TP
 114 \fB--no-acls\fR
 115 See the documentation for this option in \fBwimlib-imagex-apply\fR (1).
 116 .TP
 117 \fB--strict-acls\fR
 118 See the documentation for this option in \fBwimlib-imagex-apply\fR (1).
 119 .TP
 120 \fB--no-attributes\fR
 121 See the documentation for this option in \fBwimlib-imagex-apply\fR (1).
 122 .TP
 123 \fB--include-invalid-names\fR
 124 See the documentation for this option in \fBwimlib-imagex-apply\fR (1).
 125 .TP
 126 \fB--no-globs\fR
 127 Do not recognize wildcard characters in paths.  Each path will be searched for
 128 literally.  In addition, if case insensitivity is enabled, do not allow a single
 129 path to match multiple files with the same case-insensitive name but different
 130 case-sensitive names.
 131 .IP
 132 \fB--no-wildcards\fR is also accepted as an alias for this option.
 133 .TP
 134 \fB--nullglob\fR
 135 If a glob does not match any files, ignore it and print a warning instead of
 136 failing with an error.  In other words, this option allows a glob to
 137 successfully match zero files.
 138 .IP
 139 This option also affects paths that do not contain wildcard characters, since
 140 such paths are still considered globs unless \fB--no-globs\fR is enabled.  If
 141 case-insensitivity is enabled, such a glob could match multiple files with the
 142 same case-insensitive name but different case-sensitive names, whereas a
 143 non-glob path (with \fB--no-globs\fR) can match at most one file.
 144 .TP
 145 \fB--preserve-dir-structure\fR
 146 When extracting paths, preserve the archive directory structure instead of
 147 extracting the file or directory tree named by each path directly to the
 148 destination directory.  Note: \fB--preserve-dir-structure\fR is already the
 149 default behavior for paths in listfiles, but not paths directly specified on the
 150 command line.
 151 .TP
 152 \fB--wimboot\fR
 153 See the documentation for this option in \fBwimlib-imagex-apply\fR (1).
 154 .TP
 155 \fB--compact\fR=\fIFORMAT\fR
 156 See the documentation for this option in \fBwimlib-imagex-apply\fR (1).
 157 .SH NOTES
 158 See the documentation \fBwimlib-imagex apply\fR (1) for documentation about
 159 what data and metadata are extracted on UNIX-like systems versus on Windows.
 160 .PP
 161 On UNIX-like systems that support userspace filesystems with FUSE (e.g. Linux),
 162 one can alternatively mount the WIM image with \fBwimlib-imagex mount\fR (1)
 163 and then extract the desired files or directories using any standard
 164 command-line or graphical program.
 165 .PP
 166 Reparse-point fixups (a.k.a. changing absolute symbolic links and junctions to
 167 point within the extraction location) are never done by \fBwimlib-imagex
 168 extract\fR.  Use \fBwimlib-imagex apply\fR if you want this behavior.
 169 .PP
 170 Unlike \fBwimlib-imagex apply\fR, \fBwimlib-imagex extract\fR does not
 171 support extracting files directly to an NTFS volume using libntfs-3g.
 172 .PP
 173 wimlib v1.6.0 and later can extract files from version 3584 WIMs, which usually
 174 contain LZMS-compressed solid resources and may carry the \fI.esd\fR file extension
 175 rather than \fI.wim\fR.  However, \fI.esd\fR files downloaded directly by the
 176 Windows 8 web downloader have encrypted segments, and wimlib cannot extract such
 177 files until they are first decrypted.  Furthermore, such files are not designed
 178 for random access, so extracting individual files from them may be slow.
 179 .SH EXAMPLES
 180 Extract a file from the first image in "boot.wim" to the current directory:
 181 .RS
 182 .PP
 183 wimlib-imagex extract boot.wim 1 /Windows/System32/notepad.exe
 184 .RE
 185 .PP
 186 Extract a file from the first image in "boot.wim" to standard output:
 187 .RS
 188 .PP
 189 wimlib-imagex extract boot.wim 1 /Windows/System32/notepad.exe \\
 190 .br
 191 .RS
 192 --to-stdout
 193 .RE
 194 .RE
 195 .PP
 196 Extract a file from the first image in "boot.wim" to the specified directory:
 197 .RS
 198 .PP
 199 wimlib-imagex extract boot.wim 1 /Windows/System32/notepad.exe \\
 200 .br
 201 .RS
 202 --dest-dir=somedir
 203 .RE
 204 .RE
 205 .PP
 206 Extract the "sources" directory from the first image in "boot.wim" to the
 207 current directory:
 208 .RS
 209 .PP
 210 wimlib-imagex extract boot.wim 1 /sources
 211 .RE
 212 .PP
 213 Extract multiple files and directories in one command:
 214 .RS
 215 .PP
 216 wimlib-imagex extract boot.wim 1 /Windows/Fonts \\
 217 .br
 218 .RS
 219 /sources /Windows/System32/cmd.exe
 220 .RE
 221 .RE
 222 .PP
 223 Extract many files to the current directory using a wildcard pattern:
 224 .RS
 225 .PP
 226 wimlib-imagex extract install.wim 1 "/Windows/Fonts/*.ttf"
 227 .RE
 228 .PP
 229 Extract files using a list file:
 230 .RS
 231 .PP
 232 wimlib-imagex extract install.wim 1 @files.txt
 233 .RE
 234 .PP
 235  ...  where files.txt could be something like:
 236 .PP
 237 .RS
 238 .RS
 239 .nf
 240 Windows\\System32\\*.*
 241 Windows\\System32\\??-??\\*.*
 242 Windows\\System32\\en-US\\*.*
 243 .RE
 244 .RE
 245 .fi
 246 .SH SEE ALSO
 247 .BR wimlib-imagex (1)
 248 .BR wimlib-imagex-apply (1)
 249 .BR wimlib-imagex-dir (1)
 250 .BR wimlib-imagex-info (1)
 251 .BR wimlib-imagex-mount (1)