.TH WIMLIB-IMAGEX "1" "December 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
.SH NAME
@IMAGEX_PROGNAME@-export \- Exports an image from a WIM archive to an existing or new WIM archive
.SH SYNOPSIS
\fB@IMAGEX_PROGNAME@ export\fR \fISRC_WIMFILE\fR \fISRC_IMAGE\fR
\fIDEST_WIMFILE\fR [\fIDEST_IMAGE_NAME\fR [\fIDEST_IMAGE_DESCRIPTION\fR]]
[\fIOPTION\fR...]
.SH DESCRIPTION
Copies the specified image in \fISRC_WIMFILE\fR to \fIDEST_WIMFILE\fR,
optionally changing its name and/or description and/or compression type.
If \fIDEST_WIMFILE\fR exists, it is taken be be a WIM archive to which the image
will be appended.  Otherwise, it is created as a new WIM archive containing only
the exported image.
This command is also available as simply \fBwimexport\fR if the appropriate hard
link or batch file has been installed.
.PP
\fISRC_IMAGE\fR specifies the image in \fISRC_WIMFILE\fR to export.  It may be a
1-based index of an image in \fISRC_WIMFILE\fR, the name of an image in
\fISRC_WIMFILE\fR, or the keyword "all" to indicate that all images in
\fISRC_WIMFILE\fR are to be exported.  Use the \fB@IMAGEX_PROGNAME@ info\fR (1)
command to list the images a WIM file contains.
.PP
If specified, \fIDEST_IMAGE_NAME\fR is the name to give the image being exported
to \fIDEST_WIMFILE\fR.  The default is its name in \fISRC_WIMFILE\fR.
\fIDEST_IMAGE_NAME\fR cannot be specified if multiple images are being exported.
.PP
If specified, \fIDEST_IMAGE_DESCRIPTION\fR is the description to give the image
being exported to \fIDEST_WIMFILE\fR.  The default is its description in
\fISRC_WIMFILE\fR.
.PP
\fB@IMAGEX_PROGNAME@ export\fR supports exporting images from stand-alone WIMs as well as
from split WIMs.  However, you cannot export an image to a split WIM.  See
\fBSPLIT WIMS\fR.
.PP
\fB@IMAGEX_PROGNAME@ export\fR also supports exporting images from a non-pipable
WIM into a (possibly new) pipable WIM, and vice versa.  Furthermore, it will
export a pipable WIM directly to standard output if "-" is specified as
\fIDEST_WIMFILE\fR (this implies \fB--pipable\fR).  See \fB--pipable\fR and
\fB--not-pipable\fR.
.PP
.SH OPTIONS
.TP 6
\fB--boot\fR
Specifies that the exported image is to be the bootable image of the destination
WIM archive.
.IP ""
If multiple images are being exported, this flag indicates that the image in the
\fISRC_WIMFILE\fR that is currently marked as bootable is to be made bootable in
\fIDEST_WIMFILE\fR.  If no image in \fISRC_WIMFILE\fR is bootable, it is an
error.
.TP
\fB--check\fR
When reading \fISRC_WIMFILE\fR, and \fIDEST_WIMFILE\fR if it exists, verify the
file's integrity if the integrity table is present; additionally, when writing
\fIDEST_WIMFILE\fR with the new image(s) added, write an integrity table.
If neither \fB--check\fR nor \fB--nocheck\fR is specified, an integrity
table is included in \fIDEST_WIMFILE\fR if and only if \fIDEST_WIMFILE\fR
already existed and it had an integrity table before.
.TP
\fB--nocheck\fR
When writing \fIDEST_WIMFILE\fR with the new image(s) added, do not write an
integrity table.
If neither \fB--check\fR nor \fB--nocheck\fR is specified, an integrity
table is included in \fIDEST_WIMFILE\fR if and only if \fIDEST_WIMFILE\fR
already existed and it had an integrity table before.
.TP
\fB--compress\fR=\fITYPE\fR
Specifies the compression type for \fIDEST_WIMFILE\fR.  This is only valid if
\fIDEST_WIMFILE\fR does not yet exist, since if \fIDEST_WIMFILE\fR exists, the
compression type must be the same as that of \fIDEST_WIMFILE\fR.
.IP ""
\fITYPE\fR may be "none", "maximum", or "fast".  By default, it is the same as
that of the input WIM file.
.IP ""
You may also specify the actual names of the compression algorithms, "XPRESS"
and "LZX", instead of "fast" and "maximum", respectively.
.IP ""
\fITYPE\fR may also be "recovery" (or "LZMS"); however, this will result in
reduced compatibility.  See the documentation for this option to
\fB@IMAGEX_PROGNAME@ capture\fR (1) for more details.
.TP
\fB--pack-streams\fR
Create a "solid" archive that compresses multiple files together.  This can
result in a higher compression ratio, but has disadvantages such as reduced
compatibility; see the documentation for this option to
\fB@IMAGEX_PROGNAME@ capture\fR (1) for more details.
.TP
\fB--threads\fR=\fINUM_THREADS\fR
Number of threads to use for compressing data.  Default: autodetect (number of
processors).  Note: multiple compressor threads are not very useful when
exporting to a WIM with the same compression type as the source WIM, since
wimlib optimizes this case by re-using the raw compressed data.
.TP
\fB--rebuild\fR
When exporting image(s) to an existing WIM: rebuild the entire WIM rather than
appending data to the end of it.  Rebuilding the WIM is slower, but will save a
little bit of space that would otherwise be left as a hole in the WIM.  Also see
\fB@IMAGEX_PROGNAME@ optimize\fR.
.TP
\fB--ref\fR="\fIGLOB\fR"
File glob of additional WIMs or split WIM parts to reference resources from.
See \fBSPLIT_WIMS\fR.  This option can be specified multiple times.  Note:
\fIGLOB\fR is listed in quotes because it is interpreted by
\fB@IMAGEX_PROGNAME@\fR and may need to be quoted to protect against shell
expansion.
.TP
\fB--pipable\fR
Build, or rebuild, \fIDEST_WIMFILE\fR as a "pipable WIM" so that it can be
applied fully sequentially, including from a pipe.  See \fB@IMAGEX_PROGNAME@
capture\fR(1) for more details about creating pipable WIMs.  The default without
this option is to make \fIDEST_WIMFILE\fR pipable if and only if it already
existed and was already pipable, or was "-" (standard output).
.TP
\fB--not-pipable\fR
Build, or rebuild, \fIDEST_WIMFILE\fR as a normal, non-pipable WIM.  This is the
default behavior, unless \fIDEST_WIMFILE\fR already existed and was already
pipable, or if \fIDEST_WIMFILE\fR was "-" (standard output).
.SH SPLIT WIMS
You may use \fB@IMAGEX_PROGNAME@ export\fR to export images from a split WIM.
The \fISRC_WIMFILE\fR argument must specify the first part of the split WIM,
while the additional parts of the split WIM must be specified in one or more
\fB--ref\fR="\fIGLOB\fR" options.  Since globbing is built into the \fB--ref\fR
option, typically only one \fB--ref\fR option is necessary.  For example, the
names for the split WIM parts usually go something like:
.PP
.RS
.nf
mywim.swm
mywim2.swm
mywim3.swm
mywim4.swm
mywim5.swm
.RE
.PP
To export the first image of this split WIM to a new or existing WIM file
"other.wim", run:
.PP
.RS
@IMAGEX_PROGNAME@ export mywim.swm 1 other.wim --ref="mywim*.swm"
.RE
.SH NOTES
It is safe to abort an \fB@IMAGEX_PROGNAME@ export\fR command partway through;
however, after doing this, it is recommended to run \fB@IMAGEX_PROGNAME@
optimize\fR on the destination WIM to remove any data that was appended to the
physical WIM file but not yet incorporated into the structure of the WIM, unless
the WIM was being rebuild (e.g. with \fB--rebuild\fR), in which case you should
delete the temporary file left over.
.PP
Since the WIM format uses single-instancing (streams are content-addressed by
SHA1 message digests), when an image is exported, only the streams not already
present in the destination WIM need to be copied.  However, a new copy of the
image's metadata resource always needs to be created.
.PP
.SH EXAMPLES
Export the second image of 'boot.wim' to the new WIM file 'new.wim':
.RS
.PP
@IMAGEX_PROGNAME@ export boot.wim 2 new.wim
.RE
.PP
The above example creates "new.wim" with the same compression type as
"boot.wim".  If you wish to change the compression type, specify
\fB--compress\fR=\fITYPE\fR; for example:
.RS
.PP
@IMAGEX_PROGNAME@ export boot.wim 2 new.wim --compress=maximum
.RE
.PP
.SH SEE ALSO
.BR @IMAGEX_PROGNAME@ (1)
.BR @IMAGEX_PROGNAME@-info (1)
.BR @IMAGEX_PROGNAME@-optimize (1)