wimlib.net Git - wimlib/blob - doc/imagex-export.1.in

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