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

   1 .TH 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 is 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 the WIM, the name of an image in the WIM, or the
  19 keyword "all" to indicate that all images are to be exported.  Use the
  20 \fB@IMAGEX_PROGNAME@ info\fR (1) command to list the images a WIM file contains.
  21 .PP
  22 If given, \fIDEST_IMAGE_NAME\fR specifies the name to give the image being
  23 exported to \fIDEST_WIMFILE\fR.  The default is its name in \fISRC_WIMFILE\fR.
  24 \fIDEST_IMAGE_NAME\fR cannot be specified if multiple images are being exported.
  25 .PP
  26 If given, \fIDEST_IMAGE_DESCRIPTION\fR specifies the description to give the
  27 image being exported to \fIDEST_WIMFILE\fR.  The default is its description in
  28 \fISRC_WIMFILE\fR.
  29 .PP
  30 \fB@IMAGEX_PROGNAME@ export\fR supports exporting images from stand-alone WIMs as well as
  31 from split WIMs.  However, you cannot export an image to a split WIM.  See
  32 \fBSPLIT WIMS\fR.
  33 .PP
  34 \fB@IMAGEX_PROGNAME@ export\fR also supports exporting images from a non-pipable
  35 WIM into a (possibly new) pipable WIM, and vice versa.  See \fB--pipable\fR and
  36 \fB--not-pipable\fR.
  37 .PP
  38 .SH OPTIONS
  39 .TP 6
  40 \fB--boot\fR
  41 Specifies that the exported image is to be the bootable image of the destination
  42 WIM archive.
  43 .IP ""
  44 If multiple images are being exported, this flag indicates that the image in the
  45 \fISRC_WIMFILE\fR that is currently marked as bootable is to be made bootable in
  46 \fIDEST_WIMFILE\fR.  If no image in \fISRC_WIMFILE\fR is bootable, it is an
  47 error.
  48 .TP
  49 \fB--check\fR
  50 When reading \fISRC_WIMFILE\fR, and \fIDEST_WIMFILE\fR if it exists, verify the
  51 file's integrity if the integrity table is present; additionally, when writing
  52 \fIDEST_WIMFILE\fR with the new image(s) added, write an integrity table.
  53 If neither \fB--check\fR nor \fB--nocheck\fR is specified, an integrity
  54 table is included in \fIDEST_WIMFILE\fR if and only if \fIDEST_WIMFILE\fR
  55 already existed and it had an integrity table before.
  56 .TP
  57 \fB--nocheck\fR
  58 When writing \fIDEST_WIMFILE\fR with the new image(s) added, do not write an
  59 integrity table.
  60 If neither \fB--check\fR nor \fB--nocheck\fR is specified, an integrity
  61 table is included in \fIDEST_WIMFILE\fR if and only if \fIDEST_WIMFILE\fR
  62 already existed and it had an integrity table before.
  63 .TP
  64 \fB--compress\fR=\fITYPE\fR
  65 Specifies the compression type for \fIDEST_WIMFILE\fR.  This is only valid if
  66 \fIDEST_WIMFILE\fR does not yet exist, since if \fIDEST_WIMFILE\fR exists, the
  67 compression type must be the same as that of \fIDEST_WIMFILE\fR.
  68 .IP ""
  69 \fITYPE\fR may be "none", "maximum", or "fast".  By default, it is the same as
  70 that of the input WIM file.
  71 .IP ""
  72 You may also specify the actual names of the compression algorithms, "XPRESS"
  73 and "LZX", instead of "fast" and "maximum", respectively.
  74 .TP
  75 \fB--threads\fR=\fINUM_THREADS\fR
  76 Number of threads to use for compressing data.  Default: autodetect (number of
  77 processors).  Note: if exporting to an uncompressed WIM, or exporting to a WIM
  78 with the same compression type as the source WIM, additional threads will not
  79 be used, regardless of this parameter, since no data compression needs to be
  80 done in these cases.
  81 .TP
  82 \fB--rebuild\fR
  83 When exporting image(s) to an existing WIM: rebuild the entire WIM rather than
  84 appending data to the end of it.  Rebuilding the WIM is slower, but will save a
  85 little bit of space that would otherwise be left as a hole in the WIM.  Also see
  86 \fB@IMAGEX_PROGNAME@ optimize\fR.
  87 .TP
  88 \fB--ref\fR="\fIGLOB\fR"
  89 File glob of additional split WIM parts that are part of the split WIM being
  90 exported.  See \fBSPLIT_WIMS\fR.
  91 .TP
  92 \fB--pipable\fR
  93 Build, or rebuild, \fIDEST_WIMFILE\fR as a "pipable WIM" so that it can be
  94 applied fully sequentially, including from a pipe.  See \fB@IMAGEX_PROGNAME@
  95 capture\fR(1) for more details about creating pipable WIMs.  The default without
  96 this option is to make \fIDEST_WIMFILE\fR pipable if and only if it already
  97 existed and was already pipable.
  98 .TP
  99 \fB--not-pipable\fR
 100 Build, or rebuld, \fIDEST_WIMFILE\fR as a normal, non-pipable WIM.  This is the
 101 default behavior, unless \fIDEST_WIMFILE\fR already existed and was already
 102 pipable.
 103 .SH SPLIT WIMS
 104 You may use \fB@IMAGEX_PROGNAME@ export\fR to export images from a split WIM.  The
 105 \fISRC_WIMFILE\fR argument is used to specify the first part of the split WIM, and
 106 the \fB--refs\fR="\fIGLOB\fR" option is used to provide a shell-style file glob
 107 that specifies the additional parts of the split WIM.  \fIGLOB\fR is expected to
 108 be a single string on the command line, so \fIGLOB\fR must be quoted so that it
 109 is protected against shell expansion.  \fIGLOB\fR must expand to all parts of
 110 the split WIM, except optionally the first part which may either omitted or
 111 included in the glob (but the first part MUST be specified as \fISRC_WIMFILE\fR as
 112 well).
 113 .PP
 114 Here's an example.  The names for the split WIMs usually go something like:
 115 .PP
 116 .RS
 117 .nf
 118 mywim.swm
 119 mywim2.swm
 120 mywim3.swm
 121 mywim4.swm
 122 mywim5.swm
 123 .RE
 124 .PP
 125 To export the first image of this split WIM to a new or existing WIM file
 126 "other.wim", run:
 127 .PP
 128 .RS
 129 @IMAGEX_PROGNAME@ export mywim.swm 1 other.wim --ref="mywim*.swm"
 130 .RE
 131 .SH NOTES
 132 It is safe to abort an \fB@IMAGEX_PROGNAME@ export\fR command partway through;
 133 however, after doing this, it is recommended to run \fB@IMAGEX_PROGNAME@
 134 optimize\fR on the destination WIM to remove any data that was appended to the
 135 physical WIM file but not yet incorporated into the structure of the WIM, unless
 136 \fB--rebuild\fR was specified, in which case you should delete the temporary
 137 file left over.
 138 .SH EXAMPLES
 139 Export the second image of 'boot.wim' to the new WIM file 'new.wim', and
 140 change the compression type to maximum, if it wasn't maximum already:
 141 .RS
 142 .PP
 143 @IMAGEX_PROGNAME@ export boot.wim 2 new.wim --compress=maximum
 144 .RE
 145 .PP
 146 .SH SEE ALSO
 147 .BR @IMAGEX_PROGNAME@ (1)
 148 .BR @IMAGEX_PROGNAME@-info (1)
 149 .BR @IMAGEX_PROGNAME@-optimize (1)