-.TH WIMLIB-IMAGEX "1" "March 2014" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
+.TH WIMLIB-IMAGEX "1" "May 2014" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
.SH NAME
@IMAGEX_PROGNAME@-capture, @IMAGEX_PROGNAME@-append \- Create or append a WIM image
.SH SYNOPSIS
default) and LZMS ("recovery") compression.
.TP
\fB--chunk-size\fR=\fISIZE\fR
-Set the WIM compression chunk size to \fISIZE\fR. Larger chunks mean larger
+Set the WIM compression chunk size to \fISIZE\fR bytes. Larger chunks mean larger
LZ77 dictionaries and better compression ratios on sufficiently large files, but
slower random access. \fBUsing this option is generally not recommended because
of the compatibility limitations detailed in the next paragraph.\fR But if you
-decide to use this option regardless, you may choose a chunk size that is a
-power of 2 greater than or equal to 2^15 (32768) up to a maximum determined by
-the compression format. For LZX ("maximum") compression, the maximum allowed
-chunk size is 2^21 (2097152), and for XPRESS ("fast") and LZMS ("recovery")
-compression, the maximum allowed chunk size is 2^30 (1073741824).
-.IP ""
-For XPRESS and LZX compression, Microsoft's implementation (as of Windows 8)
-does not appear to support alternate chunk sizes; although it will still open
-such files, it will crash, extract the data incorrectly, or report that the data
-is invalid. For LZMS compression, Microsoft's implementation (as of Windows 8)
-appears to only support chunk sizes that are powers of 2 between 2^15 (32768)
-and 2^20 (1048576) inclusively. In addition, wimlib versions before 1.6.0 do
-not support alternate chunk sizes.
+decide to use this option regardless, you may choose a chunk size that is
+allowed by the compression format. All formats only allow power-of-2 chunk
+sizes. For LZX ("maximum") compression the maximum allowed chunk size is 2^21
+(2097152), for XPRESS ("fast") compression the maximum allowed chunk size is
+2^26 (67108864), and for LZMS ("recovery") compression the maximum allowed chunk
+size is 2^30 (1073741824).
+.IP ""
+Beware that Microsoft's implementation has limited support for non-default chunk
+sizes. Depending on the version, their software may refuse to open the WIM, or
+open it and crash, or open it and report the data is invalid, or even extract
+the data incorrectly. In addition, wimlib versions before 1.6.0 do not support
+alternate chunk sizes.
.TP
\fB--pack-streams\fR, \fB--solid\fR
Create a "solid" archive that compresses multiple unique streams ("files")
option use a different version number in their header and as of Windows 8 are
only compatible with Windows Setup and WIMGAPI, not even ImageX and Dism.
.IP ""
-Packed resources use a compression type and chunk size that is independent of
-the WIM's "default compression type" and "default chunk size" (which may be
-adjusted by the \fB--compress\fR and \fB--chunk-size\fR options, respectively).
-For compatibility reasons, \fB@IMAGEX_PROGNAME@ capture\fR currently has no
-option to change the compression type used in packed resources; however, the
-\fB--pack-chunk-size\fR option may be used to set the chunk size.
+The default compression type and chunk size in packed resources is LZMS with
+2^25 (33554432) byte chunks. This is independent of the WIM's main compression
+type and chunk size.
.TP
\fB--pack-chunk-size\fR=\fISIZE\fR, \fB--solid-chunk-size\fR=\fISIZE\fR
Like \fB--chunk-size\fR, but set the chunk size used in packed resources. The
-compression format is LZMS, so the chunk size can be any power of 2 between 2^15
-and 2^30, inclusively. WIMGAPI (Windows 8) appears to be compatible with these
-sizes up to 2^26 inclusively, despite not being compatible with sizes greater
-than 2^20 in non-packed resources. The default is currently 2^25 (33554432).
-Note: currently, the LZMS compression algorithm uses about 15 times the chunk
-size in memory per thread, which is about 500 MB per thread for the default pack
-chunk size of 2^25 or 1 GB per thread if you change it to 2^26 (67108864).
+default is LZMS compression with 2^25 (33554432) byte chunks. This option only
+has an effect when \fB--pack-streams\fR is also specified. For maximum
+compatibility with the Microsoft implementation, do not use either of these
+options.
+.TP
+\fB--pack-compress\fR=\fITYPE\fR, \fB--solid-compress\fR=\fITYPE\fR
+Like \fB--compress\fR, but set the compression format used in packed resources.
+The default is LZMS compression with 2^25 (33554432) byte chunks. This option
+only has an effect when \fB--pack-streams\fR is also specified. For maximum
+compatibility with the Microsoft implementation, do not use either of these
+options.
.TP
\fB--threads\fR=\fINUM_THREADS\fR
Number of threads to use for compressing data. Default: autodetect (number of
to, rather than archiving the links themselves.
.TP
\fB--config\fR=\fIFILE\fR
-Specifies a configuration file for capturing the new image. The configuration
-file specifies files that are to be treated specially during the image capture.
-.IP ""
-The format of the configuration file is a number of sections containing path
-globs one per line, where each section begins with the tag [ExclusionList],
-[ExclusionException], [CompressionExclusionList], or [AlignmentList].
-Currently, only the [ExclusionList] and [ExclusionException] sections are
-implemented. The [ExclusionList] section specifies a list of path globs to
-exclude from capture, while the [ExclusionException] section specifies a list of
-path globs to include in the capture even if the matched file or directory name
-also appears in the [ExclusionList].
-.IP ""
-Relative globs with only one path component (e.g. *.mp3) match against a
-filename in any directory. Relative globs with multiple path components (e.g.
-dir/file), as well as absolute globs (e.g. /dir/file), are treated as paths
-starting at the root directory of capture, or the root of the NTFS volume for
-NTFS volume capture mode. If a directory is matched by a glob in the
-[ExclusionList], the entire directory tree rooted at that directory is excluded
-from the capture, unless \fB--dereference\fR is specified and there is another
-path into that directory through a symbolic link.
-.IP ""
-For compatibility with Windows, the path separators in the globs may be either
-forward slashes or backslashes, and the line separators may be either UNIX-style
-or DOS-style. Globs with spaces in them must be quoted, and leading and
-trailing whitespace is not significant. Empty lines and lines beginning with
-\'#' or whitespace followed by '#' are ignored.
-.IP ""
-Paths may not have drive letters in them, as they are all relative to the root
-of capture and not absolute external paths.
+Specifies a configuration file (UTF-8 or UTF-16LE encoded; plain ASCII also
+works) for capturing the new image. The configuration file specifies files that
+are to be treated specially during the image capture.
+.IP ""
+The format of the configuration file is INI-style; that is, it is arranged in
+bracketed sections. Currently, only the following sections are recognized:
+.RS
+.IP \[bu] 4
+[ExclusionList] --- contains a list of path globs to exclude from capture. If
+a directory is matched, both the directory and its contents are excluded.
+.IP \[bu]
+[ExclusionException] --- contains a list of path globs to include in the
+capture, even when the file or directory also matches a glob in [ExclusionList].
+.IP \[bu]
+[PrepopulateList] --- this does not affect capture, but if the image is applied
+later with \fB--wimboot\fR, these are globs of files that shall be extracted
+normally, not as WIMBoot "pointer files". If a directory is matched, all files
+and subdirectories are also matched recursively.
+.RE
+.IP ""
+Any unrecognized sections will be ignored, with a warning printed. Sections
+dealing with compression (e.g. [CompressionExclusion]) are not particularly
+important.
+.IP ""
+Path globs may contain the '*' and '?' meta-characters. Relative globs (e.g.
+*.mp3) match against a filename in any directory. Absolute globs (e.g.
+/dir/file), are treated as paths starting at the main directory being captured,
+or the root of the NTFS volume for NTFS volume capture mode. Do not use drive
+letters in the paths; they will be ignored. Path separators may be either
+forwards slashes or backwards slashes.
+.IP ""
+Lines beginning with the '#' or ';' characters are treated as comments and
+ignored. Globs with whitespace in them need not be quoted; however, if they
+are, both double and single quotes are accepted.
.IP ""
If this option is not specified the following default configuration file is
used:
\\$ntfs.log
\\hiberfil.sys
\\pagefile.sys
-"\\System Volume Information"
+\\swapfile.sys
+\\System Volume Information
\\RECYCLER
\\Windows\\CSC
.RE
.RE
.fi
+.IP ""
+However, special behavior applies if \fB--wimboot\fR is also specified. By
+default, with \fB--wimboot\fR specified, the file
+Windows/System32/WimBootCompress.ini in the directory being captured will be
+used as the configuration file. However, this can be overridden using
+\fB--config\fR; and this also causes the specified configuration file to be
+saved in the WIM image as Windows/System32/WimBootCompress.ini, overriding any
+that may be present on the filesystem.
.TP
\fB--unix-data\fR
(UNIX-like systems only) Store the UNIX owner, group, and mode of all captured
.IP ""
This option can be specified multiple times, in which case the resulting delta
WIM will only contain streams not present in any of the specified base
-.TP
-\fB--wimboot\fR
-Windows only: mark the image as WIMBoot-compatible. See Microsoft's
-documentation for more information about WIMBoot. This option will, by default,
-change the compression type to XPRESS and the chunk size to 4096 bytes; these
-can, however, still be overridden through the \fB--compress\fR and
-\fB--chunk-size\fR parameters, respectively. In addition, this option will, by
-default, set the configuration file to
-\fISOURCE\fR\\Windows\\System32\\WimBootCompress.ini if present and accessible;
-however, this may still be overridden through the \fB--config\fR parameter.
-\fIWIMFILE\fRs.
.IP ""
To operate on the resulting delta WIM using other commands such as
\fB@IMAGEX_PROGNAME@ apply\fR, you must specify the delta WIM as the WIM file to
WIMs. In such cases, the base WIM(s) must be captured as pipable as well as the
delta WIM, and when applying an image, the base WIM(s) must be sent over the
pipe after the delta WIM.
+.TP
+\fB--wimboot\fR
+Mark the image as WIMBoot-compatible. See Microsoft's
+documentation for more information about WIMBoot. This option will, by default,
+change the compression type to XPRESS and the chunk size to 4096 bytes; these
+can, however, still be overridden through the \fB--compress\fR and
+\fB--chunk-size\fR parameters, respectively. In addition, this option will, by
+default, set the configuration file to
+\fISOURCE\fR\\Windows\\System32\\WimBootCompress.ini if present and accessible;
+however, this may still be overridden through the \fB--config\fR parameter.
.SH NOTES
\fB@IMAGEX_PROGNAME@ append\fR does not support appending an image to a split WIM.
.PP
git://wimlib.net / wimlib / blobdiff