doc: note that data integrity is not guaranteed in --unsafe-compact mode
[wimlib] / doc / man1 / wimlib-imagex-export.1
1 .TH WIMLIB-IMAGEX "1" "August 2015" "wimlib 1.8.2" "User Commands"
3 wimlib-imagex-export \- Exports an image from a WIM archive to an existing or new WIM archive
5 \fBwimlib-imagex export\fR \fISRC_WIMFILE\fR \fISRC_IMAGE\fR
7 [\fIOPTION\fR...]
9 Copies the specified image in \fISRC_WIMFILE\fR to \fIDEST_WIMFILE\fR,
10 optionally changing its name and/or description and/or compression type.
11 If \fIDEST_WIMFILE\fR exists, it is taken be a WIM archive to which the image
12 will be appended.  Otherwise, it is created as a new WIM archive containing only
13 the exported image.
14 This command is also available as simply \fBwimexport\fR if the appropriate hard
15 link or batch file has been installed.
16 .PP
17 \fISRC_IMAGE\fR specifies the image in \fISRC_WIMFILE\fR to export.  It may be a
18 1-based index of an image in \fISRC_WIMFILE\fR, the name of an image in
19 \fISRC_WIMFILE\fR, or the keyword "all" to indicate that all images in
20 \fISRC_WIMFILE\fR are to be exported.  Use the \fBwimlib-imagex info\fR (1)
21 command to list the images a WIM file contains.
22 .PP
23 If specified, \fIDEST_IMAGE_NAME\fR is the name to give the image being exported
24 to \fIDEST_WIMFILE\fR.  The default is its name in \fISRC_WIMFILE\fR.
25 \fIDEST_IMAGE_NAME\fR cannot be specified if multiple images are being exported.
26 .PP
27 If specified, \fIDEST_IMAGE_DESCRIPTION\fR is the description to give the image
28 being exported to \fIDEST_WIMFILE\fR.  The default is its description in
30 .PP
31 \fBwimlib-imagex export\fR supports exporting images from stand-alone WIMs as well as
32 from split WIMs.  However, you cannot export an image to a split WIM.  See
34 .PP
35 \fBwimlib-imagex export\fR also supports exporting images from a non-pipable
36 WIM into a (possibly new) pipable WIM, and vice versa.  Furthermore, it will
37 export a pipable WIM directly to standard output if "-" is specified as
38 \fIDEST_WIMFILE\fR (this implies \fB--pipable\fR).  See \fB--pipable\fR and
39 \fB--not-pipable\fR.
40 .PP
42 .TP 6
43 \fB--boot\fR
44 Specifies that the exported image is to be the bootable image of the destination
45 WIM archive.
46 .IP ""
47 If multiple images are being exported, this flag indicates that the image in the
48 \fISRC_WIMFILE\fR that is currently marked as bootable is to be made bootable in
49 \fIDEST_WIMFILE\fR.  If no image in \fISRC_WIMFILE\fR is bootable, it is an
50 error.
51 .TP
52 \fB--check\fR
53 When reading \fISRC_WIMFILE\fR, and \fIDEST_WIMFILE\fR if it exists, verify the
54 file's integrity if the integrity table is present; additionally, when writing
55 \fIDEST_WIMFILE\fR with the new image(s) added, write an integrity table.
56 If neither \fB--check\fR nor \fB--nocheck\fR is specified, an integrity
57 table is included in \fIDEST_WIMFILE\fR if and only if \fIDEST_WIMFILE\fR
58 already existed and it had an integrity table before.
59 .TP
60 \fB--nocheck\fR
61 When writing \fIDEST_WIMFILE\fR with the new image(s) added, do not write an
62 integrity table.
63 If neither \fB--check\fR nor \fB--nocheck\fR is specified, an integrity
64 table is included in \fIDEST_WIMFILE\fR if and only if \fIDEST_WIMFILE\fR
65 already existed and it had an integrity table before.
66 .TP
67 \fB--compress\fR=\fITYPE\fR[:\fILEVEL\fR]
68 Specifies the compression type, and optionally the compression level for that
69 compression type, for \fIDEST_WIMFILE\fR.  Setting the compression type only has
70 an effect if \fIDEST_WIMFILE\fR does not yet exist, since if \fIDEST_WIMFILE\fR
71 exists, the compression type must be the same as that of \fIDEST_WIMFILE\fR.
72 .IP ""
73 See the documentation for this option to \fBwimlib-imagex capture\fR (1) for
74 more details.
75 .TP
76 \fB--recompress\fR
77 Force all exported data to be recompressed, even if the destination WIM will use
78 the same compression type as the source WIM.
79 .TP
80 \fB--chunk-size\fR=\fISIZE\fR
81 Set the WIM compression chunk size to \fISIZE\fR.  See the documentation for
82 this option to \fBwimlib-imagex capture\fR (1) for more details.
83 .TP
84 \fB--solid\fR
85 Create a "solid" archive that compresses multiple files together.  This can
86 result in a higher compression ratio, but has disadvantages such as reduced
87 compatibility.  See the documentation for this option to \fBwimlib-imagex
88 capture\fR (1) for more details.
89 .TP
90 \fB--solid-chunk-size\fR=\fISIZE\fR
91 Like \fB--chunk-size\fR, but set the chunk size used in solid resources.  See the
92 documentation for this option to \fBwimlib-imagex capture\fR (1) for more
93 details.
94 .TP
95 \fB--solid-compress\fR=\fITYPE\fR[:\fILEVEL\fR]
96 Like \fB--compress\fR, but set the compression type used in solid resources.  See
97 the documentation for this option to \fBwimlib-imagex capture\fR (1) for
98 more details.
99 .TP
100 \fB--threads\fR=\fINUM_THREADS\fR
101 Number of threads to use for compressing data.  Default: autodetect (number of
102 processors).  Note: multiple compressor threads are not very useful when
103 exporting to a WIM with the same compression type as the source WIM, since
104 wimlib optimizes this case by re-using the raw compressed data.
105 .TP
106 \fB--rebuild\fR
107 When exporting image(s) to an existing WIM: rebuild the entire WIM rather than
108 appending data to the end of it.  Rebuilding the WIM is slower, but will save a
109 little bit of space that would otherwise be left as a hole in the WIM.  Also see
110 \fBwimlib-imagex optimize\fR.
111 .TP
112 \fB--ref\fR="\fIGLOB\fR"
113 File glob of additional WIMs or split WIM parts to reference resources from.
114 See \fBSPLIT_WIMS\fR.  This option can be specified multiple times.  Note:
115 \fIGLOB\fR is listed in quotes because it is interpreted by
116 \fBwimlib-imagex\fR and may need to be quoted to protect against shell
117 expansion.
118 .TP
119 \fB--pipable\fR
120 Build, or rebuild, \fIDEST_WIMFILE\fR as a "pipable WIM" so that it can be
121 applied fully sequentially, including from a pipe.  See \fBwimlib-imagex
122 capture\fR(1) for more details about creating pipable WIMs.  The default without
123 this option is to make \fIDEST_WIMFILE\fR pipable if and only if it already
124 existed and was already pipable, or was "-" (standard output).
125 .TP
126 \fB--not-pipable\fR
127 Build, or rebuild, \fIDEST_WIMFILE\fR as a normal, non-pipable WIM.  This is the
128 default behavior, unless \fIDEST_WIMFILE\fR already existed and was already
129 pipable, or if \fIDEST_WIMFILE\fR was "-" (standard output).
130 .TP
131 \fB--wimboot\fR
132 Mark the destination image as WIMBoot-compatible.  Also, if exporting to a new
133 archive, set the compression type to that recommended for WIMBoot (currently,
134 XPRESS with 4096 byte chunks).
135 .TP
136 \fB--unsafe-compact\fR
137 See the documentation for this option in \fBwimlib-imagex-optimize\fR (1).
139 You may use \fBwimlib-imagex export\fR to export images from a split WIM.
140 The \fISRC_WIMFILE\fR argument must specify the first part of the split WIM,
141 while the additional parts of the split WIM must be specified in one or more
142 \fB--ref\fR="\fIGLOB\fR" options.  Since globbing is built into the \fB--ref\fR
143 option, typically only one \fB--ref\fR option is necessary.  For example, the
144 names for the split WIM parts usually go something like:
145 .PP
146 .RS
147 .nf
148 mywim.swm
149 mywim2.swm
150 mywim3.swm
151 mywim4.swm
152 mywim5.swm
153 .RE
154 .PP
155 To export the first image of this split WIM to a new or existing WIM file
156 "other.wim", run:
157 .PP
158 .RS
159 wimlib-imagex export mywim.swm 1 other.wim --ref="mywim*.swm"
160 .RE
162 \fIData integrity\fR: Except when using \fB--unsafe-compact\fR, it is safe to
163 abort a \fBwimlib-imagex export\fR command partway through.  However, after
164 doing this, it is recommended to run \fBwimlib-imagex optimize\fR on the
165 destination WIM to remove any data that was appended to the physical WIM file
166 but not yet incorporated into the structure of the WIM, unless the WIM was being
167 rebuilt (e.g. with \fB--rebuild\fR), in which case you should delete the
168 temporary file left over.
169 .PP
170 \fISingle instancing\fR: The WIM format uses single-instance streams (roughly,
171 "files").  When an image is exported, only the streams ("files") not already
172 present in the destination WIM will be copied.  However, a new copy of the
173 image's metadata resource, which describes the full directory structure, will
174 always be created.
175 .PP
176 \fIESD files\fR: wimlib v1.6.0 and later can export images from version 3584
177 WIMs, which usually contain LZMS-compressed solid resources and may carry the
178 \fI.esd\fR file extension rather than \fI.wim\fR.  However, \fI.esd\fR files
179 downloaded directly by the Windows 8 web downloader have encrypted segments, and
180 wimlib cannot export images from such files until they are first decrypted.  In
181 addition, to ensure the destination archive is created in the original WIM
182 format rather than in the newer format, specify \fB--compress\fR=\fILZX\fR (or
183 \fB--compress\fR=\fImaximum\fR).
185 Export the second image of 'boot.wim' to the new WIM file 'new.wim':
186 .RS
187 .PP
188 wimlib-imagex export boot.wim 2 new.wim
189 .RE
190 .PP
191 The above example creates "new.wim" with the same compression type as
192 "boot.wim".  If you wish to change the compression type, specify
193 \fB--compress\fR=\fITYPE\fR; for example:
194 .RS
195 .PP
196 wimlib-imagex export boot.wim 2 new.wim --compress=LZX
197 .RE
198 .PP
199 Export "ESD to WIM" --- that is, solid WIM to non-solid WIM:
200 .RS
201 .PP
202 wimlib-imagex export install.esd all install.wim --compress=LZX
203 .RE
204 .PP
205 Export "WIM to ESD" --- that is, non-solid WIM to solid WIM:
206 .RS
207 .PP
208 wimlib-imagex export install.wim all install.esd --solid
209 .RE
210 .PP
212 .BR wimlib-imagex (1)
213 .BR wimlib-imagex-info (1)
214 .BR wimlib-imagex-optimize (1)