wimlib-imagex: add --quiet option
[wimlib] / doc / man1 / wimextract.1
1 .TH WIMEXTRACT "1" "January 2017" "wimlib 1.11.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)