wimlib.net Git - wimlib/blob - doc/man1/wimexport.1

   1 .TH WIMEXPORT "1" "July 2017" "wimlib 1.12.0" "User Commands"
   2 .SH NAME
   3 wimexport \- Export image(s) from a WIM archive
   4 .SH SYNOPSIS
   5 \fBwimexport\fR \fISRC_WIMFILE\fR \fISRC_IMAGE\fR \fIDEST_WIMFILE\fR
   6  [\fIDEST_IMAGE_NAME\fR [\fIDEST_IMAGE_DESC\fR]] [\fIOPTION\fR...]
   7 .SH DESCRIPTION
   8 \fBwimexport\fR, or equivalently \fBwimlib-imagex export\fR, exports the
   9 specified image from \fISRC_WIMFILE\fR into \fIDEST_WIMFILE\fR, optionally
  10 changing the image's name and/or description.  If \fIDEST_WIMFILE\fR already
  11 exists, the image will be appended to it; otherwise, a new WIM archive will be
  12 created to contain the exported image.
  13 .PP
  14 \fISRC_IMAGE\fR specifies the image in \fISRC_WIMFILE\fR to export.  It may be
  15 the 1-based index of an image, the name of an image, or the keyword "all" to
  16 specify all images.  You can use \fBwiminfo\fR(1) to list the images contained
  17 in \fISRC_WIMFILE\fR.
  18 .PP
  19 If specified, \fIDEST_IMAGE_NAME\fR is the name to give the image being
  20 exported.  The default is its name in \fISRC_WIMFILE\fR.  If specified,
  21 \fIDEST_IMAGE_NAME\fR must be either a name not already used in
  22 \fIDEST_WIMFILE\fR, or the empty string to leave the image unnamed.
  23 \fIDEST_IMAGE_NAME\fR cannot be specified if "all" images are being exported.
  24 .PP
  25 If specified, \fIDEST_IMAGE_DESC\fR is the description to give the image being
  26 exported.  The default is its description in \fISRC_WIMFILE\fR.
  27 .PP
  28 \fBwimexport\fR supports exporting images from stand-alone WIMs as well as from
  29 split WIMs and delta WIMs.  See \fBSPLIT WIMS\fR.
  30 .PP
  31 \fBwimexport\fR also supports exporting images from a non-pipable WIM into a
  32 pipable WIM or vice versa, or from a non-solid WIM into a solid WIM or vice
  33 versa.  It can also export a pipable WIM directly to standard output if
  34 \fIDEST_WIMFILE\fR is specified as "-"; see \fB--pipable\fR.
  35 .PP
  36 .SH OPTIONS
  37 .TP 6
  38 \fB--boot\fR
  39 Mark the exported image as the "bootable" image of the WIM; or, if multiple
  40 images are being exported, make the image that was the bootable image of the
  41 source WIM also the bootable image of the destination WIM.
  42 .TP
  43 \fB--check\fR
  44 Before exporting the image(s), verify the integrity of the source and
  45 destination WIMs if extra integrity information is present.  Also include extra
  46 integrity information in the destination WIM, even if it was not present before.
  47 .TP
  48 \fB--nocheck\fR
  49 Do not include extra integrity information in the destination WIM, even if it
  50 was present before.
  51 .TP
  52 \fB--compress\fR=\fITYPE\fR[:\fILEVEL\fR]
  53 Specify the compression type, and optionally the compression level for that
  54 compression type, for \fIDEST_WIMFILE\fR.  Note that if \fIDEST_WIMFILE\fR
  55 already exists, then its compression type cannot be changed by this option.  See
  56 the documentation for this option to \fBwimcapture\fR(1) for more details.
  57 .TP
  58 \fB--chunk-size\fR=\fISIZE\fR
  59 Set the WIM compression chunk size to \fISIZE\fR.  See the documentation for
  60 this option to \fBwimcapture\fR(1) for more details.
  61 .TP
  62 \fB--recompress\fR
  63 Force all exported data to be recompressed, even if the destination WIM will use
  64 the same compression type as the source WIM.
  65 .TP
  66 \fB--solid\fR
  67 Create a "solid" archive that compresses multiple files together.  This usually
  68 results in a significantly better compression ratio but has disadvantages such
  69 as reduced compatibility.  See the documentation for this option to
  70 \fBwimcapture\fR(1) for more details.
  71 .TP
  72 \fB--solid-compress\fR=\fITYPE\fR[:\fILEVEL\fR]
  73 Like \fB--compress\fR, but set the compression type used in solid resources.
  74 See the documentation for this option to \fBwimcapture\fR(1) for more details.
  75 .TP
  76 \fB--solid-chunk-size\fR=\fISIZE\fR
  77 Like \fB--chunk-size\fR, but set the chunk size used in solid resources.  See
  78 the documentation for this option to \fBwimcapture\fR(1) for more details.
  79 .TP
  80 \fB--threads\fR=\fINUM_THREADS\fR
  81 Number of threads to use for compressing data.  Default: autodetect (number of
  82 processors).
  83 .TP
  84 \fB--rebuild\fR
  85 If exporting to an existing WIM, rebuild it rather than appending to it.
  86 Rebuilding is slower but will save some space that would otherwise be left as a
  87 hole in the WIM.  Also see \fBwimoptimize\fR(1).
  88 .TP
  89 \fB--ref\fR="\fIGLOB\fR"
  90 File glob of additional WIMs or split WIM parts to reference resources from.
  91 See \fBSPLIT_WIMS\fR.  This option can be specified multiple times.  Note:
  92 \fIGLOB\fR is listed in quotes because it is interpreted by \fBwimexport\fR and
  93 may need to be quoted to protect against shell expansion.
  94 .TP
  95 \fB--pipable\fR
  96 Build or rebuild \fIDEST_WIMFILE\fR as a "pipable WIM" that can be applied fully
  97 sequentially, including from a pipe.  See \fBwimcapture\fR(1) for more details
  98 about creating pipable WIMs.  The default without this option is to make
  99 \fIDEST_WIMFILE\fR pipable only if it was "-" (standard output) or was an
 100 existing pipable WIM.
 101 .TP
 102 \fB--not-pipable\fR
 103 Rebuild \fIDEST_WIMFILE\fR as a normal, non-pipable WIM.  This only useful if
 104 you are exporting image(s) to a pipable WIM but you want it rebuilt as
 105 non-pipable.
 106 .TP
 107 \fB--wimboot\fR
 108 Mark the destination image as WIMBoot-compatible.  Also, if exporting to a new
 109 archive, set the compression type to that recommended for WIMBoot (currently,
 110 XPRESS with 4096 byte chunks).
 111 .TP
 112 \fB--unsafe-compact\fR
 113 Compact the existing destination WIM in-place and append any new data,
 114 eliminating "holes".  This is efficient, but in general this option should
 115 \fInot\fR be used because a failed or interrupted compaction will corrupt the
 116 WIM archive.  For more information, see the documentation for this option to
 117 \fBwimoptimize\fR(1).
 118 .SH SPLIT WIMS
 119 You may use \fBwimexport\fR to export images from (but not to) a split WIM.  The
 120 \fISRC_WIMFILE\fR argument must specify the first part of the split WIM, while
 121 the additional parts of the split WIM must be specified in one or more
 122 \fB--ref\fR="\fIGLOB\fR" options.  Since globbing is built into the \fB--ref\fR
 123 option, typically only one \fB--ref\fR option is necessary.  For example, the
 124 names for the split WIM parts usually go something like:
 125 .PP
 126 .RS
 127 .nf
 128 mywim.swm
 129 mywim2.swm
 130 mywim3.swm
 131 mywim4.swm
 132 mywim5.swm
 133 .RE
 134 .PP
 135 To export the first image of this split WIM to a new or existing WIM file
 136 "other.wim", run:
 137 .PP
 138 .RS
 139 wimexport mywim.swm 1 other.wim --ref="mywim*.swm"
 140 .RE
 141 .SH NOTES
 142 \fIData consistency\fR: Except when using \fB--unsafe-compact\fR, it is safe to
 143 abort a \fBwimexport\fR command partway through.  However, after doing this, it
 144 is recommended to run \fBwimoptimize\fR on the destination WIM to remove any
 145 data that was appended to the physical WIM file but not yet incorporated into
 146 the structure of the WIM, unless the WIM was being rebuilt (e.g. with
 147 \fB--rebuild\fR), in which case you should delete the temporary file left over.
 148 .PP
 149 \fIData deduplication\fR: The WIM format has built-in deduplication (also called
 150 "single instancing") of file contents.  Therefore, when an image is exported,
 151 only the file contents not already present in the destination WIM will be
 152 physically copied.  However, a new copy of the image's metadata resource, which
 153 describes the image's directory structure, will always be created.
 154 .PP
 155 \fIESD files\fR: \fBwimexport\fR supports solid-compressed WIMs, or "ESD" (.esd)
 156 files, except for encrypted ESDs, which must be decrypted first.  The source and
 157 destination files of \fBwimexport\fR can be solid WIMs, non-solid WIMs, or a
 158 combination thereof.  If the destination file does not exist, then by default it
 159 will be created as solid if the source was solid, or as non-solid if the source
 160 was non-solid.  To override this, either specify \fB--solid\fR to create a solid
 161 WIM (.esd file), or specify \fB--compress\fR=\fILZX\fR to create a standard
 162 non-solid WIM (.wim file).
 163 .SH EXAMPLES
 164 Export the second image of 'boot.wim' to the new WIM file 'new.wim':
 165 .RS
 166 .PP
 167 wimexport boot.wim 2 new.wim
 168 .RE
 169 .PP
 170 The above example creates "new.wim" with the same compression type as
 171 "boot.wim".  If you wish to change the compression type, specify
 172 \fB--compress\fR=\fITYPE\fR; for example:
 173 .RS
 174 .PP
 175 wimexport boot.wim 2 new.wim --compress=LZX
 176 .RE
 177 .PP
 178 Export "ESD to WIM" --- that is, solid WIM to non-solid WIM:
 179 .RS
 180 .PP
 181 wimexport install.esd all install.wim --compress=LZX
 182 .RE
 183 .PP
 184 Export "WIM to ESD" --- that is, non-solid WIM to solid WIM:
 185 .RS
 186 .PP
 187 wimexport install.wim all install.esd --solid
 188 .RE
 189 .PP
 190 .SH SEE ALSO
 191 .BR wimlib-imagex (1)
 192 .BR wiminfo (1)
 193 .BR wimoptimize (1)