X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=doc%2Fimagex-export.1.in;h=bd24e36cd1a374447d93e1b249a980ab0d8d5ae4;hp=e0ad169aef3712b7f5a6bd77b934c73e6f076ca7;hb=731a41d6d86be9c27e9f1f99bb35ee3772cb0f61;hpb=72bca3eaa105979a551612a56812250d44f9b049 diff --git a/doc/imagex-export.1.in b/doc/imagex-export.1.in index e0ad169a..bd24e36c 100644 --- a/doc/imagex-export.1.in +++ b/doc/imagex-export.1.in @@ -1,44 +1,49 @@ -.TH IMAGEX "1" "March 2013" "imagex (wimlib) wimlib @VERSION@" "User Commands" +.TH WIMLIB-IMAGEX "1" "January 2014" "@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. - -\fBimagex export\fR supports exporting images from stand-alone WIMs as well as +.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 @@ -47,54 +52,87 @@ error. \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 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. +\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--compress-slow\fR +Spend even more time compressing the data to achieve a very slightly better +compression ratio. This currently only has an effect for LZX ("maximum") and +LZMS ("recovery") compression. This option does not itself set the compression +format. +.TP +\fB--pack-streams\fR, \fB--solid\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--pack-chunk-size\fR=\fISIZE\fR, \fB--solid-chunk-size\fR=\fISIZE\fR +Like \fB--chunk-size\fR, but set the chunk size used in packed resources. .TP \fB--threads\fR=\fINUM_THREADS\fR Number of threads to use for compressing data. Default: autodetect (number of -processors). Note: if exporting to an uncompressed WIM, or exporting to a WIM -with the same compression type as the source WIM, additional threads will not -be used, regardless of this parameter, since no data compression needs to be -done in these cases. +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 -\fBimagex optimize\fR. +\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. - +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 \fBimagex 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). - -Here's an example. The names for the split WIMs usually go something like: - -.RS +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 @@ -102,33 +140,42 @@ 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 export mywim.swm 1 other.wim --ref="mywim*.swm" +@IMAGEX_PROGNAME@ export mywim.swm 1 other.wim --ref="mywim*.swm" .RE -.PP - .SH NOTES - -Unless \fB--rebuild\fR is specified, aborting an \fBimagex export\fR command -mid-way through has a small chance of corrupting the destination WIM file. -However, a precaution is taken against this, so it should be very unlikely. In -the event of an aborted \fBimagex export\fR, \fBimagex optimize\fR can be run to -remove extra data that may have been partially appended to the physical -destination WIM file but not yet incorporated into the structure of the WIM. - +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', 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 -image export boot.wim 2 new.wim --compress=maximum +@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)