c55d748f95e498fde4759761072c4d6291c6851c
[wimlib] / doc / man1 / imagex.1.in
1 .TH WIMLIB-IMAGEX 1 "March 2014" "@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
104 (XPRESS, LZX, LZMS, 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 WIM files themselves store file and stream names using UTF-16LE.  On Windows,
174 wimlib works in UTF-16LE, so conversions are usually not necessary and there
175 should be no problems with character encodings.
176 .PP
177 On UNIX-like systems, wimlib works primarily in the locale-dependent multibyte
178 encoding, which you are strongly recommended to set to UTF-8 to avoid any
179 problems.  You can alternatively set the environmental variable
180 \fBWIMLIB_IMAGEX_USE_UTF8\fR to force \fB@IMAGEX_PROGNAME@\fR to use UTF-8
181 character encoding internally, even if the current locale is not UTF-8
182 compatible.
183 .SH CASE SENSITIVITY
184 By default, the case sensitivity of \fB@IMAGEX_PROGNAME@\fR differs somewhat
185 between UNIX-like systems and Windows.  WIM images may (but usually do not) have
186 multiple files with the same case-insensitive name.  Internally, wimlib
187 stores filenames as case-sensitive, but on Windows paths
188 actually provided by the user for use in a WIM image (e.g. for extracting,
189 adding, renaming, or deleting files) will by default be treated as
190 case-insensitive in order to get the "expected" behavior. This differs from the
191 default behavior on UNIX-like systems, where such paths will be treated as
192 case-sensitive.  Note that with case insensitivity, a path component may in
193 general be ambiguous due to multiple files or directories having the same
194 case-insensitive name.  In such cases, if there is a file or directory with an
195 exactly matching name, it is chosen; otherwise, one of the case-insensitively
196 matching file or directories is chosen arbitrarily.
197 .PP
198 The default behavior can be overridden by explicitly setting the environmental
199 variable \fBWIMLIB_IMAGEX_IGNORE_CASE\fR to 1, in which case such paths will be
200 treated case insensitively, or 0, in which such paths will be treated case
201 sensitively.
202 .PP
203 Regardless of these settings, options and non-path arguments must be specified
204 in lower case.
205 .SH LICENSE
206 wimlib and \fB@IMAGEX_PROGNAME@\fR are distributed under the GNU General Public
207 License version 3 or later.  Be aware this means this software is provided as-is
208 and has no warranty; see COPYING for details.
209 .SH REPORTING BUGS
210 Report bugs to ebiggers3@gmail.com.
211 .SH SEE ALSO
212 .BR @IMAGEX_PROGNAME@-append (1),
213 .BR @IMAGEX_PROGNAME@-apply (1),
214 .BR @IMAGEX_PROGNAME@-capture (1),
215 .BR @IMAGEX_PROGNAME@-delete (1),
216 .BR @IMAGEX_PROGNAME@-dir (1),
217 .BR @IMAGEX_PROGNAME@-export (1),
218 .BR @IMAGEX_PROGNAME@-extract (1),
219 .BR @IMAGEX_PROGNAME@-info (1),
220 .BR @IMAGEX_PROGNAME@-join (1),
221 .BR @IMAGEX_PROGNAME@-mount (1),
222 .BR @IMAGEX_PROGNAME@-mountrw (1),
223 .BR @IMAGEX_PROGNAME@-optimize (1),
224 .BR @IMAGEX_PROGNAME@-split (1),
225 .BR @IMAGEX_PROGNAME@-unmount (1),
226 .BR @IMAGEX_PROGNAME@-update (1),