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