[wimlib] / doc / imagex.1.in

.TH WIMLIB-IMAGEX 1 "August 2013" "@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 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 stand-alone 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 stand-alone WIM as a new image (\fB@IMAGEX_PROGNAME@
append\fR)
.IP \[bu]
Apply an image from a stand-alone 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 stand-alone or split WIM read-only (\fB@IMAGEX_PROGNAME@
mount\fR) (not available on Windows)
.IP \[bu]
Mount an image from a stand-alone 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 stand-alone WIM (\fB@IMAGEX_PROGNAME@ delete\fR)
.IP \[bu]
Export image(s) from a stand-alone 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 stand-alone WIM (\fB@IMAGEX_PROGNAME@ join\fR)
.IP \[bu]
Split a stand-alone WIM into multiple parts (\fB@IMAGEX_PROGNAME@ split\fR)
.IP \[bu]
Support for all WIM compression types, both compression and decompression (LZX,
XPRESS, 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 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]
wimlib's XPRESS compressor is slightly better than Microsoft's (in terms of
compression ratio).
.IP \[bu]
wimlib's LZX compressor is slightly worse than Microsoft's (in terms of
compression ratio), but it's still better than XPRESS compression.
.IP \[bu]
\fB@IMAGEX_PROGNAME@ capture\fR defaults to LZX ("maximum") compression for new
WIMs, as opposed to Microsoft's software which defaults to XPRESS ("fast")
compression.
.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).
.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]
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.)
.IP \[bu]
\fB@IMAGEX_PROGNAME@ capture\fR supports a special mode where UNIX file modes,
owners, and groups are stored.  (Note: this functionality is only available in
builds of wimlib for UNIX-like systems.)
.SH LOCALES AND CHARACTER ENCODINGS
On Windows, wimlib works in UTF-16LE, and there should be no problems with
character encodings.
.PP
On UNIX, wimlib works primarily in the locale-dependent multibyte encoding,
which you are strongly recommended to set to UTF-8 to avoid any problems.
.SH CASE SENSITIVITY
The case sensitivity of \fB@IMAGEX_PROGNAME@\fR differs somewhat between
UNIX-like systems and Windows.  Filenames are internally treated as
case-sensitive, but on Windows paths actually provided by the user will be
treated as case-insensitive in order to get the "expected" behavior.  Otherwise,
options and non-path arguments should 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),