Update version to 1.4.2
[wimlib] / doc / imagex-export.1.in
1 .TH IMAGEX "1" "June 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
2 .SH NAME
3 @IMAGEX_PROGNAME@-export \- Exports an image from a WIM archive to an existing or new WIM archive
4 .SH SYNOPSIS
5 \fB@IMAGEX_PROGNAME@ export\fR \fISRC_WIMFILE\fR \fISRC_IMAGE\fR
6 \fIDEST_WIMFILE\fR [\fIDEST_IMAGE_NAME\fR\] [\fIDEST_IMAGE_DESCRIPTION\fR]
7 [\fIOPTION\fR...]
8 .SH DESCRIPTION
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 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 .PP
15 \fISRC_IMAGE\fR specifies the image in \fISRC_WIMFILE\fR to export.  It may be a
16 1-based index of an image in the WIM, the name of an image in the WIM, or the
17 keyword "all" to indicate that all images are to be exported.  Use the
18 \fB@IMAGEX_PROGNAME@ info\fR (1) command to list the images a WIM file contains.
19 .PP
20 If given, \fIDEST_IMAGE_NAME\fR specifies the name to give the image being
21 exported to \fIDEST_WIMFILE\fR.  The default is its name in \fISRC_WIMFILE\fR.
22 \fIDEST_IMAGE_NAME\fR cannot be specified if multiple images are being exported.
23 .PP
24 If given, \fIDEST_IMAGE_DESCRIPTION\fR specifies the description to give the
25 image being exported to \fIDEST_WIMFILE\fR.  The default is its description in
26 \fISRC_WIMFILE\fR.
27 .PP
28 \fB@IMAGEX_PROGNAME@ export\fR supports exporting images from stand-alone WIMs as well as
29 from split WIMs.  However, you cannot export an image to a split WIM.  See
30 \fBSPLIT WIMS\fR.
31 .PP
32 .SH OPTIONS
33 .TP 6
34 \fB--boot\fR
35 Specifies that the exported image is to be the bootable image of the destination
36 WIM archive.
37 .IP ""
38 If multiple images are being exported, this flag indicates that the image in the
39 \fISRC_WIMFILE\fR that is currently marked as bootable is to be made bootable in
40 \fIDEST_WIMFILE\fR.  If no image in \fISRC_WIMFILE\fR is bootable, it is an
41 error.
42 .TP
43 \fB--check\fR
44 When reading \fISRC_WIMFILE\fR, and \fIDEST_WIMFILE\fR if it exists, verify the
45 file's integrity if the integrity table is present; additionally, when writing
46 \fIDEST_WIMFILE\fR with the new image added, write an integrity table.  If this
47 option is not specified, no integrity table is included in \fIDEST_WIMFILE\fR,
48 even if there was one before.
49 .TP
50 \fB--compress\fR=\fITYPE\fR
51 Specifies the compression type for \fIDEST_WIMFILE\fR.  This is only valid if
52 \fIDEST_WIMFILE\fR does not yet exist, since if \fIDEST_WIMFILE\fR exists, the
53 compression type must be the same as that of \fIDEST_WIMFILE\fR.
54 .IP ""
55 \fITYPE\fR may be "none", "maximum", or "fast".  By default, it is the same as
56 that of the input WIM file.
57 .IP ""
58 You may also specify the actual names of the compression algorithms, "XPRESS"
59 and "LZX", instead of "fast" and "maximum", respectively.
60 .TP
61 \fB--threads\fR=\fINUM_THREADS\fR
62 Number of threads to use for compressing data.  Default: autodetect (number of
63 processors).  Note: if exporting to an uncompressed WIM, or exporting to a WIM
64 with the same compression type as the source WIM, additional threads will not
65 be used, regardless of this parameter, since no data compression needs to be
66 done in these cases.
67 .TP
68 \fB--rebuild\fR
69 When exporting image(s) to an existing WIM: rebuild the entire WIM rather than
70 appending data to the end of it.  Rebuilding the WIM is slower, but will save a
71 little bit of space that would otherwise be left as a hole in the WIM.  Also see
72 \fB@IMAGEX_PROGNAME@ optimize\fR.
73 .TP
74 \fB--ref\fR="\fIGLOB\fR"
75 File glob of additional split WIM parts that are part of the split WIM being
76 exported.  See \fBSPLIT_WIMS\fR.
77 .SH SPLIT WIMS
78 You may use \fB@IMAGEX_PROGNAME@ export\fR to export images from a split WIM.  The
79 \fISRC_WIMFILE\fR argument is used to specify the first part of the split WIM, and
80 the \fB--refs\fR="\fIGLOB\fR" option is used to provide a shell-style file glob
81 that specifies the additional parts of the split WIM.  \fIGLOB\fR is expected to
82 be a single string on the command line, so \fIGLOB\fR must be quoted so that it
83 is protected against shell expansion.  \fIGLOB\fR must expand to all parts of
84 the split WIM, except optionally the first part which may either omitted or
85 included in the glob (but the first part MUST be specified as \fISRC_WIMFILE\fR as
86 well).
87 .PP
88 Here's an example.  The names for the split WIMs usually go something like:
89 .PP
90 .RS
91 .nf
92 mywim.swm
93 mywim2.swm
94 mywim3.swm
95 mywim4.swm
96 mywim5.swm
97 .RE
98 .PP
99 To export the first image of this split WIM to a new or existing WIM file
100 "other.wim", run:
101 .PP
102 .RS
103 @IMAGEX_PROGNAME@ export mywim.swm 1 other.wim --ref="mywim*.swm"
104 .RE
105 .SH NOTES
106 It is safe to abort an \fB@IMAGEX_PROGNAME@ export\fR command partway through;
107 however, after doing this, it is recommended to run \fB@IMAGEX_PROGNAME@
108 optimize\fR on the destination WIM to remove any data that was appended to the
109 physical WIM file but not yet incorporated into the structure of the WIM, unless
110 \fB--rebuild\fR was specified, in which case you should delete the temporary
111 file left over.
112 .SH EXAMPLES
113 Export the second image of 'boot.wim' to the new WIM file 'new.wim', and
114 change the compression type to maximum, if it wasn't maximum already:
115 .RS
116 .PP
117 @IMAGEX_PROGNAME@ export boot.wim 2 new.wim --compress=maximum
118 .RE
119 .PP
120 .SH SEE ALSO
121 .BR @IMAGEX_PROGNAME@ (1)
122 .BR @IMAGEX_PROGNAME@-info (1)
123 .BR @IMAGEX_PROGNAME@-optimize (1)