-.TH IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
+.TH WIMLIB-IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
.SH NAME
@IMAGEX_PROGNAME@-capture, @IMAGEX_PROGNAME@-append \- Create or append a WIM image
.SH SYNOPSIS
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
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 from an NTFS
-volume image on UNIX-like systems. See \fBDIRECTORY CAPTURE (WINDOWS)\fR for
-the corresponding documentation for Windows.
+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
-a NTFS volume or volume image, and wimlib will capture a WIM image containing a
+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
\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
similarly to the corresponding commands of Microsoft's ImageX. For best
-results, the directory being captured should be on an NTFS volume and you should
-be running with Administrator privileges; however, non-NTFS filesystems and
-running without Administrator privileges are also supported.
+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 as possible, including:
+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)
.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 descriptor for individual files or directories may be omitted or
-only partially captured if the user does not have permission to read it, which
-is mainly a problem if \fB@IMAGEX_PROGNAME@\fR is run as a non-Administrator.
+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.
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--delta-from\fR=\fIIMAGE\fR
+Only for \fB@IMAGEX_PROGNAME@ append\fR: declares that the new image being added
+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 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.
.SH NOTES
\fB@IMAGEX_PROGNAME@ append\fR does not support appending an image to a split WIM.
.PP
@IMAGEX_PROGNAME@ capture somedir mywim.wim
.RE
.PP
-or, if the \fBwimcapture\fR hard link or batch file is installed, the
+or, if the \fBwimcapture\fR hard link or batch file has been installed, the
abbreviated form can be used:
.RS
.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 a NTFS filesystem:
+containing an NTFS filesystem:
.RS
.PP
@IMAGEX_PROGNAME@ capture /dev/sda2 windows7.wim "Windows 7"
@IMAGEX_PROGNAME@ capture E:\\ windows7.wim "Windows 7"
.RE
.PP
-Same as above example with capturing a NTFS volume from \fB@IMAGEX_PROGNAME@\fR
+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
git://wimlib.net / wimlib / blobdiff