-.TH IMAGEX "1" "May 2012" "imagex (wimlib) wimlib @VERSION@" "User Commands"
+.TH WIMLIB-IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
.SH NAME
-imagex capture \- Create a new WIM file from a directory.
-
+@IMAGEX_PROGNAME@-capture, @IMAGEX_PROGNAME@-append \- Create or append a WIM image
.SH SYNOPSIS
-\fBimagex capture\fR \fIDIRECTORY\fR \fIWIMFILE\fR [\fIIMAGE_NAME\fR] \
-[\fIDESCRIPTION\fR] [\fIOPTION\fR]...
-
+\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
-
-Captures a WIM image from \fIDIRECTORY\fR and creates a new WIM archive,
-\fIWIMFILE\fR, that contains it. \fIDIRECTORY\fR becomes the root directory of
-the image.
-
-\fIIMAGE_NAME\fR and \fIDESCRIPTION\fR specify the name and description of the
-new image. If \fIIMAGE_NAME\fR is not given, it is taken to be the same as the
-base name of \fIDIRECTORY\fR. If \fIDESCRIPTION\fR is not given, the
-description is taken to be empty.
-
+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.
+.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]
+Files that are neither regular files, directories, nor symbolic links, such as
+device files and FIFOs. These will be excluded by default.
+.PP
+Notes: hard links and symbolic links are supported by the WIM format and
+\fIare\fR stored. (Symbolic links are turned into "native" Windows symbolic
+links via reparse points; this process is reversible, e.g. automatically by
+\fB@IMAGEX_PROGNAME@ apply\fR.) 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).
+.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. See \fBDIRECTORY CAPTURE
+(WINDOWS)\fR for the corresponding documentation for Windows.
+.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 wimlib will capture a WIM image containing a
+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
+unencrypted, their data will not be available if restored on a Windows system
+that does not have the decryption key.
.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
-Include an integrity table in the new WIM file.
+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". By default, it is "maximum".
+This default behavior is different from Microsoft's ImageX, where the default is
+"fast". \fB@IMAGEX_PROGNAME@ capture\fR instead gives you the best compression
+ratio by default and makes up for the slightly slower compression by being
+faster than Microsoft's software in the first place and using multiple CPUs when
+available.
+.IP ""
+You may also specify the actual names of the compression algorithms, "XPRESS"
+and "LZX", instead of "fast" and "maximum", respectively.
+.TP
+\fB--threads\fR=\fINUM_THREADS\fR
+Number of threads to use for compressing data. Default: autodetect (number of
+available CPUs).
.TP
-\fB--compress\fR[=\fITYPE\fR]
-Specifies the compression type for the WIM file. \fITYPE\fR may be "none",
-"maximum", or "fast". By default, the compression type is "none". If \fB--compress\fR
-is specified but \fITYPE\fR is not, the compression type is taken to be
-"maximum", which is LZX compression. "fast" compression is XPRESS compression.
+\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 image.
+\fB--flags\fR=\fIEDITIONID\fR
+Specify a string to use in the <FLAGS> element of the XML data for the new
+image.
.TP
\fB--verbose\fR
Print the names of files and directories as they are captured.
.TP
\fB--dereference\fR
-Follow symlinks; archive and dump the files they point to. (The default is to
-archive the symlinks themselves)
+(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 /
-.SH EXAMPLES
-.IP
-image capture boot boot.wim --compress=maximum --check
-.LP
-Create a new WIM 'boot.wim' from the directory 'boot', using LZX compression and
-including an integrity table.
+# Send the 'overlay' directory to '/overlay' in the WIM image
+overlay /overlay
-.SH SEE ALSO
-.BR imagex (1)
+# 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 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).
+.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 file.
+.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 may be omitted, in which case it will default to the WIM
+file being appended to for append operations, or the WIM file from which a delta
+is being taken (with \fB--delta-from\fR, if specified) 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 ""
+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 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 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, 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 must be captured as pipable as well as the
+delta WIM, and when applying an image, the base WIM 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.
+.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
+\fB@IMAGEX_PROGNAME@\fR uses "maximum" (LZX) compression by default, so
+\fB--compress\fR does \fInot\fR need to be specified; furthermore, the image
+name need not be specified and will default to 'somedir':
+.RS
+.PP
+@IMAGEX_PROGNAME@ capture somedir mywim.wim
+.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
+.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