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