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

   1 .TH WIMLIB-IMAGEX 1 "December 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 Easily remove wasted space in a WIM file and optionally recompress it (\fB
 101 @IMAGEX_PROGNAME@ optimize\fR)
 102 .IP \[bu]
 103 Support for all WIM compression types, both compression and decompression (LZX,
 104 XPRESS, and none)
 105 .IP \[bu]
 106 WIM integrity table is supported (\fB--check\fR option to many commands)
 107 .SH DIFFERENCES FROM MICROSOFT IMAGEX
 108 Although \fB@IMAGEX_PROGNAME@\fR shares some similarities with Microsoft's
 109 implementation of ImageX, this section lists some of the many noteworthy
 110 differences between the two programs:
 111 .IP \[bu] 4
 112 \fB@IMAGEX_PROGNAME@\fR is supported on both UNIX-like systems and Windows;
 113 thus, some functionality was designed around this.
 114 .IP \[bu]
 115 The command-line syntax of the two programs is similar but not exactly the same.
 116 .IP \[bu]
 117 Because Microsoft designed the WIM file format to accomodate Windows-specific
 118 and NTFS-specific features, on UNIX-like systems wimlib must have two separate
 119 image capture and application modes (although the \fB@IMAGEX_PROGNAME@\fR
 120 commands for the modes are the same): one for image capture and application
 121 from/to a directory, and one for the capture or application of an image
 122 specifically from/to an NTFS volume.
 123 .IP ""
 124 Note: the above applies to builds of \fB@IMAGEX_PROGNAME@\fR for UNIX-like
 125 systems.  On the Windows build, there is only one image capture and application
 126 mode, similar to Microsoft's ImageX.
 127 .IP \[bu]
 128 wimlib supports multithreaded compression, which can make it much faster to
 129 create compressed WIM files.
 130 .IP \[bu]
 131 \fB@IMAGEX_PROGNAME@\fR offers the extra commands \fB@IMAGEX_PROGNAME@
 132 extract\fR and \fB@IMAGEX_PROGNAME@ update\fR, which let you quickly extract
 133 files from or make changes to a WIM image without mounting it.
 134 .IP \[bu]
 135 \fB@IMAGEX_PROGNAME@\fR offers the extra command \fB@IMAGEX_PROGNAME@
 136 optimize\fR, which lets you easily remove wasted space in a WIM (which can arise
 137 after a WIM image is appended or mounted read-write).  It also makes it easy to
 138 recompress a WIM file at the highest compression level.
 139 .IP \[bu]
 140 \fB@IMAGEX_PROGNAME@\fR also offers the command \fB@IMAGEX_PROGNAME@ join\fR,
 141 which lets you easily join the parts of a split WIM.
 142 .IP \[bu]
 143 For convenience, \fB@IMAGEX_PROGNAME@\fR automatically preserves the integrity
 144 table in WIMs that have one, even when \fB--check\fR is not specified.
 145 .IP \[bu]
 146 wimlib supports a special "pipable" WIM format (not compatible with Microsoft's
 147 software).  This allows capturing and applying images directly to standard
 148 output or from standard input, respectively; this can be used to pipe images to
 149 or from a server over the network to implement fast filesystem imaging and
 150 restore.
 151 .IP \[bu]
 152 \fB@IMAGEX_PROGNAME@ capture\fR and \fB@IMAGEX_PROGNAME@ append\fR support
 153 options to optimize incremental backups and to create "delta" WIM files.
 154 .IP \[bu]
 155 wimlib (and \fB@IMAGEX_PROGNAME@\fR via \fB@IMAGEX_PROGNAME@ capture\fR)
 156 supports combining multiple separate directories and files together in a
 157 configurable way to create a WIM image.
 158 .IP \[bu]
 159 Microsoft's ImageX has some weird limitations, like it won't let you extract a
 160 WIM on a shared folder, and it requires some commands to be run only from
 161 Windows PE and not from regular Windows.  \fB@IMAGEX_PROGNAME@\fR does not have
 162 these unusual limitations.
 163 .IP \[bu]
 164 There are bugs in Microsoft's WIM library and I obviously have not included the
 165 same bugs in wimlib, although in some cases I have had to work around bugs for
 166 compatibility purposes.
 167 .IP \[bu]
 168 wimlib (and \fB@IMAGEX_PROGNAME@\fR via \fB@IMAGEX_PROGNAME@ mount\fR) support
 169 mounting an image from a split WIM, but Microsoft's software does not.  (Note:
 170 this functionality is not available in Windows builds of wimlib and
 171 \fB@IMAGEX_PROGNAME@\fR.)
 172 .SH LOCALES AND CHARACTER ENCODINGS
 173 On Windows, wimlib works in UTF-16LE, and there should be no problems with
 174 character encodings.
 175 .PP
 176 On UNIX, wimlib works primarily in the locale-dependent multibyte encoding,
 177 which you are strongly recommended to set to UTF-8 to avoid any problems.
 178 .SH CASE SENSITIVITY
 179 The case sensitivity of \fB@IMAGEX_PROGNAME@\fR differs somewhat between
 180 UNIX-like systems and Windows.  Filenames are internally treated as
 181 case-sensitive, but on Windows paths actually provided by the user will be
 182 treated as case-insensitive in order to get the "expected" behavior.  Otherwise,
 183 options and non-path arguments should be specified in lower case.
 184 .SH LICENSE
 185 wimlib and \fB@IMAGEX_PROGNAME@\fR are distributed under the GNU General Public
 186 License version 3 or later.  Be aware this means this software is provided as-is
 187 and has no warranty; see COPYING for details.
 188 .SH REPORTING BUGS
 189 Report bugs to ebiggers3@gmail.com.
 190 .SH SEE ALSO
 191 .BR @IMAGEX_PROGNAME@-append (1),
 192 .BR @IMAGEX_PROGNAME@-apply (1),
 193 .BR @IMAGEX_PROGNAME@-capture (1),
 194 .BR @IMAGEX_PROGNAME@-delete (1),
 195 .BR @IMAGEX_PROGNAME@-dir (1),
 196 .BR @IMAGEX_PROGNAME@-export (1),
 197 .BR @IMAGEX_PROGNAME@-extract (1),
 198 .BR @IMAGEX_PROGNAME@-info (1),
 199 .BR @IMAGEX_PROGNAME@-join (1),
 200 .BR @IMAGEX_PROGNAME@-mount (1),
 201 .BR @IMAGEX_PROGNAME@-mountrw (1),
 202 .BR @IMAGEX_PROGNAME@-optimize (1),
 203 .BR @IMAGEX_PROGNAME@-split (1),
 204 .BR @IMAGEX_PROGNAME@-unmount (1),
 205 .BR @IMAGEX_PROGNAME@-update (1),