]> wimlib.net Git - wimlib/blob - doc/imagex-export.1.in
wimlib-imagex documentation updates
[wimlib] / doc / imagex-export.1.in
1 .TH WIMLIB-IMAGEX "1" "August 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 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 \fB@IMAGEX_PROGNAME@ 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
29 \fISRC_WIMFILE\fR.
30 .PP
31 \fB@IMAGEX_PROGNAME@ 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
33 \fBSPLIT WIMS\fR.
34 .PP
35 \fB@IMAGEX_PROGNAME@ 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
41 .SH OPTIONS
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
68 Specifies the compression type for \fIDEST_WIMFILE\fR.  This is only valid if
69 \fIDEST_WIMFILE\fR does not yet exist, since if \fIDEST_WIMFILE\fR exists, the
70 compression type must be the same as that of \fIDEST_WIMFILE\fR.
71 .IP ""
72 \fITYPE\fR may be "none", "maximum", or "fast".  By default, it is the same as
73 that of the input WIM file.
74 .IP ""
75 You may also specify the actual names of the compression algorithms, "XPRESS"
76 and "LZX", instead of "fast" and "maximum", respectively.
77 .TP
78 \fB--threads\fR=\fINUM_THREADS\fR
79 Number of threads to use for compressing data.  Default: autodetect (number of
80 processors).  Note: multiple compressor threads are not very useful when
81 exporting to a WIM with the same compression type as the source WIM, since
82 wimlib optimizes this case by re-using the raw compressed data.
83 .TP
84 \fB--rebuild\fR
85 When exporting image(s) to an existing WIM: rebuild the entire WIM rather than
86 appending data to the end of it.  Rebuilding the WIM is slower, but will save a
87 little bit of space that would otherwise be left as a hole in the WIM.  Also see
88 \fB@IMAGEX_PROGNAME@ optimize\fR.
89 .TP
90 \fB--ref\fR="\fIGLOB\fR"
91 File glob of additional split WIM parts that are part of the split WIM being
92 exported.  See \fBSPLIT_WIMS\fR.
93 .TP
94 \fB--pipable\fR
95 Build, or rebuild, \fIDEST_WIMFILE\fR as a "pipable WIM" so that it can be
96 applied fully sequentially, including from a pipe.  See \fB@IMAGEX_PROGNAME@
97 capture\fR(1) for more details about creating pipable WIMs.  The default without
98 this option is to make \fIDEST_WIMFILE\fR pipable if and only if it already
99 existed and was already pipable, or was "-" (standard output).
100 .TP
101 \fB--not-pipable\fR
102 Build, or rebuld, \fIDEST_WIMFILE\fR as a normal, non-pipable WIM.  This is the
103 default behavior, unless \fIDEST_WIMFILE\fR already existed and was already
104 pipable, or if \fIDEST_WIMFILE\fR was "-" (standard output).
105 .SH SPLIT WIMS
106 You may use \fB@IMAGEX_PROGNAME@ export\fR to export images from a split WIM.  The
107 \fISRC_WIMFILE\fR argument is used to specify the first part of the split WIM, and
108 the \fB--refs\fR="\fIGLOB\fR" option is used to provide a shell-style file glob
109 that specifies the additional parts of the split WIM.  \fIGLOB\fR is expected to
110 be a single string on the command line, so \fIGLOB\fR must be quoted so that it
111 is protected against shell expansion.  \fIGLOB\fR must expand to all parts of
112 the split WIM, except optionally the first part which may either omitted or
113 included in the glob (but the first part MUST be specified as \fISRC_WIMFILE\fR as
114 well).
115 .PP
116 Here's an example.  The names for the split WIMs usually go something like:
117 .PP
118 .RS
119 .nf
120 mywim.swm
121 mywim2.swm
122 mywim3.swm
123 mywim4.swm
124 mywim5.swm
125 .RE
126 .PP
127 To export the first image of this split WIM to a new or existing WIM file
128 "other.wim", run:
129 .PP
130 .RS
131 @IMAGEX_PROGNAME@ export mywim.swm 1 other.wim --ref="mywim*.swm"
132 .RE
133 .SH NOTES
134 It is safe to abort an \fB@IMAGEX_PROGNAME@ export\fR command partway through;
135 however, after doing this, it is recommended to run \fB@IMAGEX_PROGNAME@
136 optimize\fR on the destination WIM to remove any data that was appended to the
137 physical WIM file but not yet incorporated into the structure of the WIM, unless
138 the WIM was being rebuild (e.g. with \fB--rebuild\fR), in which case you should
139 delete the temporary file left over.
140 .PP
141 Since the WIM format uses single-instancing (streams are content-addressed by
142 SHA1 message digests), when an image is exported, only the streams not already
143 present in the destination WIM need to be copied.  However, a new copy of the
144 image's metadata resource always needs to be created.
145 .PP
146 .SH EXAMPLES
147 Export the second image of 'boot.wim' to the new WIM file 'new.wim':
148 .RS
149 .PP
150 @IMAGEX_PROGNAME@ export boot.wim 2 new.wim
151 .RE
152 .PP
153 The above example creates "new.wim" with the same compression type as
154 "boot.wim".  If you wish to change the compression type, specify
155 \fB--compress\fR=\fITYPE\fR; for example:
156 .RS
157 .PP
158 @IMAGEX_PROGNAME@ export boot.wim 2 new.wim --compress=maximum
159 .RE
160 .PP
161 .SH SEE ALSO
162 .BR @IMAGEX_PROGNAME@ (1)
163 .BR @IMAGEX_PROGNAME@-info (1)
164 .BR @IMAGEX_PROGNAME@-optimize (1)