\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,
+(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.
+(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
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.
+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
(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.
+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 wimlib will capture a WIM image containing a
-full contents of the NTFS volume, including NTFS-specific data. This is done
-using libntfs-3g.
+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 as
+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 unnamed 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]
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
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, unless running on a version of Windows prior to
-Vista, in which case named data streams (if supported by the source filesystem)
-will not be captured.
+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
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
+encrypted, their data will not be available if restored on a Windows system
that does not have the decryption key.
.SH OPTIONS
.TP 6
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 (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
git://wimlib.net / wimlib / blobdiff