-.TH IMAGEX "1" "May 2012" "imagex (wimlib) wimlib @VERSION@" "User Commands"
+.TH WIMLIB-IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
.SH NAME
-imagex export \- Exports an image from a WIM archive to an existing or new WIM archive
-
+@IMAGEX_PROGNAME@-export \- Exports an image from a WIM archive to an existing or new WIM archive
.SH SYNOPSIS
-\fBimagex export\fR \fISRC_WIMFILE\fR (\fISRC_IMAGE_NUM\fR | \
-\fISRC_IMAGE_NAME\fR | all ) \fIDEST_WIMFILE\fR [\fIDEST_IMAGE_NAME\fR\] \
-[\fIDEST_IMAGE_DESCRIPTION\fR] [\fIOPTION\fR]...
-
+\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
-.PP
-
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.
-
-The source image may be specified by \fISRC_IMAGE_NUM\fR, which must be an integer that is
-an index of an image in \fISRC_WIMFILE\fR, starting at 1. Alternatively, it may be
-the name of an image in \fISRC_WIMFILE\fR, or it may be the keyword "all" to
-specify that all images are to be exported.
-
-If given, \fIDEST_IMAGE_NAME\fR specifies the name to give the image being
-exported to \fIDEST_WIMFILE\fR. The default is its name in \fISRC_WIMFILE\fR.
+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.
-
-If given, \fIDEST_IMAGE_DESCRIPTION\fR specifies the description to give the
-image being exported to \fIDEST_WIMFILE\fR. The default is its description in
+.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 WIM archive.
-
+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, verify its integrity if the integrity table is
-present; additionally, when writing \fIDEST_WIMFILE\fR with the new image added,
-write an integrity table. If this option is not specified, no integrity table
-is included in \fIDEST_WIMFILE\fR, even if there was one before.
+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]
+\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.
-
-\fITYPE\fR may be "none",
-"maximum", or "fast". By default, the compression type is "none". If \fB--compress\fR
-is specified but \fITYPE\fR is not, the compression type is taken to be
-"maximum", which is LZX compression. "fast" compression is XPRESS compression.
-
+\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.
+.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 split WIM parts that are part of the split WIM being
+exported. See \fBSPLIT_WIMS\fR.
+.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 rebuld, \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 is used to specify the first part of the split WIM, and
+the \fB--refs\fR="\fIGLOB\fR" option is used to provide a shell-style file glob
+that specifies the additional parts of the split WIM. \fIGLOB\fR is expected to
+be a single string on the command line, so \fIGLOB\fR must be quoted so that it
+is protected against shell expansion. \fIGLOB\fR must expand to all parts of
+the split WIM, except optionally the first part which may either omitted or
+included in the glob (but the first part MUST be specified as \fISRC_WIMFILE\fR as
+well).
+.PP
+Here's an example. The names for the split WIMs 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
-.IP
-image export boot.wim 2 image2.wim --compress=maximum
-.LP
-Export the second image of 'boot.wim' to the new WIM file 'image2.wim', and
-change the compression type to maximum, if it wasn't maximum already.
-
+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 (1)
-
+.BR @IMAGEX_PROGNAME@ (1)
+.BR @IMAGEX_PROGNAME@-info (1)
+.BR @IMAGEX_PROGNAME@-optimize (1)
git://wimlib.net / wimlib / blobdiff