[wimlib] / doc / imagex.1.in
1 .TH WIMLIB-IMAGEX 1 "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
3 @IMAGEX_PROGNAME@ \- Create, modify, extract, mount, or unmount a WIM (Windows Imaging Format) archive
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
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.
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 be accessed as
55 simply \fBwim\fICOMMAND\fR; for example, \fBwimapply\fR for \fB@IMAGEX_PROGNAME@
56 apply\fR.
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 stand-alone 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 stand-alone WIM as a new image (\fB@IMAGEX_PROGNAME@
67 append\fR)
68 .IP \[bu]
69 Apply an image from a stand-alone 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 stand-alone or split WIM read-only (\fB@IMAGEX_PROGNAME@
76 mount\fR) (not available on Windows)
77 .IP \[bu]
78 Mount an image from a stand-alone 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 stand-alone WIM (\fB@IMAGEX_PROGNAME@ delete\fR)
87 .IP \[bu]
88 Export image(s) from a stand-alone 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 stand-alone WIM (\fB@IMAGEX_PROGNAME@ join\fR)
97 .IP \[bu]
98 Split a stand-alone 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)
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 wimlib (and \fB@IMAGEX_PROGNAME@\fR via \fB@IMAGEX_PROGNAME@ capture\fR)
159 supports combining multiple separate directories and files together in a
160 configurable way to create a WIM image.
161 .IP \[bu]
162 Microsoft's ImageX has some weird limitations, like it won't let you extract a
163 WIM on a shared folder, and it requires some commands to be run only from
164 Windows PE and not from regular Windows.  \fB@IMAGEX_PROGNAME@\fR does not have
165 these unusual limitations.
166 .IP \[bu]
167 There are bugs in Microsoft's WIM library and I obviously have not included the
168 same bugs in wimlib, although in some cases I have had to work around bugs for
169 compatibility purposes.
170 .IP \[bu]
171 wimlib (and \fB@IMAGEX_PROGNAME@\fR via \fB@IMAGEX_PROGNAME@ mount\fR) support
172 mounting an image from a split WIM, but Microsoft's software does not.  (Note:
173 this functionality is not available in Windows builds of wimlib and
175 .IP \[bu]
176 \fB@IMAGEX_PROGNAME@ capture\fR supports a special mode where UNIX file modes,
177 owners, and groups are stored.  (Note: this functionality is only available in
178 builds of wimlib for UNIX-like systems.)
180 On Windows, wimlib works in UTF-16LE, and there should be no problems with
181 character encodings.
182 .PP
183 On UNIX, wimlib works primarily in the locale-dependent multibyte encoding,
184 which you are strongly recommended to set to UTF-8 to avoid any problems.
186 The case sensitivity of \fB@IMAGEX_PROGNAME@\fR differs somewhat between
187 UNIX-like systems and Windows.  Filenames are internally treated as
188 case-sensitive, but on Windows paths actually provided by the user will be
189 treated as case-insensitive in order to get the "expected" behavior.  Otherwise,
190 options and non-path arguments should be specified in lower case.
192 wimlib and \fB@IMAGEX_PROGNAME@\fR are distributed under the GNU General Public
193 License version 3 or later.  Be aware this means this software is provided as-is
194 and has no warranty; see COPYING for details.
196 Report bugs to ebiggers3@gmail.com.
198 .BR @IMAGEX_PROGNAME@-append (1),
199 .BR @IMAGEX_PROGNAME@-apply (1),
200 .BR @IMAGEX_PROGNAME@-capture (1),
201 .BR @IMAGEX_PROGNAME@-delete (1),
202 .BR @IMAGEX_PROGNAME@-dir (1),
203 .BR @IMAGEX_PROGNAME@-export (1),
204 .BR @IMAGEX_PROGNAME@-extract (1),
205 .BR @IMAGEX_PROGNAME@-info (1),
206 .BR @IMAGEX_PROGNAME@-join (1),
207 .BR @IMAGEX_PROGNAME@-mount (1),
208 .BR @IMAGEX_PROGNAME@-mountrw (1),
209 .BR @IMAGEX_PROGNAME@-optimize (1),
210 .BR @IMAGEX_PROGNAME@-split (1),
211 .BR @IMAGEX_PROGNAME@-unmount (1),
212 .BR @IMAGEX_PROGNAME@-update (1),