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

   1 .TH WIMLIB-IMAGEX "1" "June 2014" "@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 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 .IP ""
  78 \fITYPE\fR may also be "recovery" (or "LZMS"); however, this will result in
  79 reduced compatibility.  See the documentation for this option to
  80 \fB@IMAGEX_PROGNAME@ capture\fR (1) for more details.
  81 .TP
  82 \fB--recompress\fR
  83 Force all exported data to be recompressed, even if the destination WIM will use
  84 the same compression type as the source WIM.
  85 .TP
  86 \fB--compress-slow\fR
  87 Spend even more time compressing the data to achieve a very slightly better
  88 compression ratio.  This currently only has an effect for LZX ("maximum") and
  89 LZMS ("recovery") compression.  This option does not itself set the compression
  90 format.
  91 .TP
  92 \fB--chunk-size\fR=\fISIZE\fR
  93 Set the WIM compression chunk size to \fISIZE\fR.  See the documentation for
  94 this option to \fB@IMAGEX_PROGNAME@ capture\fR (1) for more details.
  95 .TP
  96 \fB--pack-streams\fR, \fB--solid\fR
  97 Create a "solid" archive that compresses multiple files together.  This can
  98 result in a higher compression ratio, but has disadvantages such as reduced
  99 compatibility.  See the documentation for this option to \fB@IMAGEX_PROGNAME@
 100 capture\fR (1) for more details.
 101 .TP
 102 \fB--pack-chunk-size\fR=\fISIZE\fR, \fB--solid-chunk-size\fR=\fISIZE\fR
 103 Like \fB--chunk-size\fR, but set the chunk size used in packed resources.  See
 104 the documentation for this option to \fB@IMAGEX_PROGNAME@ capture\fR (1) for
 105 more details.
 106 .TP
 107 \fB--pack-compress\fR=\fITYPE\fR, \fB--solid-compress\fR=\fITYPE\fR
 108 Like \fB--compress\fR, but set the compression format used in packed resources.
 109 See the documentation for this option to \fB@IMAGEX_PROGNAME@ capture\fR (1) for
 110 more details.
 111 .TP
 112 \fB--threads\fR=\fINUM_THREADS\fR
 113 Number of threads to use for compressing data.  Default: autodetect (number of
 114 processors).  Note: multiple compressor threads are not very useful when
 115 exporting to a WIM with the same compression type as the source WIM, since
 116 wimlib optimizes this case by re-using the raw compressed data.
 117 .TP
 118 \fB--rebuild\fR
 119 When exporting image(s) to an existing WIM: rebuild the entire WIM rather than
 120 appending data to the end of it.  Rebuilding the WIM is slower, but will save a
 121 little bit of space that would otherwise be left as a hole in the WIM.  Also see
 122 \fB@IMAGEX_PROGNAME@ optimize\fR.
 123 .TP
 124 \fB--ref\fR="\fIGLOB\fR"
 125 File glob of additional WIMs or split WIM parts to reference resources from.
 126 See \fBSPLIT_WIMS\fR.  This option can be specified multiple times.  Note:
 127 \fIGLOB\fR is listed in quotes because it is interpreted by
 128 \fB@IMAGEX_PROGNAME@\fR and may need to be quoted to protect against shell
 129 expansion.
 130 .TP
 131 \fB--pipable\fR
 132 Build, or rebuild, \fIDEST_WIMFILE\fR as a "pipable WIM" so that it can be
 133 applied fully sequentially, including from a pipe.  See \fB@IMAGEX_PROGNAME@
 134 capture\fR(1) for more details about creating pipable WIMs.  The default without
 135 this option is to make \fIDEST_WIMFILE\fR pipable if and only if it already
 136 existed and was already pipable, or was "-" (standard output).
 137 .TP
 138 \fB--not-pipable\fR
 139 Build, or rebuild, \fIDEST_WIMFILE\fR as a normal, non-pipable WIM.  This is the
 140 default behavior, unless \fIDEST_WIMFILE\fR already existed and was already
 141 pipable, or if \fIDEST_WIMFILE\fR was "-" (standard output).
 142 .TP
 143 \fB--wimboot\fR
 144 Mark the destination image as WIMBoot-compatible.  Also, if exporting to a new
 145 archive, set the compression type to that recommended for WIMBoot (currently,
 146 XPRESS with 4096 byte chunks).
 147 .SH SPLIT WIMS
 148 You may use \fB@IMAGEX_PROGNAME@ export\fR to export images from a split WIM.
 149 The \fISRC_WIMFILE\fR argument must specify the first part of the split WIM,
 150 while the additional parts of the split WIM must be specified in one or more
 151 \fB--ref\fR="\fIGLOB\fR" options.  Since globbing is built into the \fB--ref\fR
 152 option, typically only one \fB--ref\fR option is necessary.  For example, the
 153 names for the split WIM parts usually go something like:
 154 .PP
 155 .RS
 156 .nf
 157 mywim.swm
 158 mywim2.swm
 159 mywim3.swm
 160 mywim4.swm
 161 mywim5.swm
 162 .RE
 163 .PP
 164 To export the first image of this split WIM to a new or existing WIM file
 165 "other.wim", run:
 166 .PP
 167 .RS
 168 @IMAGEX_PROGNAME@ export mywim.swm 1 other.wim --ref="mywim*.swm"
 169 .RE
 170 .SH NOTES
 171 \fIData integrity\fR:  It is safe to abort a \fB@IMAGEX_PROGNAME@ export\fR command partway through.
 172 However, after doing this, it is recommended to run \fB@IMAGEX_PROGNAME@
 173 optimize\fR on the destination WIM to remove any data that was appended to the
 174 physical WIM file but not yet incorporated into the structure of the WIM, unless
 175 the WIM was being rebuilt (e.g. with \fB--rebuild\fR), in which case you should
 176 delete the temporary file left over.
 177 .PP
 178 \fISingle instancing\fR: The WIM format uses single-instance streams (roughly,
 179 "files").  When an image is exported, only the streams ("files") not already
 180 present in the destination WIM will be copied.  However, a new copy of the
 181 image's metadata resource, which describes the full directory structure, will
 182 always be created.
 183 .PP
 184 \fIESD files\fR: wimlib v1.6.0 and later can export images from version 3584
 185 WIMs, which usually contain LZMS-compressed solid blocks and may carry the
 186 \fI.esd\fR file extension rather than \fI.wim\fR.  However, \fI.esd\fR files
 187 downloaded directly by the Windows 8 web downloader have encrypted segments, and
 188 wimlib cannot export images from such files until they are first decrypted.  In
 189 addition, to ensure the destination archive is created in the original WIM
 190 format rather than in the newer format, specify \fB--compress\fR=\fImaximum\fR.
 191 .SH EXAMPLES
 192 Export the second image of 'boot.wim' to the new WIM file 'new.wim':
 193 .RS
 194 .PP
 195 @IMAGEX_PROGNAME@ export boot.wim 2 new.wim
 196 .RE
 197 .PP
 198 The above example creates "new.wim" with the same compression type as
 199 "boot.wim".  If you wish to change the compression type, specify
 200 \fB--compress\fR=\fITYPE\fR; for example:
 201 .RS
 202 .PP
 203 @IMAGEX_PROGNAME@ export boot.wim 2 new.wim --compress=maximum
 204 .RE
 205 .PP
 206 .SH SEE ALSO
 207 .BR @IMAGEX_PROGNAME@ (1)
 208 .BR @IMAGEX_PROGNAME@-info (1)
 209 .BR @IMAGEX_PROGNAME@-optimize (1)