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

   1 .TH WIMLIB-IMAGEX "1" "December 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 or batch file has been 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 \fISRC_WIMFILE\fR, the name of an image in
  19 \fISRC_WIMFILE\fR, or the keyword "all" to indicate that all images in
  20 \fISRC_WIMFILE\fR are to be exported.  Use the \fB@IMAGEX_PROGNAME@ info\fR (1)
  21 command to list the images a WIM file contains.
  22 .PP
  23 If specified, \fIDEST_IMAGE_NAME\fR is the name to give the image being exported
  24 to \fIDEST_WIMFILE\fR.  The default is its name in \fISRC_WIMFILE\fR.
  25 \fIDEST_IMAGE_NAME\fR cannot be specified if multiple images are being exported.
  26 .PP
  27 If specified, \fIDEST_IMAGE_DESCRIPTION\fR is the description to give the image
  28 being exported to \fIDEST_WIMFILE\fR.  The default is its description in
  29 \fISRC_WIMFILE\fR.
  30 .PP
  31 \fB@IMAGEX_PROGNAME@ export\fR supports exporting images from stand-alone WIMs as well as
  32 from split WIMs.  However, you cannot export an image to a split WIM.  See
  33 \fBSPLIT WIMS\fR.
  34 .PP
  35 \fB@IMAGEX_PROGNAME@ export\fR also supports exporting images from a non-pipable
  36 WIM into a (possibly new) pipable WIM, and vice versa.  Furthermore, it will
  37 export a pipable WIM directly to standard output if "-" is specified as
  38 \fIDEST_WIMFILE\fR (this implies \fB--pipable\fR).  See \fB--pipable\fR and
  39 \fB--not-pipable\fR.
  40 .PP
  41 .SH OPTIONS
  42 .TP 6
  43 \fB--boot\fR
  44 Specifies that the exported image is to be the bootable image of the destination
  45 WIM archive.
  46 .IP ""
  47 If multiple images are being exported, this flag indicates that the image in the
  48 \fISRC_WIMFILE\fR that is currently marked as bootable is to be made bootable in
  49 \fIDEST_WIMFILE\fR.  If no image in \fISRC_WIMFILE\fR is bootable, it is an
  50 error.
  51 .TP
  52 \fB--check\fR
  53 When reading \fISRC_WIMFILE\fR, and \fIDEST_WIMFILE\fR if it exists, verify the
  54 file's integrity if the integrity table is present; additionally, when writing
  55 \fIDEST_WIMFILE\fR with the new image(s) added, write an integrity table.
  56 If neither \fB--check\fR nor \fB--nocheck\fR is specified, an integrity
  57 table is included in \fIDEST_WIMFILE\fR if and only if \fIDEST_WIMFILE\fR
  58 already existed and it had an integrity table before.
  59 .TP
  60 \fB--nocheck\fR
  61 When writing \fIDEST_WIMFILE\fR with the new image(s) added, do not write an
  62 integrity table.
  63 If neither \fB--check\fR nor \fB--nocheck\fR is specified, an integrity
  64 table is included in \fIDEST_WIMFILE\fR if and only if \fIDEST_WIMFILE\fR
  65 already existed and it had an integrity table before.
  66 .TP
  67 \fB--compress\fR=\fITYPE\fR
  68 Specifies the compression type for \fIDEST_WIMFILE\fR.  This is only valid if
  69 \fIDEST_WIMFILE\fR does not yet exist, since if \fIDEST_WIMFILE\fR exists, the
  70 compression type must be the same as that of \fIDEST_WIMFILE\fR.
  71 .IP ""
  72 \fITYPE\fR may be "none", "maximum", or "fast".  By default, it is the same as
  73 that of the input WIM file.
  74 .IP ""
  75 You may also specify the actual names of the compression algorithms, "XPRESS"
  76 and "LZX", instead of "fast" and "maximum", respectively.
  77 .TP
  78 \fB--threads\fR=\fINUM_THREADS\fR
  79 Number of threads to use for compressing data.  Default: autodetect (number of
  80 processors).  Note: multiple compressor threads are not very useful when
  81 exporting to a WIM with the same compression type as the source WIM, since
  82 wimlib optimizes this case by re-using the raw compressed data.
  83 .TP
  84 \fB--rebuild\fR
  85 When exporting image(s) to an existing WIM: rebuild the entire WIM rather than
  86 appending data to the end of it.  Rebuilding the WIM is slower, but will save a
  87 little bit of space that would otherwise be left as a hole in the WIM.  Also see
  88 \fB@IMAGEX_PROGNAME@ optimize\fR.
  89 .TP
  90 \fB--ref\fR="\fIGLOB\fR"
  91 File glob of additional WIMs or split WIM parts to reference resources from.
  92 See \fBSPLIT_WIMS\fR.  This option can be specified multiple times.  Note:
  93 \fIGLOB\fR is listed in quotes because it is interpreted by
  94 \fB@IMAGEX_PROGNAME@\fR and may need to be quoted to protect against shell
  95 expansion.
  96 .TP
  97 \fB--pipable\fR
  98 Build, or rebuild, \fIDEST_WIMFILE\fR as a "pipable WIM" so that it can be
  99 applied fully sequentially, including from a pipe.  See \fB@IMAGEX_PROGNAME@
 100 capture\fR(1) for more details about creating pipable WIMs.  The default without
 101 this option is to make \fIDEST_WIMFILE\fR pipable if and only if it already
 102 existed and was already pipable, or was "-" (standard output).
 103 .TP
 104 \fB--not-pipable\fR
 105 Build, or rebuild, \fIDEST_WIMFILE\fR as a normal, non-pipable WIM.  This is the
 106 default behavior, unless \fIDEST_WIMFILE\fR already existed and was already
 107 pipable, or if \fIDEST_WIMFILE\fR was "-" (standard output).
 108 .SH SPLIT WIMS
 109 You may use \fB@IMAGEX_PROGNAME@ export\fR to export images from a split WIM.
 110 The \fISRC_WIMFILE\fR argument must specify the first part of the split WIM,
 111 while the additional parts of the split WIM must be specified in one or more
 112 \fB--ref\fR="\fIGLOB\fR" options.  Since globbing is built into the \fB--ref\fR
 113 option, typically only one \fB--ref\fR option is necessary.  For example, the
 114 names for the split WIM parts 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 the WIM was being rebuild (e.g. with \fB--rebuild\fR), in which case you should
 137 delete the temporary file left over.
 138 .PP
 139 Since the WIM format uses single-instancing (streams are content-addressed by
 140 SHA1 message digests), when an image is exported, only the streams not already
 141 present in the destination WIM need to be copied.  However, a new copy of the
 142 image's metadata resource always needs to be created.
 143 .PP
 144 .SH EXAMPLES
 145 Export the second image of 'boot.wim' to the new WIM file 'new.wim':
 146 .RS
 147 .PP
 148 @IMAGEX_PROGNAME@ export boot.wim 2 new.wim
 149 .RE
 150 .PP
 151 The above example creates "new.wim" with the same compression type as
 152 "boot.wim".  If you wish to change the compression type, specify
 153 \fB--compress\fR=\fITYPE\fR; for example:
 154 .RS
 155 .PP
 156 @IMAGEX_PROGNAME@ export boot.wim 2 new.wim --compress=maximum
 157 .RE
 158 .PP
 159 .SH SEE ALSO
 160 .BR @IMAGEX_PROGNAME@ (1)
 161 .BR @IMAGEX_PROGNAME@-info (1)
 162 .BR @IMAGEX_PROGNAME@-optimize (1)