1WIMUPDATE(1)                     User Commands                    WIMUPDATE(1)
2
3
4

NAME

6       wimupdate - Update a WIM image
7

SYNOPSIS

9       wimupdate WIMFILE [IMAGE] [OPTION...] [< CMDFILE]
10

DESCRIPTION

12       wimupdate, or equivalently wimlib-imagex update, modifies the specified
13       IMAGE in the Windows Imaging (WIM) archive WIMFILE by adding, deleting,
14       or renaming files or directories in it.
15
16       IMAGE  specifies the image in WIMFILE to update.  It may be the 1-based
17       index of an image or the name of an image.  It may be omitted  if  WIM‐
18       FILE  contains  only  one  image.   You  can use wiminfo(1) to list the
19       images contained in WIMFILE.
20
21       The modifications to perform on  the  WIM  image  are  specified  as  a
22       sequence  of  commands, one per line, read in a text file from standard
23       input.  It is recommended that standard input be redirected from a file
24       (CMDFILE),  as  shown  above,  rather  than typing in commands interac‐
25       tively.  Alternatively, to specify a command directly  on  the  command
26       line, see the --command option.
27

AVAILABLE COMMANDS

29       This  section  documents  the  commands  that may appear in the CMDFILE
30       described above.
31
32   add [OPTION...] SOURCE DESTINATION
33       Add a file or directory tree to the WIM image.  SOURCE must specify the
34       path to a file or directory on your filesystem.  DESTINATION must spec‐
35       ify the path inside the WIM image at which to add the file or directory
36       tree.
37
38       If  DESTINATION  names  an  existing  directory  in the WIM image, then
39       SOURCE must also name a directory.  This causes  the  contents  of  the
40       SOURCE directory to be added to the DESTINATION directory.
41
42       If  DESTINATION  names  an existing nondirectory file in the WIM image,
43       then SOURCE must also name  a  nondirectory  file.   By  default,  this
44       causes  the  DESTINATION file to be replaced with the SOURCE file.  Or,
45       with --no-replace specified, this generates an error.
46
47       If DESTINATION does not exist in the WIM image, then  any  prerequisite
48       directories are created as needed to add the SOURCE at that location.
49
50       The  add  command  supports a subset of the options accepted by wimcap‐
51       ture; namely, --dereference, --unix-data, --no-acls, and --strict-acls.
52       See wimcapture(1) for explanations of these options.
53
54       In  addition,  the  add command supports the --no-replace option, which
55       causes the add command to refuse  to  overwrite  existing  nondirectory
56       files in the WIM image.
57
58   delete [OPTION...] PATH
59       Delete  a file or directory tree from the WIM image.  PATH must specify
60       the path inside the WIM image of the file or directory tree to delete.
61
62       The available options for the delete command are:
63
64       --force
65             Do not issue an error if the path to delete does not exist.
66
67       --recursive
68             Delete the file or directory tree recursively; if not  specified,
69             an error is issued if the path to delete is a directory.
70
71   rename OLD_PATH NEW_PATH
72       Rename  a  file  or directory tree inside the WIM image.  OLD_PATH must
73       specify the old path of the file  or  directory  tree  inside  the  WIM
74       image, and NEW_PATH must specify the new path for the file or directory
75       tree.  This command follows the semantics of the POSIX rename (3) func‐
76       tion; in particular, a pre-existing file at NEW_PATH will be deleted if
77       present, except in certain cases such as attempting to rename a  direc‐
78       tory to a non-directory, which is not allowed.
79
80       There are no options available for the rename command.
81

OPTIONS

83       The  following  options  are  accepted on the command line by wimupdate
84       itself:
85
86       --dereference
87             Use --dereference for all add commands.
88
89       --unix-data
90             Use --unix-data for all add commands.
91
92       --no-acls
93             Use --no-acls for all add commands.
94
95       --strict-acls
96             Use --strict-acls for all add commands.
97
98       --no-replace
99             Use --no-replace for all add commands.
100
101       --config=FILE
102             Set the capture configuration file for all add commands.  See the
103             description of this option to wimcapture(1).
104
105       --force
106             Use --force for all delete commands.
107
108       --recursive
109             Use --recursive for all delete commands.
110
111       --check
112             Before  updating  the  WIM,  verify  its integrity if it contains
113             extra integrity information.  Also include extra integrity infor‐
114             mation in the updated WIM even if it was not present before.
115
116       --include-integrity
117             Include extra integrity information in the updated WIM, i.e. like
118             --check but don't also verify the WIM beforehand.
119
120       --threads=NUM_THREADS
121             Number of threads to  use  for  compressing  newly  added  files.
122             Default: autodetect (number of processors).
123
124       --rebuild
125             Rebuild  the entire WIM rather than appending the updated data to
126             the end of it.  Rebuilding the WIM is slower,  but  will  save  a
127             little bit of space that would otherwise be left as a hole in the
128             WIM file.
129
130             See wimoptimize(1) for a more customizable way of rebuilding (and
131             optionally  recompressing)  a  WIM  file.  If running wimoptimize
132             after wimupdate, there is no need to specify --rebuild to  wimup‐
133             date.
134
135       --command=STRING
136             Instead  of  reading  update commands from standard input, read a
137             single update command directly from the string  STRING  specified
138             on  the  command  line.  This option cannot be provided more than
139             one time and cannot be used to specify more than one update  com‐
140             mand.  Note that the STRING, as well as any paths containing spa‐
141             ces within the STRING must be appropriately quoted.   If  running
142             from  cmd.exe  on  Windows,  you should use double quotes for the
143             outer quotes and single quotes for the inner quotes.  Example:
144
145                    wimupdate boot.wim 1 --command="add 'C:\My Dir' '\My Dir'"
146
147             This option is provided for convenience  only.   Do  not  execute
148             wimupdate  multiple  consecutive  times,  each  time  passing the
149             --command option!  This is  inefficient.   Instead,  generate  an
150             update  command file and provide it (on standard input) to a sin‐
151             gle invocation of wimupdate, as explained in this document.
152
153       --wimboot-config=FILE
154             If this option is specified, no commands shall be read from stan‐
155             dard input, and instead the following command shall be executed:
156
157                    add FILE /Windows/System32/WimBootCompress.ini
158
159             This  sets  FILE as the WIMBoot configuration file for the image.
160             The [PrepopulateList] section of this file specifies  path  globs
161             that shall not be extracted as WIMBoot pointer files (perhaps due
162             to being needed early in the boot process).  See  the  documenta‐
163             tion  for  the  --wimboot option of wimapply(1) for more informa‐
164             tion.
165
166       --unsafe-compact
167             Compact the WIM archive in-place and append any new data,  elimi‐
168             nating  "holes".   This  is efficient, but in general this option
169             should not be used because a  failed  or  interrupted  compaction
170             will corrupt the WIM archive.  For more information, see the doc‐
171             umentation for this option in wimoptimize(1).
172

NOTES

174       wimupdate can be viewed as redundant with wimmountrw, since a WIM image
175       can  also  be  updated  by  mounting it read-write.  However, wimupdate
176       works on all platforms including Windows, whereas wimmountrw only works
177       on Linux.
178
179       Symbolic  links  inside  a  WIM  image  are not dereferenced when being
180       interpreted.  So, for example, if you have a WIM image that contains  a
181       symbolic link "/Documents and Settings" -> "/Users" where "/Users" is a
182       directory, then a subdirectory named "Public" in this directory must be
183       specified  as "/Users/Public" rather than "/Documents and Settings/Pub‐
184       lic".
185
186       All paths to files or directories within the WIM image must  be  speci‐
187       fied  relative to the root of the image.  However, the leading slash is
188       optional, and both forward slashes and backslashes  are  accepted.   In
189       addition,  on  Windows,  the paths are by default treated case-insensi‐
190       tively, while on UNIX-like systems, the paths are  by  default  treated
191       case-sensitively.   The default case sensitivity may be changed by set‐
192       ting the WIMLIB_IMAGEX_IGNORE_CASE environmental variable to 0 or 1.
193
194       The command file (CMDFILE) is parsed by wimupdate itself and not by the
195       system  shell.   Therefore,  its  syntax  is limited.  However, comment
196       lines beginning with '#' are allowed, and it is also possible to  quote
197       arguments with whitespace inside them.
198
199       On UNIX-like systems, you cannot use wimupdate to add files to an image
200       directly from an NTFS volume using libntfs-3g, even  though  wimcapture
201       supports capturing a full image this way.
202
203       Except  when  using  --unsafe-compact,  it is safe to abort a wimupdate
204       command partway through; however, after doing this, it  is  recommended
205       to run wimoptimize to remove any data that was appended to the physical
206       WIM file but not yet incorporated into the structure of the WIM, unless
207       --rebuild  was specified, in which case you should delete the temporary
208       file left over.
209

EXAMPLES

211       All the examples below show the update command file to  be  created  as
212       well as the wimupdate command to run to perform the updates.
213
214       Delete two files from a WIM image:
215
216              update_commands.txt:
217
218                     delete /setup.exe
219                     delete /sources/setup.exe
220
221              $ wimupdate boot.wim 2 < update_commands.txt
222
223       Add  some  files  and  directories to a WIM image.  Note that the first
224       path of each add command specifies the files to add, while  the  second
225       path  of  each  add  command specify the locations at which to add them
226       inside the WIM image:
227
228              update_commands.txt:
229
230                     add somedir     /dir
231                     add somefile    /dir/file
232
233              $ wimupdate boot.wim 2 < update_commands.txt
234
235       Rename a file inside a WIM image.
236
237              update_commands.txt:
238
239                     rename /dir_in_wim/oldfile.txt /dir_in_wim/newfile.txt
240
241              $ wimupdate boot.wim 2 < update_commands.txt
242
243       Using additional features, such as comments, options, and overlays, and
244       including extra integrity information in the updated WIM:
245
246              update_commands.txt:
247
248                     #
249                     # This file specifies some changes to make to a WIM image.
250                     #
251
252                     # Add a new directory containing files I want in the image.
253                     # The quotes are necessary because the directory name
254                     # contains a space.
255                     add "My Directory" "/My Directory"
256
257                     # Add the contents of "Another Directory" to the
258                     # "/My Directory" we just created in the WIM image.  Since
259                     # the destination path already exists, this performs an
260                     # overlay.
261                     add "Another Directory" "/My Directory"
262
263                     # Rename some file for some reason.
264                     rename /dir_in_wim/oldfile.txt /dir_in_wim/newfile.txt
265
266                     # Delete an unwanted directory.
267                     delete --recursive /Users/Me/Documents/Junk
268
269              $ wimupdate boot.wim 2 --check < update_commands.txt
270

SEE ALSO

272       wimlib-imagex(1) wimcapture(1) wiminfo(1) wimmountrw(1) wimoptimize(1)
273
274
275
276wimlib 1.13.3                    October 2020                     WIMUPDATE(1)
Impressum