-.TH IMAGEX "1" "November 2012" "imagex (wimlib) wimlib @VERSION@" "User Commands"
+.TH IMAGEX "1" "March 2013" "imagex (wimlib) wimlib @VERSION@" "User Commands"
.SH NAME
imagex-capture, imagex-append \- Capture a WIM image from a directory tree
\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. 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.
+directory. Alternatively, \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
.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.
+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
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 in a single
+command. See the documentation for \fB--source-list\fR below.
+
.SH OPTIONS
.TP 6
\fB--boot\fR
needs to be done in this case.
.TP
\fB--rebuild\fR
-For \fBimagex append\fR: rebuild the entire WIM rather than appending an image
-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
+For \fBimagex 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.
.TP
\fB--flags\fR=\fIEDITIONID\fR
.RE
.RE
+.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.
+.TP
+\fB--source-list\fR
+\fBimagex capture\fR and \fBimagex append\fR, as of wimlib 1.2.7, support a new
+option to create a WIM image from multiple 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
+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
+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:
+
+.RS
+.RS
+.PP
+.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
+
+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.
+
+Filenames containing whitespace may be quoted with either single quotes or
+double quotes. Quotes may not be escaped.
+
+Empty lines, and lines beginning with '#' followed by optional whitespace, are
+ignored.
+
+As a special case, if \fISOURCE\fR is "-" the source list is read from standard
+input rather than an external file.
+
+The NTFS capture mode cannot be used with \fB--source-list\fR.
+
.SH NOTES
\fBimage append\fR does not support appending an image to a split WIM.
-The two different capture modes only specify the data that is captured and don't
+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.
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.
+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.
+
+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.
+
+\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.
+
.SH EXAMPLES
Create a new WIM 'mywim.wim' from the directory 'somedir', using LZX compression and
including an integrity table:
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" and give it a description.
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 --check
-if you don't want the integrity table to be discarded.
+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.
.RS
.PP
imagex append /dev/sda2 mywim.wim --check "Windows 7" "Warning: This operating
git://wimlib.net / wimlib / blobdiff