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

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