-.TH IMAGEX "1" "March 2013" "imagex (wimlib) wimlib @VERSION@" "User Commands"
+.TH WIMLIB-IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
.SH NAME
-imagex-capture, imagex-append \- Create or append a WIM image
-
+@IMAGEX_PROGNAME@-capture, @IMAGEX_PROGNAME@-append \- Create or append a WIM image
.SH SYNOPSIS
-\fBimagex capture\fR \fISOURCE\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
-\fBimagex append\fR \fISOURCE\fR \fIWIMFILE\fR [\fIIMAGE_NAME\fR] \
-[\fIDESCRIPTION\fR] [\fIOPTION\fR]...
-
+\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
-
-The \fBimagex capture\fR and \fBimagex append\fR commands create a Windows
-Imaging (WIM) image from a directory tree. The \fBimagex capture\fR command
-creates a new WIM file containing the captured image, while the \fBimagex
-append\fR command appends the captured image to an existing WIM file.
-
-Note: this man page primarily documents the UNIX behavior. See \fBWINDOWS
-VERSION\fR for information specific to the Windows build of wimlib.
-
-A WIM image is an independent directory tree in the WIM file. A WIM file may
-contain any number of separate images. However, files are stored only one time
+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. Alternatively, if \fISOURCE\fR is a regular file or block device, it
-is interpreted as a NTFS volume from which a WIM image is to be captured. Still
-alternatively, if the \fB--source-list\fR option is given, \fISOURCE\fR is
-interpreted as a file that itself provides a list of files and directories to
-include in the new WIM 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 \fISOURCE\fR. If \fIDESCRIPTION\fR is not given, no description is
-given to the new image.
-
-.SH NORMAL MODE
-
-The normal image capture mode is entered when \fISOURCE\fR specifies a
-directory. The WIM image will be captured from the directory tree rooted at
-this directory. The directory may be on any type of filesystem.
-
-In this mode, the following information is captured from the directory tree:
-
+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
-The "normal" name and contents of each file and directory
+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]
-File and directory creation, access, and modification timestamps to the nearest
-100 nanoseconds, if supported by the underlying filesystem
+Extended attributes. This mainly includes extensions to the traditional UNIX
+security model, such as SELinux security labels, POSIX ACLs, and capabilities
+labels.
.IP \[bu]
-Hard links and symbolic links
-
+Files that are neither regular files, directories, nor symbolic links, such as
+device files and FIFOs. These will be excluded by default.
.PP
-
-However, in this mode, the following information is \fInot\fR captured from the
-directory tree:
-
-.IP \[bu] 4
-File permissions. The resulting WIM image will not contain any security
-descriptors because the format of the security descriptors is Windows-specific,
-and they cannot contain UNIX file modes. (Exception: see the \fB--unix-data\fR
-option.)
-
-.IP \[bu]
-No alternate data streams will be captured, since these do not exist on
-POSIX-compliant filesystems. The resulting WIM image will not contain any
-alternate data streams. (Exception: see the \fB--unix-data\fR option.)
-
-.SH NTFS MODE
-
-A special image capture mode is entered when \fISOURCE\fR is a regular file or
-block device. \fISOURCE\fR is interpreted as an NTFS volume and opened using
-libntfs-3g. If successful, a WIM image is captured containing the contents of
-the NTFS volume, including NTFS-specific data.
-
-Please note that the NTFS image capture mode is \fInot\fR entered if
-\fISOURCE\fR is a directory, even if a NTFS filesystem is mounted on
-\fISOURCE\fR. You must specify the NTFS volume itself (and it must be
-unmounted, and you must have permission to read from it).
-
-More specifically, in this mode, the following types of information are captured
-from the NTFS volume:
-
+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 files, including the un-named data stream as well as all
-named data streams.
+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 from NTFS
-inodes (these have a resolution of 100 nanoseconds).
+File and directory creation, access, and modification timestamps, using the
+native NTFS resolution of 100 nanoseconds.
.IP \[bu]
-The security descriptor for each NTFS inode.
+Windows security descriptors, including all components (owner, group, DACL, and
+SACL).
.IP \[bu]
-File attribute flags.
+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.
-
-.SH SOURCE LIST MODE
-
-Yet another capture mode is entered when the \fB--source-list\fR option is
-given. It is essentially an extension of the \fBNORMAL MODE\fR that allows
-multiple files or directories to be incorporated into a WIM image using a single
-\fBimagex capture\fR or \fBimagex append\fR command. See the documentation for
-\fB--source-list\fR below.
-
-.SH WINDOWS VERSION
-
-This section documents the differences between \fBimagex capture\fR and
-\fBimagex append\fR in the Windows builds of wimlib versus the rest of this man
-page, which is written to document UNIX build.
-
-\fBimagex capture\fR and \fBimagex append\fR do not have separate "normal" and
-"NTFS" modes on Windows. There is simply one mode, and it uses the Windows API
-to capture NTFS-specific information, including alternate data streams, reparse
-points, hard links, and file attributes. So, you essentially get the advantages
-of the "NTFS mode" documented above, but you can capture a WIM image from any
-directory, not just an entire NTFS volume. This is essentially the same
-behavior as Microsoft's ImageX.
-
-The \fB--source-list\fR option is supported on Windows, but the
-\fB--dereference\fR option is not.
-
-Except for the differences documented in this section, the Windows build of
-\fBimagex capture\fR and \fBimagex append\fR should be essentially equivalent to
-the UNIX build. However, one additional thing to note is that wimlib's Windows
-ImageX is NOT written to be command-line compatible with Microsoft's ImageX,
-although they are very similar.
-
+.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 or the modified WIM file. If
-this option is not specified, no integrity table is included in \fIWIMFILE\fR,
-even if there was one before in the case of \fBimagex append\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 \fBimagex capture\fR, since the compression mode for \fBimagex append\fR
-must be the same as that of the existing WIM. \fITYPE\fR may be "none",
-"maximum", or "fast". By default, it is "fast".
-
+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
-processors). Note: if creating or appending to an uncompressed WIM, additional
-threads will not be used, regardless of this parameter, since no compression
-needs to be done in this case.
+available CPUs).
.TP
\fB--rebuild\fR
-For \fBimagex append\fR: rebuild the entire WIM rather than appending the new
+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 \fBimagex
-optimize\fR.
+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--verbose\fR
-Print the names of files and directories as they are captured, as well as a few
-other informational messages.
+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.) This flag is only valid in the normal image
-capture mode.
+(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.
-
-The format of the configuration file is a number of sections containing file
+.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 file globs to
+implemented. The [ExclusionList] section specifies a list of path globs to
exclude from capture, while the [ExclusionException] section specifies a list of
-file globs to include in the capture even if the matched file or directory name
+path globs to include in the capture even if the matched file or directory name
also appears in the [ExclusionList].
-
-Relative globs with only one path component match against a filename in any
-directory. Relative globs with multiple path components, as well as absolute
-globs, are treated as paths starting at the root directory of capture, or the
-root of the NTFS volume for NTFS 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 ""
+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. However, globs with spaces in them currently must not be quoted.
-Empty lines are ignored.
-
+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
-.PP
.nf
[ExclusionList]
\\$ntfs.log
\\hiberfil.sys
\\pagefile.sys
-\\System Volume Information
+"\\System Volume Information"
\\RECYCLER
\\Windows\\CSC
-
-[CompressionExclusionList]
-*.mp3
-*.zip
-*.cab
-\\WINDOWS\\inf\\*.pnf
.RE
.RE
-
+.fi
.TP
\fB--unix-data\fR
-Store the UNIX owner, group, and mode of regular files, symbolic links, and
-directories. 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 \fBimagex\fR to archive files on
-UNIX. Microsoft's software will not understand this special
-information.
+(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
-\fBimagex capture\fR and \fBimagex append\fR, as of wimlib 1.3.0, support a new
-option to create a WIM image from multiple files or directories. When
+\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
-filenames. The first filename, the source, specifies the path to a file or
+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 filename, if provided, is the
+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 are ignored. "/" indicates that
-the directory is to become the root of the WIM image. If not specified, the
-target string defaults to the same as the source string.
-
-An example is as follows:
-
+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
-.PP
.nf
# Make the WIM image from the 'winpe' directory
winpe /
# 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.
-
-Filenames containing whitespace may be quoted with either single quotes or
+.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)
-The NTFS capture mode cannot be used with \fB--source-list\fR, as only capturing
-a full NTFS volume is supported.
-
-.SH NOTES
-
-\fBimage append\fR does not support appending an image to a split WIM.
-
-The different capture modes only specify the data that is captured and don't
-specify a special WIM format. A WIM file can contain images captured using
-different modes. However, all images in a WIM must have the same compression
-type, and \fBimagex\fR always enforces this.
-
-\fBimagex\fR writes WIMs having the version number 0x10d00 and a compressed
-stream chunk size of 32768. The only WIMs I've seen that are different from
-this are some pre-Vista WIMs that had a different version number.
+$ wimcapture /some/directory bkup-base.wim
-Unless \fB--rebuild\fR is specified, aborting an \fBimagex append\fR command
-mid-way through has a small chance of corrupting the WIM file. However, a
-precaution is taken against this, so it should be very unlikely. In the event
-of an aborted \fBimagex append\fR, \fBimagex optimize\fR may be run to remove
-extra data that may have been partially appended to the physical WIM file but
-not yet incorporated into the structure of the WIM.
+(some days later, create second backup as delta from first)
-Capturing or appending an image happens in two main phases: (1) scanning the
-directory or NTFS volume to checksum all the files and determine the streams to
-be written, and (2) writing the new streams to the WIM file. Streams are not
-stored in memory after (1), since there could easily be gigabytes of data;
-instead, they are read again during step (2); however, duplicate streams in the
-image, and streams already existing in any other image in the WIM, are not read
-again. In the future, it may be possible to introduce the ability to capture an
-image with reading each file only one time, although this mode would have some
-limitations--- for example, a stream might be compressed only to be thrown away
-as a duplicate once it's been checksummed.
+$ wimcapture /some/directory bkup-2013-08-20.dwm \\
+ --update-of bkup-base.wim:-1 --delta-from bkup-base.wim
-\fISOURCE\fR may be a symbolic link to a directory rather than a directory
-itself. However, additional symbolic links in subdirectories, or in additional
-source directories not destined for the WIM image root (with
-\fB--source-list\fR), are not dereferenced unless \fB--dereference\fR is
-specified.
+(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
-Create a new WIM 'mywim.wim' from the directory 'somedir', using LZX compression and
-including an integrity table:
+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 capture somedir mywim.wim --compress=maximum --check
+@IMAGEX_PROGNAME@ capture somedir mywim.wim
.RE
.PP
-Append an image to the WIM we just captured, but do it from a NTFS volume on the
-partition /dev/sda2 and name the image "Windows 7". You do not need to specify
-the compression type, because the WIM already is using LZX compression and this
-cannot be changed. You need to specify \fB--check\fR if you don't want the
-integrity table to be discarded.
+or, if the \fBwimcapture\fR hard link or batch file has been installed, the
+abbreviated form can be used:
.RS
.PP
-imagex append /dev/sda2 mywim.wim --check "Windows 7"
+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 (1)
-
+.BR @IMAGEX_PROGNAME@ (1),
+.BR @IMAGEX_PROGNAME@-apply (1)
git://wimlib.net / wimlib / blobdiff