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

   1 .TH WIMLIB-IMAGEX "1" "January 2014" "@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 | @\fILISTFILE\fR)...]  [\fIOPTION\fR...]
   6 .SH DESCRIPTION
   7 \fB@IMAGEX_PROGNAME@ 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 \fB@IMAGEX_PROGNAME@ 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 \fB@IMAGEX_PROGNAME@ 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 \fB@IMAGEX_PROGNAME@ 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 \fB@IMAGEX_PROGNAME@ 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 \fB@IMAGEX_PROGNAME@ 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 \fB@IMAGEX_PROGNAME@\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 pattern may expand to multiple actual files or directories.  Use the
  60 \fB--no-wildcards\fR option to disable wildcard matching and search for each
  61 path literally.
  62 .PP
  63 Each \fILISTFILE\fR must be a UTF-8 text file that contains a list of paths to
  64 extract, one per line.  Wildcard characters are allowed by default.  The
  65 following demonstrates an example listfile:
  66 .PP
  67 .RS
  68 .nf
  69
  70 ; This is a comment (begins with semicolon)
  71 /Users
  72 /Windows/explorer.exe
  73 /Windows/System32/en-US/*
  74
  75 ; Both forward and backslashes are valid.
  76 ; Don't quote paths containing spaces.
  77 \\Program Files\\A*
  78
  79 ; Leading and trailing whitespace is ignored
  80     \\Windows\\notepad*
  81
  82 .SH SPLIT WIMS
  83 You may use \fB@IMAGEX_PROGNAME@ extract\fR to extract files or directory trees
  84 from a split WIM.  This uses the \fB--refs\fR="\fIGLOB\fR" option in the same
  85 way as in other commands such as \fB@IMAGEX_PROGNAME@ apply\fR.  See
  86 \fB@IMAGEX_PROGNAME@ apply\fR (1) for more details.
  87 .SH OPTIONS
  88 .TP 6
  89 \fB--check\fR
  90 When reading \fIWIMFILE\fR, verify its integrity if an integrity table is
  91 present.
  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 \fB@IMAGEX_PROGNAME@\fR and may need to be quoted to protect
  97 against 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, alternate data streams are not
 107 extracted.
 108 .TP
 109 \fB--unix-data\fR
 110 See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
 111 .TP
 112 \fB--no-acls\fR
 113 See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
 114 .TP
 115 \fB--strict-acls\fR
 116 See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
 117 .TP
 118 \fB--no-attributes\fR
 119 See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
 120 .TP
 121 \fB--include-invalid-names\fR
 122 See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
 123 .TP
 124 \fB--no-wildcards\fR
 125 Do not interpret wildcard characters in paths.  Each path will be searched for
 126 literally.
 127 .TP
 128 \fB--nullglob\fR
 129 If a wildcard pattern (a.k.a. a "glob") does not match any paths, ignore it and
 130 print a warning instead of failing with an error.  In other words, this option
 131 allows a wildcard pattern to successfully match zero files.  Note that this
 132 applies even if one of the paths does not contain wildcard characters.  Such a
 133 path is still treated as a "wildcard pattern", so with this option it may not
 134 match anything and therefore produce no error.  This option cannot be combined
 135 with \fB--no-wildcards\fR, as that would be meaningless.
 136 .TP
 137 \fB--preserve-dir-structure\fR
 138 When extracting paths, preserve the archive directory structure instead of
 139 extracting the file or directory tree named by each path directly to the
 140 destination directory.  Note: \fB--preserve-dir-structure\fR is already the
 141 default behavior for paths in listfiles, but not paths directly specified on the
 142 command line.
 143 .SH NOTES
 144 See the documentation \fB@IMAGEX_PROGNAME@ apply\fR (1) for documentation about
 145 what data and metadata are extracted on UNIX-like systems versus on Windows.
 146 .PP
 147 On UNIX-like systems that support userspace filesystems with FUSE (e.g. Linux),
 148 one can alternatively mount the WIM image with \fB@IMAGEX_PROGNAME@ mount\fR (1)
 149 and then extract the desired files or directories using any standard
 150 command-line or graphical program.
 151 .PP
 152 Reparse-point fixups (a.k.a. changing absolute symbolic links and junctions to
 153 point within the extraction location) are never done by \fB@IMAGEX_PROGNAME@
 154 extract\fR.  Use \fB@IMAGEX_PROGNAME@ apply\fR if you want this behavior.
 155 .PP
 156 Unlike \fB@IMAGEX_PROGNAME@ apply\fR, \fB@IMAGEX_PROGNAME@ extract\fR does not
 157 support extracting files directly to a NTFS volume using libntfs-3g.
 158 .PP
 159 wimlib v1.6.0 and later can extract files from version 3584 WIMs, which usually
 160 use packed, LZMS-compressed streams and may carry the \fI.esd\fR file extension
 161 rather than \fI.wim\fR.  However, \fI.esd\fR files downloaded directly by the
 162 Windows 8 web downloader have encrypted segments, and wimlib cannot extract such
 163 files until they are first decrypted.  Furthermore, such files are not designed
 164 for random access, so extracting individual files from them may be slow.
 165 .SH EXAMPLES
 166 Extract a file from the first image in "boot.wim" to the current directory:
 167 .RS
 168 .PP
 169 @IMAGEX_PROGNAME@ extract 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 @IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/System32/notepad.exe \\
 176 .br
 177 .RS
 178 --to-stdout
 179 .RE
 180 .RE
 181 .PP
 182 Extract a file from the first image in "boot.wim" to the specified directory:
 183 .RS
 184 .PP
 185 @IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/System32/notepad.exe \\
 186 .br
 187 .RS
 188 --dest-dir=somedir
 189 .RE
 190 .RE
 191 .PP
 192 Extract the "sources" directory from the first image in "boot.wim" to the
 193 current directory:
 194 .RS
 195 .PP
 196 @IMAGEX_PROGNAME@ extract boot.wim 1 /sources
 197 .RE
 198 .PP
 199 Extract multiple files and directories in one command:
 200 .RS
 201 .PP
 202 @IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/Fonts \\
 203 .br
 204 .RS
 205 /sources /Windows/System32/cmd.exe
 206 .RE
 207 .RE
 208 .PP
 209 Extract many files to the current directory using a wildcard pattern:
 210 .RS
 211 .PP
 212 @IMAGEX_PROGNAME@ extract install.wim 1 "/Windows/Fonts/*.ttf"
 213 .RE
 214 .PP
 215 Extract files using a list file:
 216 .RS
 217 .PP
 218 @IMAGEX_PROGNAME@ extract install.wim 1 @files.txt
 219 .RE
 220 .PP
 221  ...  where files.txt could be something like:
 222 .PP
 223 .RS
 224 .RS
 225 .nf
 226 Windows\\System32\\*.*
 227 Windows\\System32\\??-??\\*.*
 228 Windows\\System32\\en-US\\*.*
 229 .RE
 230 .RE
 231 .fi
 232 .SH SEE ALSO
 233 .BR @IMAGEX_PROGNAME@ (1)
 234 .BR @IMAGEX_PROGNAME@-apply (1)
 235 .BR @IMAGEX_PROGNAME@-dir (1)
 236 .BR @IMAGEX_PROGNAME@-info (1)
 237 .BR @IMAGEX_PROGNAME@-mount (1)