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

   1 .TH WIMLIB-IMAGEX 1 "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
   2 .SH NAME
   3 @IMAGEX_PROGNAME@ \- Create, modify, extract, mount, or unmount a WIM (Windows Imaging Format) archive
   4 .SH SYNOPSIS
   5 \fB@IMAGEX_PROGNAME@ append\fR \fIarguments...\fR
   6 .br
   7 \fB@IMAGEX_PROGNAME@ apply\fR \fIarguments...\fR
   8 .br
   9 \fB@IMAGEX_PROGNAME@ capture\fR \fIarguments...\fR
  10 .br
  11 \fB@IMAGEX_PROGNAME@ delete\fR \fIarguments...\fR
  12 .br
  13 \fB@IMAGEX_PROGNAME@ dir\fR \fIarguments...\fR
  14 .br
  15 \fB@IMAGEX_PROGNAME@ export\fR \fIarguments...\fR
  16 .br
  17 \fB@IMAGEX_PROGNAME@ extract\fR \fIarguments...\fR
  18 .br
  19 \fB@IMAGEX_PROGNAME@ info\fR \fIarguments...\fR
  20 .br
  21 \fB@IMAGEX_PROGNAME@ join\fR \fIarguments...\fR
  22 .br
  23 \fB@IMAGEX_PROGNAME@ mount\fR \fIarguments...\fR
  24 .br
  25 \fB@IMAGEX_PROGNAME@ mountrw\fR \fIarguments...\fR
  26 .br
  27 \fB@IMAGEX_PROGNAME@ optimize\fR \fIarguments...\fR
  28 .br
  29 \fB@IMAGEX_PROGNAME@ split\fR \fIarguments...\fR
  30 .br
  31 \fB@IMAGEX_PROGNAME@ unmount\fR \fIarguments...\fR
  32 .br
  33 \fB@IMAGEX_PROGNAME@ update\fR \fIarguments...\fR
  34 .SH DESCRIPTION
  35 \fB@IMAGEX_PROGNAME@\fR deals with archives in the Windows Imaging Format (.wim
  36 files). Its interface is meant to be similar to Microsoft's "imagex.exe"
  37 program, but it also provide many useful extensions.
  38 .PP
  39 To do its work, \fB@IMAGEX_PROGNAME@\fR uses \fBwimlib\fR, a C library which
  40 provides interfaces for manipulating WIM archives.  You can wimlib in your own
  41 programs if desired, although \fB@IMAGEX_PROGNAME@\fR already provides access to
  42 most of wimlib's functionality.  In some cases, however, there are general
  43 interfaces which are only used by \fB@IMAGEX_PROGNAME@\fR in a specific way, so
  44 it may be worth taking a look if you're looking to do something beyond what
  45 \fB@IMAGEX_PROGNAME@\fR directly supports.
  46 .SH COMMANDS
  47 \fB@IMAGEX_PROGNAME@\fR accepts one of a number of commands (listed above in
  48 \fBSYNOPSYS\fR), and additional arguments depending on the specific command.
  49 Although \fB@IMAGEX_PROGNAME@\fR will print usage information with \fB--help\fR
  50 or if you invoke it incorrectly, the full documentation for each
  51 \fB@IMAGEX_PROGNAME@\fR command can be found in the appropriate manual page.
  52 .PP
  53 Note: to save typing, if appropriate hard links or batch files have been
  54 installed, a command \fB@IMAGEX_PROGNAME@ \fICOMMAND\fR can also be accessed as
  55 simply \fBwim\fICOMMAND\fR; for example, \fBwimapply\fR for \fB@IMAGEX_PROGNAME@
  56 apply\fR.
  57 .SH SUPPORTED FEATURES
  58 The following are some of the main features currently supported by
  59 \fB@IMAGEX_PROGNAME@\fR, and pointers to the relevant commands:
  60 .IP \[bu] 4
  61 Create a standalone WIM from a directory or NTFS volume (\fB@IMAGEX_PROGNAME@ capture\fR)
  62 .IP \[bu]
  63 Capture a WIM image directly to standard output in a special pipable format
  64 (\fB@IMAGEX_PROGNAME@ capture\fR)
  65 .IP \[bu]
  66 Append a directory or NTFS volume onto a standalone WIM as a new image (\fB@IMAGEX_PROGNAME@
  67 append\fR)
  68 .IP \[bu]
  69 Apply an image from a standalone or split WIM to a directory or NTFS volume
  70 (\fB@IMAGEX_PROGNAME@ apply\fR)
  71 .IP \[bu]
  72 Apply an image from a special pipable WIM format sent over standard input
  73 (\fB@IMAGEX_PROGNAME@ apply\fR)
  74 .IP \[bu]
  75 Mount an image from a standalone or split WIM read-only (\fB@IMAGEX_PROGNAME@
  76 mount\fR) (not available on Windows)
  77 .IP \[bu]
  78 Mount an image from a standalone WIM read-write (\fB@IMAGEX_PROGNAME@
  79 mountrw\fR) (not available on Windows)
  80 .IP \[bu]
  81 Extract individual files or directories from a WIM without mounting it
  82 (\fB@IMAGEX_PROGNAME@ extract\fR)
  83 .IP \[bu]
  84 Make changes to a WIM image without mounting it (\fB@IMAGEX_PROGNAME@ update\fR)
  85 .IP \[bu]
  86 Delete image(s) from a standalone WIM (\fB@IMAGEX_PROGNAME@ delete\fR)
  87 .IP \[bu]
  88 Export image(s) from a standalone or split WIM (\fB@IMAGEX_PROGNAME@ export\fR)
  89 .IP \[bu]
  90 Display information about a WIM file (\fB@IMAGEX_PROGNAME@ info\fR, \fB@IMAGEX_PROGNAME@ dir\fR)
  91 .IP \[bu]
  92 Change the name or description of an image in the WIM (\fB@IMAGEX_PROGNAME@ info\fR)
  93 .IP \[bu]
  94 Change which image in a WIM is bootable (\fB@IMAGEX_PROGNAME@ info\fR)
  95 .IP \[bu]
  96 Combine split WIMs into one standalone WIM (\fB@IMAGEX_PROGNAME@ join\fR)
  97 .IP \[bu]
  98 Split a standalone WIM into multiple parts (\fB@IMAGEX_PROGNAME@ split\fR)
  99 .IP \[bu]
 100 Support for all WIM compression types, both compression and decompression (LZX,
 101 XPRESS, and none)
 102 .IP \[bu]
 103 WIM integrity table is supported (\fB--check\fR option to many commands)
 104 .SH DIFFERENCES FROM MICROSOFT IMAGEX
 105 Although \fB@IMAGEX_PROGNAME@\fR shares some similarities with Microsoft's
 106 implementation of ImageX, this section lists some noteworthy differences between
 107 the two programs:
 108 .IP \[bu] 4
 109 \fB@IMAGEX_PROGNAME@\fR is supported on both UNIX-like systems and Windows;
 110 thus, some functionality was designed around this.
 111 .IP \[bu]
 112 The command-line syntax of the two programs is similar but not exactly the same.
 113 .IP \[bu]
 114 Because Microsoft designed the WIM file format to accomodate Windows-specific
 115 and NTFS-specific features, on UNIX-like systems wimlib must have two separate
 116 image capture and application modes (although the \fB@IMAGEX_PROGNAME@\fR
 117 commands for the modes are the same): one for image capture and application
 118 from/to a directory, and one for the capture or application of an image
 119 specifically from/to an NTFS volume.
 120 .IP ""
 121 Note: the above applies to builds of \fB@IMAGEX_PROGNAME@\fR for UNIX-like
 122 systems.  On the Windows build, there is only one image capture and application
 123 mode, similar to Microsoft's ImageX.
 124 .IP \[bu]
 125 wimlib supports multithreaded compression, which can make it much faster to
 126 create compressed WIM files.
 127 .IP \[bu]
 128 wimlib's XPRESS compressor is slightly better than Microsoft's (in terms of
 129 compression ratio).
 130 .IP \[bu]
 131 wimlib's LZX compressor is slightly worse than Microsoft's (in terms of
 132 compression ratio), but it's still better than XPRESS compression.
 133 .IP \[bu]
 134 \fB@IMAGEX_PROGNAME@ capture\fR defaults to LZX ("maximum") compression for new
 135 WIMs, as opposed to Microsoft's software which defaults to XPRESS ("fast")
 136 compression.
 137 .IP \[bu]
 138 \fB@IMAGEX_PROGNAME@\fR offers the extra commands \fB@IMAGEX_PROGNAME@
 139 extract\fR and \fB@IMAGEX_PROGNAME@ update\fR, which let you quickly extract
 140 files from or make changes to a WIM image without mounting it.
 141 .IP \[bu]
 142 \fB@IMAGEX_PROGNAME@\fR offers the extra command \fB@IMAGEX_PROGNAME@
 143 optimize\fR, which lets you easily remove wasted space in a WIM (which can arise
 144 after a WIM image is appended or mounted read-write).
 145 .IP \[bu]
 146 \fB@IMAGEX_PROGNAME@\fR also offers the command \fB@IMAGEX_PROGNAME@ join\fR,
 147 which lets you easily join the parts of a split WIM.
 148 .IP \[bu]
 149 For convenience, \fB@IMAGEX_PROGNAME@\fR automatically preserves the integrity
 150 table in WIMs that have one, even when \fB--check\fR is not specified.
 151 .IP \[bu]
 152 wimlib supports a special "pipable" WIM format (not compatible with Microsoft's
 153 software).  This allows capturing and applying images directly to standard
 154 output or from standard input, respectively; this can be used to pipe images to
 155 or from a server over the network to implement fast filesystem imaging and
 156 restore.
 157 .IP \[bu]
 158 \fB@IMAGEX_PROGNAME@ capture\fR and \fB@IMAGEX_PROGNAME@ append\fR support
 159 options to optimize incremental backups and to create "delta" WIM files.
 160 .IP \[bu]
 161 wimlib (and \fB@IMAGEX_PROGNAME@\fR via \fB@IMAGEX_PROGNAME@ capture\fR)
 162 supports combining multiple separate directories and files together in a
 163 configurable way to create a WIM image.
 164 .IP \[bu]
 165 Microsoft's ImageX has some weird limitations, like it won't let you extract a
 166 WIM on a shared folder, and it requires some commands to be run only from
 167 Windows PE and not from regular Windows.  \fB@IMAGEX_PROGNAME@\fR does not have
 168 these unusual limitations.
 169 .IP \[bu]
 170 There are bugs in Microsoft's WIM library and I obviously have not included the
 171 same bugs in wimlib, although in some cases I have had to work around bugs for
 172 compatibility purposes.
 173 .IP \[bu]
 174 wimlib (and \fB@IMAGEX_PROGNAME@\fR via \fB@IMAGEX_PROGNAME@ mount\fR) support
 175 mounting an image from a split WIM, but Microsoft's software does not.  (Note:
 176 this functionality is not available in Windows builds of wimlib and
 177 \fB@IMAGEX_PROGNAME@\fR.)
 178 .IP \[bu]
 179 \fB@IMAGEX_PROGNAME@ capture\fR supports a special mode where UNIX file modes,
 180 owners, and groups are stored.  (Note: this functionality is only available in
 181 builds of wimlib for UNIX-like systems.)
 182 .SH LOCALES AND CHARACTER ENCODINGS
 183 On Windows, wimlib works in UTF-16LE, and there should be no problems with
 184 character encodings.
 185 .PP
 186 On UNIX, wimlib works primarily in the locale-dependent multibyte encoding,
 187 which you are strongly recommended to set to UTF-8 to avoid any problems.
 188 .SH CASE SENSITIVITY
 189 The case sensitivity of \fB@IMAGEX_PROGNAME@\fR differs somewhat between
 190 UNIX-like systems and Windows.  Filenames are internally treated as
 191 case-sensitive, but on Windows paths actually provided by the user will be
 192 treated as case-insensitive in order to get the "expected" behavior.  Otherwise,
 193 options and non-path arguments should be specified in lower case.
 194 .SH LICENSE
 195 wimlib and \fB@IMAGEX_PROGNAME@\fR are distributed under the GNU General Public
 196 License version 3 or later.  Be aware this means this software is provided as-is
 197 and has no warranty; see COPYING for details.
 198 .SH REPORTING BUGS
 199 Report bugs to ebiggers3@gmail.com.
 200 .SH SEE ALSO
 201 .BR @IMAGEX_PROGNAME@-append (1),
 202 .BR @IMAGEX_PROGNAME@-apply (1),
 203 .BR @IMAGEX_PROGNAME@-capture (1),
 204 .BR @IMAGEX_PROGNAME@-delete (1),
 205 .BR @IMAGEX_PROGNAME@-dir (1),
 206 .BR @IMAGEX_PROGNAME@-export (1),
 207 .BR @IMAGEX_PROGNAME@-extract (1),
 208 .BR @IMAGEX_PROGNAME@-info (1),
 209 .BR @IMAGEX_PROGNAME@-join (1),
 210 .BR @IMAGEX_PROGNAME@-mount (1),
 211 .BR @IMAGEX_PROGNAME@-mountrw (1),
 212 .BR @IMAGEX_PROGNAME@-optimize (1),
 213 .BR @IMAGEX_PROGNAME@-split (1),
 214 .BR @IMAGEX_PROGNAME@-unmount (1),
 215 .BR @IMAGEX_PROGNAME@-update (1),