wimlib.net Git - wimlib/blob - doc/man1/wimextract.1

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