9a9e1592032593a150be23fb4cf997fbe182494b
[wimlib] / 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...]  [\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, except
44 when overridden through the \fBWIMLIB_IMAGEX_IGNORE_CASE\fR environmental
45 variable, as documented in \fB@IMAGEX_PROGNAME@\fR (1).
46 .PP
47 If no \fIPATH\fRs are provided, the default behavior is to extract the full
48 image, as if the path "/" had been provided.
49 .PP
50 If a single \fIPATH\fR is provided and is prefixed with the '@' character, it is
51 interpreted as the path to a \fILISTFILE\fR which must be a UTF-8 text file that
52 contains a list of paths (files or directories) to extract, one per line.  In
53 each line, leading and trailing whitespace is ignored, and lines beginning with
54 the ';' character and otherwise empty lines are ignored.  Each path must be
55 unquoted and must specify a full path in the WIM image, as described above.
56 However, unless \fB--no-wildcards\fR is specified, each path in the list file
57 may also contain the wildcard characters '?' and '*'.  The '?' character matches
58 any character other than a path separator, whereas the '*' character matches
59 zero or more non-path-separator characters.  Consequently, a single wildcard
60 pattern may expand to multiple actual files or directories.
61 .PP
62 In the \fILISTFILE\fR mode, by default a wildcard pattern that matches no files
63 or directories in the WIM image only produces a warning; use
64 \fB--strict-wildcards\fR if you want an error instead.  Also, when using a list
65 file, files and directories not located at the root of the WIM image will be
66 extracted to a corresponding subdirectory of the destination directory rather
67 than directly to the destination directory itself.
68 .SH SPLIT WIMS
69 You may use \fB@IMAGEX_PROGNAME@ extract\fR to extract files or directory trees
70 from a split WIM.  This uses the \fB--refs\fR="\fIGLOB\fR" option in the same
71 way as in other commands such as \fB@IMAGEX_PROGNAME@ apply\fR.  See
72 \fB@IMAGEX_PROGNAME@ apply\fR (1) for more details.
73 .SH OPTIONS
74 .TP 6
75 \fB--check\fR
76 When reading \fIWIMFILE\fR, verify its integrity if an integrity table is
77 present.
78 .TP
79 \fB--ref\fR="\fIGLOB\fR"
80 File glob of additional WIMs or split WIM parts to reference resources from.
81 See \fBSPLIT_WIMS\fR.  Note: \fIGLOB\fR is listed in quotes because it is
82 interpreted by \fB@IMAGEX_PROGNAME@\fR and may need to be quoted to protect
83 against shell expansion.
84 .TP
85 \fB--unix-data\fR
86 See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
87 .TP
88 \fB--no-acls\fR
89 See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
90 .TP
91 \fB--strict-acls\fR
92 See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
93 .TP
94 \fB--no-attributes\fR
95 See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
96 .TP
97 \fB--include-invalid-names\fR
98 See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
99 .TP
100 \fB--to-stdout\fR
101 Extract the files to standard output instead of to the filesystem.  This can
102 only be provided if all the specified \fIPATH\fRs are to regular files (not
103 directories or reparse points).  If present, alternate data streams are not
104 extracted.
105 .TP
106 \fB--dest-dir\fR=\fIDIR\fR
107 Extract the files and directories to the directory \fIDIR\fR instead of to the
108 current working directory.
109 .TP
110 \fB--no-wildcards\fR
111 Do not interpret wildcard characters in paths in the \fILISTFILE\fR.
112 .TP
113 \fB--strict-wildcards\fR
114 Fail if any wildcard patterns in \fILISTFILE\fR do not match any files or
115 directories in the WIM image.  The default behavior is to warn only.  This
116 option has no effect if \fB--no-wildcards\fR is also specified or if \fIPATH\fRs
117 are specified instead of a \fILISTFILE\fR; in those cases, an error is issued if
118 any file to extract does not exist.
119 .SH NOTES
120 See the documentation \fB@IMAGEX_PROGNAME@ apply\fR (1) for documentation about
121 what data and metadata are extracted on UNIX-like systems versus on Windows.
122 .PP
123 On UNIX-like systems that support userspace filesystems with FUSE (e.g. Linux),
124 one can alternatively mount the WIM image with \fB@IMAGEX_PROGNAME@ mount\fR (1)
125 and then extract the desired files or directories using any standard
126 command-line or graphical program.
127 .PP
128 Reparse-point fixups (a.k.a. changing absolute symbolic links and junctions to
129 point within the extraction location) are never done by \fB@IMAGEX_PROGNAME@
130 extract\fR.  Use \fB@IMAGEX_PROGNAME@ apply\fR if you want this behavior.
131 .PP
132 Unlike \fB@IMAGEX_PROGNAME@ apply\fR, \fB@IMAGEX_PROGNAME@ extract\fR does not
133 support extracting files directly to a NTFS volume using libntfs-3g.
134 .PP
135 wimlib v1.6.0 and later can extract files from version 3584 WIMs, which usually
136 use packed, LZMS-compressed streams and may carry the \fI.esd\fR file extension
137 rather than \fI.wim\fR.  However, \fI.esd\fR files downloaded directly by the
138 Windows 8 web downloader have encrypted segments, and wimlib cannot extract such
139 files until they are first decrypted.  Furthermore, such files are not designed
140 for random access, so extracting individual files from them may be slow.
141 .SH EXAMPLES
142 Extract a file from the first image in "boot.wim" to the current directory:
143 .RS
144 .PP
145 @IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/System32/notepad.exe
146 .RE
147 .PP
148 Extract a file from the first image in "boot.wim" to standard output:
149 .RS
150 .PP
151 @IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/System32/notepad.exe \\
152 .br
153 .RS
154 --to-stdout
155 .RE
156 .RE
157 .PP
158 Extract a file from the first image in "boot.wim" to the specified directory:
159 .RS
160 .PP
161 @IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/System32/notepad.exe \\
162 .br
163 .RS
164 --dest-dir=somedir
165 .RE
166 .RE
167 .PP
168 Extract the "sources" directory from the first image in "boot.wim" to the
169 current directory:
170 .RS
171 .PP
172 @IMAGEX_PROGNAME@ extract boot.wim 1 /sources
173 .RE
174 .PP
175 Extract multiple files and directories in one command:
176 .RS
177 .PP
178 @IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/Fonts \\
179 .br
180 .RS
181 /sources /Windows/System32/cmd.exe
182 .RE
183 .RE
184 .PP
185 Extract files using a list file:
186 .RS
187 .PP
188 @IMAGEX_PROGNAME@ extract install.wim 1 @files.txt
189 .RE
190 .PP
191  ...  where files.txt could be something like:
192 .PP
193 .RS
194 .RS
195 .nf
196 Windows\\System32\\*.*
197 Windows\\System32\\??-??\\*.*
198 Windows\\System32\\en-US\\*.*
199 .RE
200 .RE
201 .fi
202 .SH SEE ALSO
203 .BR @IMAGEX_PROGNAME@ (1)
204 .BR @IMAGEX_PROGNAME@-apply (1)
205 .BR @IMAGEX_PROGNAME@-dir (1)
206 .BR @IMAGEX_PROGNAME@-info (1)
207 .BR @IMAGEX_PROGNAME@-mount (1)