+++ /dev/null
-.TH WIMLIB-IMAGEX "1" "March 2014" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
-.SH NAME
-@IMAGEX_PROGNAME@-capture, @IMAGEX_PROGNAME@-append \- Create or append a WIM image
-.SH SYNOPSIS
-\fB@IMAGEX_PROGNAME@ capture\fR \fISOURCE\fR \fIWIMFILE\fR [\fIIMAGE_NAME\fR \
-[\fIIMAGE_DESCRIPTION\fR]] [\fIOPTION\fR...]
-.br
-\fB@IMAGEX_PROGNAME@ append\fR \fISOURCE\fR \fIWIMFILE\fR [\fIIMAGE_NAME\fR \
-[\fIIMAGE_DESCRIPTION\fR]] [\fIOPTION\fR...]
-.SH DESCRIPTION
-The \fB@IMAGEX_PROGNAME@ capture\fR and \fB@IMAGEX_PROGNAME@ append\fR commands
-create a Windows Imaging (WIM) image from a directory tree. The
-\fB@IMAGEX_PROGNAME@ capture\fR command creates a new WIM file containing the
-captured image, while the \fB@IMAGEX_PROGNAME@ append\fR command appends the
-captured image to an existing WIM file.
-These commands are also available as simply \fBwimcapture\fR and \fBwimappend\fR
-if the appropriate hard links or batch files are installed.
-.PP
-Background information: A WIM image is an independent directory tree in a WIM
-file. A WIM file may contain any number of separate images. WIM files are
-single-instancing with regards to file data, so a file is stored only one time
-in the entire WIM, regardless of how many images the file appears in.
-.PP
-\fISOURCE\fR specifies the location of the files to create the new WIM image
-from. If \fISOURCE\fR is a directory, the WIM image is captured from that
-directory (see \fBDIRECTORY CAPTURE (UNIX)\fR or \fBDIRECTORY CAPTURE
-(WINDOWS)\fR). Alternatively, if the \fB--source-list\fR option is specified,
-\fISOURCE\fR is interpreted as a file that itself provides a list of
-files and directories to include in the new WIM image. Still
-alternatively, only on UNIX-like systems, if \fISOURCE\fR is a
-regular file or block device, it is interpreted as an NTFS volume from
-which a WIM image is to be captured using libntfs-3g (see \fBNTFS VOLUME CAPTURE
-(UNIX)\fR).
-.PP
-\fIIMAGE_NAME\fR and \fIIMAGE_DESCRIPTION\fR specify the name and description to
-give the new WIM image. If \fIIMAGE_NAME\fR is not specified, it defaults to
-the base name (excluding path to parent directory) of \fISOURCE\fR, but if this
-name already exists in \fIWIMFILE\fR, a unique suffix is added. Otherwise,
-\fIIMAGE_NAME\fR must be either a name that does not already exist as an image in
-\fIWIMFILE\fR, or the empty string to create an image with no name. If
-\fIIMAGE_DESCRIPTION\fR is not specified, no description is given to the new
-image.
-.PP
-As a special case, if \fIWIMFILE\fR is "-", the \fB--pipable\fR option is
-assumed and the WIM file is written to standard output in a special pipable
-format. See the documentation for \fB--pipable\fR for more details.
-.SH DIRECTORY CAPTURE (UNIX)
-This section documents how \fB@IMAGEX_PROGNAME@\fR captures files from a
-directory tree on UNIX-like systems. See \fBDIRECTORY CAPTURE (WINDOWS)\fR for
-the corresponding documentation for Windows.
-.PP
-On UNIX-like systems, when \fISOURCE\fR specifies a directory or a symbolic link
-to a directory, the WIM image will be captured from the directory tree rooted at
-this directory. This directory can be on any type of filesystem, and mount
-points are followed recursively. However, it is important to keep in mind that
-the WIM format was designed for Windows, so it cannot store all possible
-metadata from filesystems used on UNIX-like systems. The main information that
-will \fInot\fR be stored is:
-.IP \[bu] 4
-UNIX file owners, groups, and modes. (Exception: see the \fB--unix-data\fR
-option.) As a result, file permissions will not be stored, and files that are
-neither regular files, directories, nor symbolic links, such as device files and
-FIFOs, cannot be captured and will be excluded by default.
-.IP \[bu]
-Extended attributes. This mainly includes extensions to the traditional UNIX
-security model, such as SELinux security labels, POSIX ACLs, and capabilities
-labels.
-.IP \[bu]
-Linux file attributes, as can be changed using the \fBchattr\fR (1) utility.
-.PP
-Notes: Timestamps are stored with 100 nanosecond granularity and include last
-modification time (mtime) and last access time (atime), but not last status
-change time (ctime). Hard links and symbolic links are supported by the WIM
-format and \fIare\fR stored. Symbolic links are turned into "native" Windows
-symbolic links, or "reparse points"; this process is fully reversible, e.g.
-automatically by \fB@IMAGEX_PROGNAME@ apply\fR, unless the symbolic link target
-contains backslash characters.
-.PP
-Pedantic note: A limitation of the WIM format prevents the unusual case where a
-single symbolic link file itself has multiple names (hard links); in this
-unlikely case, each symbolic link is stored as an independent file.
-.SH NTFS VOLUME CAPTURE (UNIX)
-This section documents how \fB@IMAGEX_PROGNAME@\fR captures files directly from
-an NTFS volume image on UNIX-like systems.
-.PP
-On UNIX-like systems, a special image capture mode is entered when \fISOURCE\fR
-is a regular file or block device. In this mode, \fISOURCE\fR is assumed to be
-an NTFS volume or volume image, and \fB@IMAGEX_PROGNAME@\fR will capture a WIM
-image containing the full contents of the NTFS volume, including NTFS-specific
-data. This is done using libntfs-3g.
-.PP
-Please note that the NTFS volume capture mode is \fInot\fR entered if
-\fISOURCE\fR is a directory, even if an NTFS filesystem is mounted on
-\fISOURCE\fR using ntfs-3g. You must specify the NTFS volume itself (and it
-must be unmounted, and you must have permission to read from it).
-.PP
-The NTFS volume capture mode attempts to capture as much data and metadata as
-possible, including:
-.IP \[bu] 4
-All data streams of all unencrypted files, including the unnamed data stream as
-well as all named data streams.
-.IP \[bu]
-Reparse points, including symbolic links, junction points, and other reparse
-points.
-.IP \[bu]
-File and directory creation, access, and modification timestamps, using the
-native NTFS resolution of 100 nanoseconds.
-.IP \[bu]
-Windows security descriptors, including all components (owner, group, DACL, and
-SACL).
-.IP \[bu]
-DOS/Windows file attribute flags.
-.IP \[bu]
-All names of all files, including names in the Win32 namespace, DOS namespace,
-Win32+DOS namespace, and POSIX namespace. This includes hard links.
-.PP
-However, the main limitations of this NTFS volume capture mode are:
-.IP \[bu] 4
-Encrypted files are excluded by default. Although ntfs-3g can read their data,
-they need to be stored in the WIM file in a special format that wimlib does not
-yet support (except on Windows, where wimlib can treat the data as opaque and
-hand it off to the appropriate API function).
-.IP \[bu]
-The sparse attribute on sparse files will be saved, but the data stored will be
-the full data of the file rather than the "sparse" data. (The data is, however,
-subject to the WIM format's compression.)
-.SH DIRECTORY CAPTURE (WINDOWS)
-On Windows, \fB@IMAGEX_PROGNAME@ capture\fR and \fB@IMAGEX_PROGNAME@ append\fR
-natively support Windows-specific and NTFS-specific data. They therefore act
-similarly to the corresponding commands of Microsoft's ImageX. For best
-results, the directory being captured should be on an NTFS volume and
-\fB@IMAGEX_PROGNAME@\fR should be run with Administrator privileges; however,
-non-NTFS filesystems and running without Administrator privileges are also
-supported.
-.PP
-On Windows, \fB@IMAGEX_PROGNAME@ capture\fR and \fB@IMAGEX_PROGNAME@ append\fR
-try to archive as much data and metadata as possible, including:
-.IP \[bu] 4
-All data streams of all files.
-.IP \[bu]
-Reparse points, including symbolic links, junction points, and other reparse
-points, if supported by the source filesystem. (Note: see \fB--rpfix\fR and
-\fB--norpfix\fR for documentation on exactly how absolute symbolic links and
-junctions are captured.)
-.IP \[bu]
-File and directory creation, access, and modification timestamps. These are
-stored with Windows NT's native timestamp resolution of 100 nanoseconds.
-.IP \[bu]
-Security descriptors, if supported by the source filesystem and \fB--no-acls\fR
-is not specified. However, beware that unless \fB--strict-acls\fR is specified,
-the security descriptors for individual files or directories may be omitted or
-only partially captured if the user does not have permission to read them, which
-can be a problem if \fB@IMAGEX_PROGNAME@\fR is run as a non-Administrator.
-.IP \[bu]
-File attributes, including hidden, sparse, compressed, encrypted, etc.
-Encrypted files will be stored in encrypted form rather than in plain text.
-Transparently compressed files will be read as uncompressed and stored subject
-to the WIM's own compression. There is no special handling for storing sparse
-files, but they are likely to compress to a small size.
-.IP \[bu]
-DOS names (8.3) names of files; however, the failure to read them is not
-considered an error condition.
-.IP \[bu]
-Hard links, if supported by the source filesystem.
-.PP
-Note: the capture process is reversible, since when \fB@IMAGEX_PROGNAME@
-apply\fR (on Windows) extracts the captured WIM image, it will extract all of
-the above information, at least to the extent supported by the destination
-filesystem. One exception is that since encrypted files are stored as
-encrypted, their data will not be available if restored on a Windows system
-that does not have the decryption key.
-.PP
-Pedantic note: since Windows is not fully compatible with its own filesystem
-(NTFS), on Windows wimlib cannot archive certain files that may exist on a valid
-NTFS filesystem but are inaccessible to the Windows API, for example two files
-with names differing only in case in the same directory, or a file whose name
-contains certain characters considered invalid by Windows. If you run into
-problems archiving such files consider using the \fBNTFS VOLUME CAPTURE
-(UNIX)\fR mode from Linux.
-.SH OPTIONS
-.TP 6
-\fB--boot\fR
-Specifies that the new image is to be made the bootable image of the WIM archive.
-.TP
-\fB--check\fR
-For \fB@IMAGEX_PROGNAME@ append\fR, before performing the append operation,
-check the integrity of \fIWIMFILE\fR if an integrity table is present.
-Furthermore, include an integrity table in the new WIM file
-(\fB@IMAGEX_PROGNAME@ capture\fR) or the modified WIM file (\fB@IMAGEX_PROGNAME@
-append\fR). If this option is not specified, no integrity table is included in
-a WIM file created with \fB@IMAGEX_PROGNAME@ capture\fR, while a WIM file
-updated with \fB@IMAGEX_PROGNAME@ append\fR will be written with an integrity
-table if and only if one was present before.
-.TP
-\fB--compress\fR=\fITYPE\fR
-Specifies the compression type for the new WIM file. This flag is only valid
-for \fB@IMAGEX_PROGNAME@ capture\fR, since the compression mode for
-\fB@IMAGEX_PROGNAME@ append\fR must be the same as that of the existing
-WIM (and is automatically set as such). \fITYPE\fR may be "none",
-"fast", or "maximum". As of wimlib v1.5.3, the default is LZX compression, but
-in a special mode that is somewhere in between "fast" and "maximum" in terms of
-speed and compression ratio. Use \fB--compress\fR=\fImaximum\fR to explicitly
-request a better compression ratio at the cost of more time spent compressing.
-.IP ""
-You may also specify the actual names of the compression algorithms, "XPRESS"
-and "LZX", instead of "fast" and "maximum", respectively.
-.IP ""
-As of wimlib v1.6.0, a third compression type, "recovery" or "LZMS", is also
-available. Its use is generally not recommended because other than wimlib
-itself, as of Windows 8 it is only compatible with WIMGAPI and Windows Setup
-(not even ImageX or Dism). However, LZMS is the compression algorithm used in
-packed resources created if the \fB--pack-streams\fR option is specified.
-.TP
-\fB--compress-slow\fR
-Spend even more time compressing the data to achieve a very slightly better
-compression ratio. This currently only has an effect for LZX ("maximum", the
-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
-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.
-.TP
-\fB--pack-streams\fR, \fB--solid\fR
-Create a "solid" archive that compresses multiple unique streams ("files")
-together, rather than each unique stream ("file") independently. This can
-result in a significantly better compression ratio, but this format greatly
-decreases the performance of random access to the data, as may occur on a WIM
-mounted with \fB@IMAGEX_PROGNAME@ mount\fR. Also, WIMs created using this
-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.
-.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).
-.TP
-\fB--threads\fR=\fINUM_THREADS\fR
-Number of threads to use for compressing data. Default: autodetect (number of
-available CPUs).
-.TP
-\fB--rebuild\fR
-For \fB@IMAGEX_PROGNAME@ append\fR: rebuild the entire WIM rather than appending the new
-data to the end of it. Rebuilding the WIM is slower, but will save a little bit
-of space that would otherwise be left as a hole in the WIM. Also see \fB@IMAGEX_PROGNAME@
-optimize\fR(1).
-.TP
-\fB--flags\fR=\fIEDITIONID\fR
-Specify a string to use in the <FLAGS> element of the XML data for the new
-image.
-.TP
-\fB--dereference\fR
-(UNIX-like systems only) Follow symbolic links and archive the files they point
-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.
-.IP ""
-If this option is not specified the following default configuration file is
-used:
-.IP ""
-.RS
-.RS
-.nf
-[ExclusionList]
-\\$ntfs.log
-\\hiberfil.sys
-\\pagefile.sys
-"\\System Volume Information"
-\\RECYCLER
-\\Windows\\CSC
-.RE
-.RE
-.fi
-.TP
-\fB--unix-data\fR
-(UNIX-like systems only) Store the UNIX owner, group, and mode of all captured
-files. This is done by adding a special alternate data stream to each directory
-entry that contains this information. Please note that this flag is for
-convenience only, in case you want to use \fB@IMAGEX_PROGNAME@\fR to archive
-files on UNIX. Microsoft's software will not understand this special
-information. You also may run into problems when applying an image with UNIX
-data from a pipable WIM.
-.TP
-\fB--no-acls\fR
-Do not capture files' security descriptors.
-.TP
-\fB--strict-acls\fR
-Fail immediately if the full security descriptor of any file cannot be read. On
-Windows, the default behavior without this option is to first try omitting the
-SACL from the security descriptor, then to try omitting the security descriptor
-entirely. The purpose of this is to capture as much data as possible without
-always requiring Administrator privileges. However, if you desire that all
-security descriptors be captured exactly, you may wish to provide this option,
-although the Administrator should have permission to read everything anyway.
-.TP
-\fB--rpfix\fR, \fB--norpfix\fR
-Set whether to fix targets of absolute symbolic links (reparse points in Windows
-terminology) or not. When enabled (\fB--rpfix\fR), absolute symbolic links that
-point inside the directory tree being captured will be adjusted to be absolute
-relative to the root of the directory tree being captured. In addition,
-absolute symbolic links that point outside the directory tree being captured
-will be ignored and not be captured at all. When disabled (\fB--norpfix\fR),
-absolute symbolic links will be captured exactly as is.
-.IP ""
-The default behavior for \fB@IMAGEX_PROGNAME@ capture\fR is equivalent to
-\fB--rpfix\fR. The default behavior for \fB@IMAGEX_PROGNAME@ append\fR will be
-\fB--rpfix\fR if reparse point fixups have previously been done on
-\fIWIMFILE\fR, otherwise \fB--norpfix\fR.
-.IP ""
-In the case of a multi-source capture, (\fB--source-list\fR specified), passing
-\fB--norpfix\fR is recommended. Otherwise, reparse point fixups will be
-disabled on all capture sources destined for non-root locations in the WIM
-image, while capture sources destined for the WIM root will get the default
-behavior from the previous paragraph.
-.TP
-\fB--source-list\fR
-\fB@IMAGEX_PROGNAME@ capture\fR and \fB@IMAGEX_PROGNAME@ append\fR support
-creating a WIM image from multiple separate files or directories. When
-\fB--source-list\fR is specified, the \fISOURCE\fR argument specifies the name
-of a text file, each line of which is either 1 or 2 whitespace separated file
-paths. The first file path, the source, specifies the path to a file or
-directory to capture into the WIM image. It may be either absolute or relative
-to the current working directory. The second file path, if provided, is the
-target and specifies the path in the WIM image that this file or directory will
-be saved as. Leading and trailing slashes in the target are ignored, except if
-it consists entirely of slashes (e.g. "/"), which indicates that the directory
-is to become the root of the WIM image. If omitted, the target string defaults
-to the same as the source string.
-.IP ""
-An example source list file is as follows:
-.IP ""
-.RS
-.RS
-.nf
-# Make the WIM image from the 'winpe' directory
-winpe /
-
-# Send the 'overlay' directory to '/overlay' in the WIM image
-overlay /overlay
-
-# Overlay a separate directory directly on the root of the WIM image.
-# This is only legal if there are no conflicting files.
-/data/stuff /
-.RE
-.RE
-.fi
-.IP ""
-Subdirectories in the WIM are created as needed. Multiple source directories
-may share the same target, which implies an overlay; however, an error is issued
-if the same file appears in different overlays to the same directory.
-.IP ""
-File paths containing whitespace may be quoted with either single quotes or
-double quotes. Quotes may not be escaped.
-.IP ""
-Lines consisting only of whitespace and lines beginning with '#' preceded by
-optional whitespace are ignored.
-.IP ""
-As a special case, if \fISOURCE\fR is "-", the source list is read from standard
-input rather than an external file.
-.IP ""
-The NTFS volume capture mode on UNIX-like systems cannot be used with
-\fB--source-list\fR, as only capturing a full NTFS volume is supported.
-.TP
-\fB--pipable\fR
-Create a "pipable" WIM, which can be applied fully sequentially, including from
-a pipe. An image in the resulting WIM can be applied with \fB@IMAGEX_PROGNAME@
-apply\fR, either normally by specifying the WIM file name, or with
-\fB@IMAGEX_PROGNAME@ apply -\fR to read the WIM from standard input. See
-\fB@IMAGEX_PROGNAME@ apply\fR(1) for more details.
-.IP ""
-For append operations, this option will result in a full rebuild of the WIM to
-make it pipable. For capture operations, the captured WIM is simply created as
-pipable. Beware that the more images you add to a pipable WIM, the less
-efficient piping it will be, since more unneeded data will be sent through the
-pipe.
-.IP ""
-When wimlib creates a pipable WIM, it carefully re-arranges the components of
-the WIM so that they can be read sequentially and also makes several other
-modifications. As a result, these "pipable" WIMs are \fInot compatible with
-Microsoft's software\fR, so keep this in mind if you're going to use them. If
-desired, you can use \fB@IMAGEX_PROGNAME@ optimize --not-pipable\fR to re-write
-a pipable WIM as a regular WIM. (\fB@IMAGEX_PROGNAME@ export\fR also provides
-the capability to export images from a pipable WIM into a non-pipable WIM, or
-vice versa.)
-.IP ""
-For the most part, wimlib operates on pipable WIMs transparently. You can
-modify them, add or delete images, export images, and even create split pipable
-WIMs. The main disadvantages are that appending is (currently) less efficient
-(\fB--rebuild\fR is always implied), and also they aren't compatible with
-Microsoft's software.
-.IP ""
-\fB@IMAGEX_PROGNAME@ capture\fR and \fB@IMAGEX_PROGNAME@ append\fR can both
-write a pipable WIM directly to standard output; this is done automatically if
-\fIWIMFILE\fR is specified as "-". (In that case, \fB--pipable\fR is assumed.)
-.TP
-\fB--not-pipable\fR
-Ensure the resulting WIM is in the normal, non-pipable WIM format. This is the
-default for \fB@IMAGEX_PROGNAME@ capture\fR, except when writing to standard
-output (\fIWIMFILE\fR specified as "-"), and also for \fB@IMAGEX_PROGNAME@
-append\fR, except when appending to a WIM that is already pipable.
-.TP
-\fB--update-of\fR=[\fIWIMFILE\fR:]\fIIMAGE\fR
-Declares that the image being captured or appended from \fISOURCE\fR is mostly the same as
-the existing image \fIIMAGE\fR in \fIWIMFILE\fR, but captured at a later point
-in time, possibly with some modifications in the intervening time. This is
-designed to be used in incremental backups of the same filesystem or directory
-tree. \fIIMAGE\fR can be a 1-based index or name of an existing image in
-\fIWIMFILE\fR. It can also be a negative integer to index backwards into the
-images (e.g. -1 means the last existing image in \fIWIMFILE\fR).
-.IP ""
-When this option is provided, the capture or append of the new image will be
-optimized by not reading files that, based on metadata such as timestamps,
-appear not to have been modified since they were archived in the existing
-\fIIMAGE\fR. Barring manipulation of timestamps, this option only affects
-performance and does not change the resulting WIM image.
-.IP ""
-As shown, the full syntax for the argument to this option is to specify the WIM
-file, a colon, and the image; for example, "--update-of mywim.wim:1". However,
-the WIM file and colon may be omitted, in which case the WIM file will default
-to the WIM file being appended to for append operations, or the WIM file from
-which a delta is being taken (only if \fB--delta-from\fR is specified exactly
-once) for capture operations.
-.TP
-\fB--delta-from\fR=\fIWIMFILE\fR
-For \fB@IMAGEX_PROGNAME@ capture\fR only: capture the new WIM as a "delta" from
-\fIWIMFILE\fR. Any streams that would ordinarily need to be archived in the new
-WIM are omitted if they are already present in the \fIWIMFILE\fR on which the
-delta is being based. The new WIM will still contain a full copy of the image
-metadata, but this is typically only a small fraction of a WIM's total size.
-.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
-operate on, but also reference the base WIM(s) using the \fB--ref\fR option.
-Beware: to retain the proper functioning of the delta WIM, you can only add, not
-delete, files and images to the base WIM(s) following the capture of a delta
-from it.
-.IP ""
-\fB--delta-from\fR may be combined with \fB--update-of\fR to increase the
-speed of capturing a delta WIM.
-.IP ""
-As an example, consider the following backup and restore sequence:
-.IP ""
-.RS
-.nf
-(initial backup)
-
-$ wimcapture /some/directory bkup-base.wim
-
-(some days later, create second backup as delta from first)
-
-$ wimcapture /some/directory bkup-2013-08-20.dwm \\
- --update-of bkup-base.wim:-1 --delta-from bkup-base.wim
-
-(restoring the second backup)
-
-$ wimapply bkup-2013-08-20.dwm --ref=bkup-base.wim 1 \\
- /some/directory
-.RE
-.fi
-.IP ""
-However, note that as an alternative to the above sequence that used a delta
-WIM, the second backup could have simply been appended to the WIM as new image
-using \fB@IMAGEX_PROGNAME@ append\fR. Delta WIMs should be used only if it's
-desired to base the backups or images on a separate, large file that is rarely
-modified.
-.IP ""
-Note: unlike "pipable" WIMs (created with the \fB--pipable\fR option), "delta"
-WIMs (created with the \fB--delta-from\fR option) are compatible with
-Microsoft's software. You can use the /ref option of imagex.exe to reference
-the base WIM(s), similar to above.
-.IP ""
-Additional note: \fB@IMAGEX_PROGNAME@\fR is generalized enough that you can in
-fact combine \fB--pipable\fR and \fB--delta-from\fR to create pipable delta
-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.
-.SH NOTES
-\fB@IMAGEX_PROGNAME@ append\fR does not support appending an image to a split WIM.
-.PP
-It is safe to abort an \fB@IMAGEX_PROGNAME@ append\fR command partway through;
-however, after doing this, it is recommended to run \fB@IMAGEX_PROGNAME@
-optimize\fR to remove any data that was appended to the physical WIM file but
-not yet incorporated into the structure of the WIM, unless the WIM was being
-fully rebuilt (e.g. with \fB--rebuild\fR), in which case you should delete the
-temporary file left over.
-.PP
-\fB@IMAGEX_PROGNAME@\fR creates WIMs compatible with Microsoft's software
-(imagex.exe, Dism.exe, wimgapi.dll), with some caveats:
-.IP \[bu] 4
-With \fB@IMAGEX_PROGNAME@\fR on UNIX-like systems, it is possible to create a
-WIM image containing files with names differing only in case, or files with
-names containing the characters ':', '*', '?', '"', '<', '>', '|', or '\\',
-which are valid on POSIX-compliant filesystems but not Windows. Be warned that
-such files will not be extracted by default by the Windows version of
-\fB@IMAGEX_PROGNAME@\fR, and (even worse) Microsoft's ImageX can be confused by
-such names and quit extracting the image partway through. (It perhaps is worth
-pointing out that Windows' own default filesystem, NTFS, supports these
-characters, although Windows does not!)
-.IP \[bu]
-WIMs captured with \fB--unix-data\fR should be assumed to be incompatible with
-Microsoft's software.
-.IP \[bu]
-Pipable WIMs are incompatible with Microsoft's software. Pipable WIMs are
-created only if \fIWIMFILE\fR was specified as "-" (standard output) or if
-the \fB--pipable\fR flag was specified.
-.IP \[bu]
-WIMs captured with a non-default chunk size (with the \fB--chunk-size\fR option)
-or as solid archives (with the \fB--pack-streams\fR option) or with LZMS
-compression (with \fB--compress\fR=LZMS or \fB--compress\fR=recovery) have
-varying levels of compatibility with Microsoft's software. The best
-compatibility is achieved with WIMGAPI itself (not ImageX or Dism) on Windows 8
-or later.
-.SH EXAMPLES
-First example: Create a new WIM 'mywim.wim' with "maximum" (LZX) compression
-that will contain a captured image of the directory tree 'somedir'. Note that
-the image name need not be specified and will default to 'somedir':
-.RS
-.PP
-@IMAGEX_PROGNAME@ capture somedir mywim.wim --compress=maximum
-.RE
-.PP
-or, if the \fBwimcapture\fR hard link or batch file has been installed, the
-abbreviated form can be used:
-.RS
-.PP
-wimcapture somedir mywim.wim --compress=maximum
-.RE
-.PP
-The remaining examples will use the long form, however. Next, append the image
-of a different directory tree to the WIM created above:
-.RS
-.PP
-@IMAGEX_PROGNAME@ append anotherdir mywim.wim
-.RE
-.PP
-Easy enough, and the above examples of imaging directory trees work on both
-UNIX-like systems and Windows. Next, capture a WIM with several non-default
-options, including "fast" (XPRESS) compression, an integrity table, no messing
-with absolute symbolic links, and an image name and description:
-.RS
-.PP
-@IMAGEX_PROGNAME@ capture somedir mywim.wim --compress=fast \\
-.RS
---check --norpfix "Some Name" "Some Description"
-.RE
-.RE
-.PP
-Capture an entire NTFS volume into a new WIM file and name the image "Windows
-7". On UNIX-like systems, this requires using the special mode described in
-\fBNTFS VOLUME CAPTURE (UNIX)\fR where \fISOURCE\fR is a file or block device
-containing an NTFS filesystem:
-.RS
-.PP
-@IMAGEX_PROGNAME@ capture /dev/sda2 windows7.wim "Windows 7"
-.RE
-.PP
-or, on Windows, to capture a full NTFS volume you instead need to specify the
-root directory of the mounted volume, for example:
-.RS
-.PP
-@IMAGEX_PROGNAME@ capture E:\\ windows7.wim "Windows 7"
-.RE
-.PP
-Same as above example with capturing an NTFS volume from \fB@IMAGEX_PROGNAME@\fR
-running on a UNIX-like system, but capture the WIM in the wimlib-specific
-"pipable" format that can be piped to \fB@IMAGEX_PROGNAME@ apply\fR:
-.RS
-.PP
-@IMAGEX_PROGNAME@ capture /dev/sda2 windows7.wim "Windows 7" \\
-.br
-.RS
---pipable
-.RE
-.RE
-.PP
-Same as above, but instead of writing the pipable WIM to the file
-"windows7.wim", write it directly to standard output through a pipe into some
-other program "someprog", which could, for example, be a program or script that
-streams the data to a server. Note that \fB--pipable\fR need not be explicitly
-specified when using standard output as the WIM "file":
-.RS
-.PP
-@IMAGEX_PROGNAME@ capture /dev/sda2 - "Windows 7" | someprog
-.RE
-.SH SEE ALSO
-.BR @IMAGEX_PROGNAME@ (1),
-.BR @IMAGEX_PROGNAME@-apply (1)
git://wimlib.net / wimlib / blobdiff