.TH WIMLIB-IMAGEX 1 "March 2014" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
.SH NAME
@IMAGEX_PROGNAME@ \- Create, modify, extract, mount, or unmount a WIM (Windows Imaging Format) archive
.SH SYNOPSIS
\fB@IMAGEX_PROGNAME@ append\fR \fIarguments...\fR
.br
\fB@IMAGEX_PROGNAME@ apply\fR \fIarguments...\fR
.br
\fB@IMAGEX_PROGNAME@ capture\fR \fIarguments...\fR
.br
\fB@IMAGEX_PROGNAME@ delete\fR \fIarguments...\fR
.br
\fB@IMAGEX_PROGNAME@ dir\fR \fIarguments...\fR
.br
\fB@IMAGEX_PROGNAME@ export\fR \fIarguments...\fR
.br
\fB@IMAGEX_PROGNAME@ extract\fR \fIarguments...\fR
.br
\fB@IMAGEX_PROGNAME@ info\fR \fIarguments...\fR
.br
\fB@IMAGEX_PROGNAME@ join\fR \fIarguments...\fR
.br
\fB@IMAGEX_PROGNAME@ mount\fR \fIarguments...\fR
.br
\fB@IMAGEX_PROGNAME@ mountrw\fR \fIarguments...\fR
.br
\fB@IMAGEX_PROGNAME@ optimize\fR \fIarguments...\fR
.br
\fB@IMAGEX_PROGNAME@ split\fR \fIarguments...\fR
.br
\fB@IMAGEX_PROGNAME@ unmount\fR \fIarguments...\fR
.br
\fB@IMAGEX_PROGNAME@ update\fR \fIarguments...\fR
.SH DESCRIPTION
\fB@IMAGEX_PROGNAME@\fR deals with archives in the Windows Imaging Format (.wim
files). Its interface is meant to be similar to Microsoft's "imagex.exe"
program, but it also provide many useful extensions.
.PP
To do its work, \fB@IMAGEX_PROGNAME@\fR uses \fBwimlib\fR, a C library which
provides interfaces for manipulating WIM archives.  You can wimlib in your own
programs if desired, although \fB@IMAGEX_PROGNAME@\fR already provides access to
most of wimlib's functionality.  In some cases, however, there are general
interfaces which are only used by \fB@IMAGEX_PROGNAME@\fR in a specific way, so
it may be worth taking a look if you're looking to do something beyond what
\fB@IMAGEX_PROGNAME@\fR directly supports.
.SH COMMANDS
\fB@IMAGEX_PROGNAME@\fR accepts one of a number of commands (listed above in
\fBSYNOPSYS\fR), and additional arguments depending on the specific command.
Although \fB@IMAGEX_PROGNAME@\fR will print usage information with \fB--help\fR
or if you invoke it incorrectly, the full documentation for each
\fB@IMAGEX_PROGNAME@\fR command can be found in the appropriate manual page.
.PP
Note: to save typing, if appropriate hard links or batch files have been
installed, a command \fB@IMAGEX_PROGNAME@ \fICOMMAND\fR can also be accessed as
simply \fBwim\fICOMMAND\fR; for example, \fBwimapply\fR for \fB@IMAGEX_PROGNAME@
apply\fR.
.SH SUPPORTED FEATURES
The following are some of the main features currently supported by
\fB@IMAGEX_PROGNAME@\fR, and pointers to the relevant commands:
.IP \[bu] 4
Create a standalone WIM from a directory or NTFS volume (\fB@IMAGEX_PROGNAME@ capture\fR)
.IP \[bu]
Capture a WIM image directly to standard output in a special pipable format
(\fB@IMAGEX_PROGNAME@ capture\fR)
.IP \[bu]
Append a directory or NTFS volume onto a standalone WIM as a new image (\fB@IMAGEX_PROGNAME@
append\fR)
.IP \[bu]
Apply an image from a standalone or split WIM to a directory or NTFS volume
(\fB@IMAGEX_PROGNAME@ apply\fR)
.IP \[bu]
Apply an image from a special pipable WIM format sent over standard input
(\fB@IMAGEX_PROGNAME@ apply\fR)
.IP \[bu]
Mount an image from a standalone or split WIM read-only (\fB@IMAGEX_PROGNAME@
mount\fR) (not available on Windows)
.IP \[bu]
Mount an image from a standalone WIM read-write (\fB@IMAGEX_PROGNAME@
mountrw\fR) (not available on Windows)
.IP \[bu]
Extract individual files or directories from a WIM without mounting it
(\fB@IMAGEX_PROGNAME@ extract\fR)
.IP \[bu]
Make changes to a WIM image without mounting it (\fB@IMAGEX_PROGNAME@ update\fR)
.IP \[bu]
Delete image(s) from a standalone WIM (\fB@IMAGEX_PROGNAME@ delete\fR)
.IP \[bu]
Export image(s) from a standalone or split WIM (\fB@IMAGEX_PROGNAME@ export\fR)
.IP \[bu]
Display information about a WIM file (\fB@IMAGEX_PROGNAME@ info\fR, \fB@IMAGEX_PROGNAME@ dir\fR)
.IP \[bu]
Change the name or description of an image in the WIM (\fB@IMAGEX_PROGNAME@ info\fR)
.IP \[bu]
Change which image in a WIM is bootable (\fB@IMAGEX_PROGNAME@ info\fR)
.IP \[bu]
Combine split WIMs into one standalone WIM (\fB@IMAGEX_PROGNAME@ join\fR)
.IP \[bu]
Split a standalone WIM into multiple parts (\fB@IMAGEX_PROGNAME@ split\fR)
.IP \[bu]
Easily remove wasted space in a WIM file and optionally recompress it (\fB
@IMAGEX_PROGNAME@ optimize\fR)
.IP \[bu]
Support for all WIM compression types, both compression and decompression
(XPRESS, LZX, LZMS, and None).
.IP \[bu]
WIM integrity table is supported (\fB--check\fR option to many commands)
.SH DIFFERENCES FROM MICROSOFT IMAGEX
Although \fB@IMAGEX_PROGNAME@\fR shares some similarities with Microsoft's
implementation of ImageX, this section lists some of the many noteworthy
differences between the two programs:
.IP \[bu] 4
\fB@IMAGEX_PROGNAME@\fR is supported on both UNIX-like systems and Windows;
thus, some functionality was designed around this.
.IP \[bu]
The command-line syntax of the two programs is similar but not exactly the same.
.IP \[bu]
Because Microsoft designed the WIM file format to accomodate Windows-specific
and NTFS-specific features, on UNIX-like systems wimlib must have two separate
image capture and application modes (although the \fB@IMAGEX_PROGNAME@\fR
commands for the modes are the same): one for image capture and application
from/to a directory, and one for the capture or application of an image
specifically from/to an NTFS volume.
.IP ""
Note: the above applies to builds of \fB@IMAGEX_PROGNAME@\fR for UNIX-like
systems.  On the Windows build, there is only one image capture and application
mode, similar to Microsoft's ImageX.
.IP \[bu]
wimlib supports multithreaded compression, which can make it much faster to
create compressed WIM files.
.IP \[bu]
\fB@IMAGEX_PROGNAME@\fR offers the extra commands \fB@IMAGEX_PROGNAME@
extract\fR and \fB@IMAGEX_PROGNAME@ update\fR, which let you quickly extract
files from or make changes to a WIM image without mounting it.
.IP \[bu]
\fB@IMAGEX_PROGNAME@\fR offers the extra command \fB@IMAGEX_PROGNAME@
optimize\fR, which lets you easily remove wasted space in a WIM (which can arise
after a WIM image is appended or mounted read-write).  It also makes it easy to
recompress a WIM file at the highest compression level.
.IP \[bu]
\fB@IMAGEX_PROGNAME@\fR also offers the command \fB@IMAGEX_PROGNAME@ join\fR,
which lets you easily join the parts of a split WIM.
.IP \[bu]
For convenience, \fB@IMAGEX_PROGNAME@\fR automatically preserves the integrity
table in WIMs that have one, even when \fB--check\fR is not specified.
.IP \[bu]
wimlib supports a special "pipable" WIM format (not compatible with Microsoft's
software).  This allows capturing and applying images directly to standard
output or from standard input, respectively; this can be used to pipe images to
or from a server over the network to implement fast filesystem imaging and
restore.
.IP \[bu]
\fB@IMAGEX_PROGNAME@ capture\fR and \fB@IMAGEX_PROGNAME@ append\fR support
options to optimize incremental backups and to create "delta" WIM files.
.IP \[bu]
wimlib (and \fB@IMAGEX_PROGNAME@\fR via \fB@IMAGEX_PROGNAME@ capture\fR)
supports combining multiple separate directories and files together in a
configurable way to create a WIM image.
.IP \[bu]
Microsoft's ImageX has some weird limitations, like it won't let you extract a
WIM on a shared folder, and it requires some commands to be run only from
Windows PE and not from regular Windows.  \fB@IMAGEX_PROGNAME@\fR does not have
these unusual limitations.
.IP \[bu]
There are bugs in Microsoft's WIM library and I obviously have not included the
same bugs in wimlib, although in some cases I have had to work around bugs for
compatibility purposes.
.IP \[bu]
wimlib (and \fB@IMAGEX_PROGNAME@\fR via \fB@IMAGEX_PROGNAME@ mount\fR) support
mounting an image from a split WIM, but Microsoft's software does not.  (Note:
this functionality is not available in Windows builds of wimlib and
\fB@IMAGEX_PROGNAME@\fR.)
.SH LOCALES AND CHARACTER ENCODINGS
WIM files themselves store file and stream names using UTF-16LE.  On Windows,
wimlib works in UTF-16LE, so conversions are usually not necessary and there
should be no problems with character encodings.
.PP
On UNIX-like systems, wimlib works primarily in the locale-dependent multibyte
encoding, which you are strongly recommended to set to UTF-8 to avoid any
problems.  You can alternatively set the environmental variable
\fBWIMLIB_IMAGEX_USE_UTF8\fR to force \fB@IMAGEX_PROGNAME@\fR to use UTF-8
character encoding internally, even if the current locale is not UTF-8
compatible.
.SH CASE SENSITIVITY
By default, the case sensitivity of \fB@IMAGEX_PROGNAME@\fR differs somewhat
between UNIX-like systems and Windows.  WIM images may (but usually do not) have
multiple files with the same case-insensitive name.  Internally, wimlib
stores filenames as case-sensitive, but on Windows paths
actually provided by the user for use in a WIM image (e.g. for extracting,
adding, renaming, or deleting files) will by default be treated as
case-insensitive in order to get the "expected" behavior. This differs from the
default behavior on UNIX-like systems, where such paths will be treated as
case-sensitive.  Note that with case insensitivity, a path component may in
general be ambiguous due to multiple files or directories having the same
case-insensitive name.  In such cases, if there is a file or directory with an
exactly matching name, it is chosen; otherwise, one of the case-insensitively
matching file or directories is chosen arbitrarily.
.PP
The default behavior can be overridden by explicitly setting the environmental
variable \fBWIMLIB_IMAGEX_IGNORE_CASE\fR to 1, in which case such paths will be
treated case insensitively, or 0, in which such paths will be treated case
sensitively.
.PP
Regardless of these settings, options and non-path arguments must be specified
in lower case.
.SH LICENSE
wimlib and \fB@IMAGEX_PROGNAME@\fR are distributed under the GNU General Public
License version 3 or later.  Be aware this means this software is provided as-is
and has no warranty; see COPYING for details.
.SH REPORTING BUGS
Report bugs to ebiggers3@gmail.com.
.SH SEE ALSO
.BR @IMAGEX_PROGNAME@-append (1),
.BR @IMAGEX_PROGNAME@-apply (1),
.BR @IMAGEX_PROGNAME@-capture (1),
.BR @IMAGEX_PROGNAME@-delete (1),
.BR @IMAGEX_PROGNAME@-dir (1),
.BR @IMAGEX_PROGNAME@-export (1),
.BR @IMAGEX_PROGNAME@-extract (1),
.BR @IMAGEX_PROGNAME@-info (1),
.BR @IMAGEX_PROGNAME@-join (1),
.BR @IMAGEX_PROGNAME@-mount (1),
.BR @IMAGEX_PROGNAME@-mountrw (1),
.BR @IMAGEX_PROGNAME@-optimize (1),
.BR @IMAGEX_PROGNAME@-split (1),
.BR @IMAGEX_PROGNAME@-unmount (1),
.BR @IMAGEX_PROGNAME@-update (1),