]> wimlib.net Git - wimlib/blob - doc/man1/wimupdate.1
Use MIT license instead of CC0
[wimlib] / doc / man1 / wimupdate.1
1 .TH WIMUPDATE "1" "December 2021" "wimlib 1.13.5" "User Commands"
2 .SH NAME
3 wimupdate \- Update a WIM image
4 .SH SYNOPSIS
5 \fBwimupdate\fR \fIWIMFILE\fR [\fIIMAGE\fR] [\fIOPTION\fR...] [< \fICMDFILE\fR]
6 .SH DESCRIPTION
7 \fBwimupdate\fR, or equivalently \fBwimlib-imagex update\fR, modifies the
8 specified \fIIMAGE\fR in the Windows Imaging (WIM) archive \fIWIMFILE\fR by
9 adding, deleting, or renaming files or directories in it.
10 .PP
11 \fIIMAGE\fR specifies the image in \fIWIMFILE\fR to update.  It may be the 1-based
12 index of an image or the name of an image.  It may be omitted if \fIWIMFILE\fR
13 contains only one image.  You can use \fBwiminfo\fR(1) to list the images
14 contained in \fIWIMFILE\fR.
15 .PP
16 The modifications to perform on the WIM image are specified as a sequence of
17 commands, one per line, read in a text file from standard input.  It is
18 recommended that standard input be redirected from a file (\fICMDFILE\fR), as
19 shown above, rather than typing in commands interactively.  Alternatively, to
20 specify a command directly on the command line, see the \fB--command\fR option.
21 .SH AVAILABLE COMMANDS
22 This section documents the commands that may appear in the \fICMDFILE\fR
23 described above.
24 .SS \fBadd\fR [\fIOPTION\fR...] \fISOURCE\fR \fIDESTINATION\fR
25 Add a file or directory tree to the WIM image.  \fISOURCE\fR must specify the
26 path to a file or directory on your filesystem.  \fIDESTINATION\fR must specify
27 the path inside the WIM image at which to add the file or directory tree.
28 .PP
29 If \fIDESTINATION\fR names an existing directory in the WIM image, then
30 \fISOURCE\fR must also name a directory.  This causes the contents of the
31 \fISOURCE\fR directory to be added to the \fIDESTINATION\fR directory.
32 .PP
33 If \fIDESTINATION\fR names an existing nondirectory file in the WIM image, then
34 \fISOURCE\fR must also name a nondirectory file.  By default, this causes the
35 \fIDESTINATION\fR file to be replaced with the \fISOURCE\fR file.  Or, with
36 \fB--no-replace\fR specified, this generates an error.
37 .PP
38 If \fIDESTINATION\fR does not exist in the WIM image, then any prerequisite
39 directories are created as needed to add the \fISOURCE\fR at that location.
40 .PP
41 The \fBadd\fR command supports a subset of the options accepted by
42 \fBwimcapture\fR; namely, \fB--dereference\fR, \fB--unix-data\fR,
43 \fB--no-acls\fR, and \fB--strict-acls\fR.  See \fBwimcapture\fR(1) for
44 explanations of these options.
45 .PP
46 In addition, the \fBadd\fR command supports the \fB--no-replace\fR option, which
47 causes the \fBadd\fR command to refuse to overwrite existing nondirectory files
48 in the WIM image.
49 .SS \fBdelete\fR [\fIOPTION\fR...] \fIPATH\fR
50 Delete a file or directory tree from the WIM image.  \fIPATH\fR must specify the
51 path inside the WIM image of the file or directory tree to delete.
52 .PP
53 The available options for the \fBdelete\fR command are:
54 .TP 6
55 \fB--force\fR
56 Do not issue an error if the path to delete does not exist.
57 .TP
58 \fB--recursive\fR
59 Delete the file or directory tree recursively; if not specified, an error is
60 issued if the path to delete is a directory.
61 .SS \fBrename\fR \fIOLD_PATH\fR \fINEW_PATH\fR
62 Rename a file or directory tree inside the WIM image.  \fIOLD_PATH\fR must
63 specify the old path of the file or directory tree inside the WIM image, and
64 \fINEW_PATH\fR must specify the new path for the file or directory tree.  This
65 command follows the semantics of the POSIX \fBrename\fR (3) function; in
66 particular, a pre-existing file at \fINEW_PATH\fR will be deleted if present,
67 except in certain cases such as attempting to rename a directory to a
68 non-directory, which is not allowed.
69 .PP
70 There are no options available for the \fBrename\fR command.
71 .SH OPTIONS
72 The following options are accepted on the command line by \fBwimupdate\fR
73 itself:
74 .TP 6
75 \fB--dereference\fR
76 Use \fB--dereference\fR for all \fBadd\fR commands.
77 .TP
78 \fB--unix-data\fR
79 Use \fB--unix-data\fR for all \fBadd\fR commands.
80 .TP
81 \fB--no-acls\fR
82 Use \fB--no-acls\fR for all \fBadd\fR commands.
83 .TP
84 \fB--strict-acls\fR
85 Use \fB--strict-acls\fR for all \fBadd\fR commands.
86 .TP
87 \fB--no-replace\fR
88 Use \fB--no-replace\fR for all \fBadd\fR commands.
89 .TP
90 \fB--config\fR=\fIFILE\fR
91 Set the capture configuration file for all \fBadd\fR commands.  See the
92 description of this option to \fBwimcapture\fR(1).
93 .TP
94 \fB--force\fR
95 Use \fB--force\fR for all \fBdelete\fR commands.
96 .TP
97 \fB--recursive\fR
98 Use \fB--recursive\fR for all \fBdelete\fR commands.
99 .TP
100 \fB--check\fR
101 Before updating the WIM, verify its integrity if it contains extra integrity
102 information.  Also include extra integrity information in the updated WIM even
103 if it was not present before.
104 .TP
105 \fB--include-integrity\fR
106 Include extra integrity information in the updated WIM, i.e. like \fB--check\fR
107 but don't also verify the WIM beforehand.
108 .TP
109 \fB--threads\fR=\fINUM_THREADS\fR
110 Number of threads to use for compressing newly added files.  Default: autodetect
111 (number of processors).
112 .TP
113 \fB--rebuild\fR
114 Rebuild the entire WIM rather than appending the updated data to the end of it.
115 Rebuilding the WIM is slower, but will save a little bit of space that would
116 otherwise be left as a hole in the WIM file.
117 .IP
118 See \fBwimoptimize\fR(1) for a more customizable way of rebuilding (and
119 optionally recompressing) a WIM file.  If running \fBwimoptimize\fR after
120 \fBwimupdate\fR, there is no need to specify \fB--rebuild\fR to \fBwimupdate\fR.
121 .TP
122 \fB--command\fR=\fISTRING\fR
123 Instead of reading update commands from standard input, read a single update
124 command directly from the string \fISTRING\fR specified on the command line.
125 This option cannot be provided more than one time and cannot be used to specify
126 more than one update command.  Note that the \fISTRING\fR, as well as any
127 paths containing spaces within the \fISTRING\fR must be appropriately quoted.
128 If running from cmd.exe on Windows, you should use double quotes for the outer
129 quotes and single quotes for the inner quotes.  Example:
130 .IP
131 .RS
132 .RS
133 wimupdate boot.wim 1 --command="add 'C:\\My Dir' '\\My Dir'"
134 .RE
135 .RE
136 .IP
137 This option is provided for convenience only.  Do not execute \fBwimupdate\fR
138 multiple consecutive times, each time passing the \fB--command\fR option!  This
139 is inefficient.  Instead, generate an update command file and provide it (on
140 standard input) to a single invocation of \fBwimupdate\fR, as explained in this
141 document.
142 .TP
143 \fB--wimboot-config\fR=\fIFILE\fR
144 If this option is specified, no commands shall be read from standard input, and
145 instead the following command shall be executed:
146 .IP
147 .nf
148 .RS
149 .RS
150 \fBadd\fR \fIFILE\fR /Windows/System32/WimBootCompress.ini
151 .RE
152 .RE
153 .fi
154 .IP
155 This sets \fIFILE\fR as the WIMBoot configuration file for the image.  The
156 [PrepopulateList] section of this file specifies path globs that shall not be
157 extracted as WIMBoot pointer files (perhaps due to being needed early in the
158 boot process).  See the documentation for the \fB--wimboot\fR option of
159 \fBwimapply\fR(1) for more information.
160 .TP
161 \fB--unsafe-compact\fR
162 Compact the WIM archive in-place and append any new data, eliminating "holes".
163 This is efficient, but in general this option should \fInot\fR be used because a
164 failed or interrupted compaction will corrupt the WIM archive.  For more
165 information, see the documentation for this option in \fBwimoptimize\fR(1).
166 .SH NOTES
167 \fBwimupdate\fR can be viewed as redundant with \fBwimmountrw\fR, since a WIM
168 image can also be updated by mounting it read-write.  However, \fBwimupdate\fR
169 works on all platforms including Windows, whereas \fBwimmountrw\fR only works on
170 Linux.
171 .PP
172 Symbolic links inside a WIM image are not dereferenced when being interpreted.
173 So, for example, if you have a WIM image that contains a symbolic link
174 "/Documents and Settings" -> "/Users" where "/Users" is a directory, then a
175 subdirectory named "Public" in this directory must be specified as
176 "/Users/Public" rather than "/Documents and Settings/Public".
177 .PP
178 All paths to files or directories within the WIM image must be specified
179 relative to the root of the image.  However, the leading slash is optional, and
180 both forward slashes and backslashes are accepted.  In addition, on Windows, the
181 paths are by default treated case-insensitively, while on UNIX-like systems, the
182 paths are by default treated case-sensitively.  The default case sensitivity may
183 be changed by setting the \fBWIMLIB_IMAGEX_IGNORE_CASE\fR environmental
184 variable to 0 or 1.
185 .PP
186 The command file (\fICMDFILE\fR) is parsed by \fBwimupdate\fR itself and not by
187 the system shell.  Therefore, its syntax is limited.  However, comment lines
188 beginning with '#' are allowed, and it is also possible to quote arguments with
189 whitespace inside them.
190 .PP
191 On UNIX-like systems, you cannot use \fBwimupdate\fR to add files to an image
192 directly from an NTFS volume using libntfs-3g, even though \fBwimcapture\fR
193 supports capturing a full image this way.
194 .PP
195 Except when using \fB--unsafe-compact\fR, it is safe to abort a \fBwimupdate\fR
196 command partway through; however, after doing this, it is recommended to run
197 \fBwimoptimize\fR to remove any data that was appended to the physical WIM file
198 but not yet incorporated into the structure of the WIM, unless \fB--rebuild\fR
199 was specified, in which case you should delete the temporary file left over.
200 .SH EXAMPLES
201 All the examples below show the update command file to be created as well as the
202 \fBwimupdate\fR command to run to perform the updates.
203 .PP
204 Delete two files from a WIM image:
205 .PP
206 .RS
207 \fIupdate_commands.txt\fR:
208 .RS
209 .PP
210 .nf
211 delete /setup.exe
212 delete /sources/setup.exe
213 .fi
214 .RE
215 .RE
216 .PP
217 .RS
218 $ wimupdate boot.wim 2 < update_commands.txt
219 .RE
220 .PP
221 Add some files and directories to a WIM image.  Note that the first path of each
222 \fBadd\fR command specifies the files to add, while the second path of each
223 \fBadd\fR command specify the locations at which to add them inside the WIM
224 image:
225 .PP
226 .RS
227 \fIupdate_commands.txt\fR:
228 .RS
229 .PP
230 .nf
231 add somedir     /dir
232 add somefile    /dir/file
233 .fi
234 .RE
235 .RE
236 .PP
237 .RS
238 $ wimupdate boot.wim 2 < update_commands.txt
239 .RE
240 .PP
241 Rename a file inside a WIM image.
242 .PP
243 .RS
244 \fIupdate_commands.txt\fR:
245 .RS
246 .PP
247 .nf
248 rename /dir_in_wim/oldfile.txt /dir_in_wim/newfile.txt
249 .fi
250 .RE
251 .RE
252 .PP
253 .RS
254 $ wimupdate boot.wim 2 < update_commands.txt
255 .RE
256 .PP
257 Using additional features, such as comments, options, and overlays, and
258 including extra integrity information in the updated WIM:
259 .PP
260 .RS
261 \fIupdate_commands.txt\fR:
262 .RS
263 .PP
264 .nf
265 #
266 # This file specifies some changes to make to a WIM image.
267 #
268
269 # Add a new directory containing files I want in the image.
270 # The quotes are necessary because the directory name
271 # contains a space.
272 add "My Directory" "/My Directory"
273
274 # Add the contents of "Another Directory" to the
275 # "/My Directory" we just created in the WIM image.  Since
276 # the destination path already exists, this performs an
277 # overlay.
278 add "Another Directory" "/My Directory"
279
280 # Rename some file for some reason.
281 rename /dir_in_wim/oldfile.txt /dir_in_wim/newfile.txt
282
283 # Delete an unwanted directory.
284 delete --recursive /Users/Me/Documents/Junk
285 .fi
286 .RE
287 .RE
288 .PP
289 .RS
290 $ wimupdate boot.wim 2 --check < update_commands.txt
291 .RE
292 .PP
293 .SH SEE ALSO
294 .BR wimlib-imagex (1)
295 .BR wimcapture (1)
296 .BR wiminfo (1)
297 .BR wimmountrw (1)
298 .BR wimoptimize (1)