X-Git-Url: https://wimlib.net/git/?a=blobdiff_plain;f=doc%2Fimagex-update.1.in;h=83668f5ad74b7ce14cb1ffe8d86e50f6abb02bdc;hb=56f881eba91349abe40dd250ecbf08310cb88ce8;hp=287ea6f773bc26f4383b2e596262c0c74f0da90f;hpb=60fde240f2b47f6d015a25eee895d836cac7c68d;p=wimlib diff --git a/doc/imagex-update.1.in b/doc/imagex-update.1.in index 287ea6f7..83668f5a 100644 --- a/doc/imagex-update.1.in +++ b/doc/imagex-update.1.in @@ -1,76 +1,47 @@ -.TH IMAGEX "1" "April 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands" +.TH WIMLIB-IMAGEX "1" "March 2014" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands" .SH NAME @IMAGEX_PROGNAME@-update \- Update a WIM image - .SH SYNOPSIS -\fB@IMAGEX_PROGNAME@ update\fR \fIWIMFILE\fR [\fIIMAGE\fR] [\fIOPTION\fR...] < \fICMDFILE\fR - +\fB@IMAGEX_PROGNAME@ update\fR \fIWIMFILE\fR [\fIIMAGE\fR] [\fIOPTION\fR...] [< \fICMDFILE\fR] .SH DESCRIPTION -.PP - \fB@IMAGEX_PROGNAME@ update\fR modifies the specified \fIIMAGE\fR in the Windows Imaging (WIM) file \fIWIMFILE\fR by adding, deleting, or renaming files or directories in it. - +This command is also available as simply \fBwimupdate\fR if the appropriate +hard link or batch file has been installed. +.PP \fIIMAGE\fR specifies the image in \fIWIMFILE\fR to update. It may be a 1-based index of an image in the WIM or the name of an image in the WIM. Use the \fB@IMAGEX_PROGNAME@ info\fR (1) command to list the images a WIM file contains. \fIIMAGE\fR may be omitted if \fIWIMFILE\fR contains only one image. - +.PP The modifications to perform on the WIM image are specified as a sequence of commands, one per line, read in a text file from standard input. It is recommended that standard input be redirected from a file (\fICMDFILE\fR), as -shown above, rather than typing in commands interactively. - +shown above, rather than typing in commands interactively. Alternatively, to +specify a command directly on the command line, see the \fB--command\fR option. .SH AVAILABLE COMMANDS - This section documents the commands that may appear in the \fICMDFILE\fR described above. - .SS \fBadd\fR [\fIOPTION\fR...] \fISOURCE\fR \fIDESTINATION\fR -Adds a file or directory tree to the WIM image. \fISOURCE\fR must specify the +Add a file or directory tree to the WIM image. \fISOURCE\fR must specify the path to a file or directory on your filesystem. \fIDESTINATION\fR must specify the path inside the WIM image at which to add the file or directory tree. If -\fIDESTINATION\fR already exists in the WIM image, then an overlay is attempted; -this can be used to add multiple files to an existing directory in the WIM image -in one command. - -The available options for the \fBadd\fR command are: - -.TP 6 -\fB--verbose\fR -Print the names of files as they are captured. -.TP -\fB--dereference\fR -(UNIX only) Follow symbolic links and archive the files they point to, rather -than archiving the links themselves. -.TP -\fB--unix-data\fR -(UNIX 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. -.TP -\fB--no-acls\fR -(Windows only) Do not capture files' security descriptors. -.TP -\fB--strict-acls\fR -(Windows only) Fail immediately if the full security descriptor of any file -cannot be read. 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. - +\fIDESTINATION\fR already exists in the WIM image, then an overlay is attempted +if it is a directory; this feature can be used to add multiple files to an +existing directory in the WIM image in one command. If \fIDESTINATION\fR does +not exist in the WIM image, then any prerequisite directories are created as +needed to add the \fISOURCE\fR at that location. +.PP +The \fBadd\fR command supports a subset of the options accepted by +\fB@IMAGEX_PROGNAME@-capture\fR; namely, \fB--dereference\fR, +\fB--unix-data\fR, \fB--no-acls\fR, and \fB--strict-acls\fR. See +\fB@IMAGEX_PROGNAME@-capture\fR (1) for explanations of these options. .SS \fBdelete\fR [\fIOPTION\fR...] \fIPATH\fR -Deletes a file or directory tree from a WIM image. \fIPATH\fR must specify the +Delete a file or directory tree from the WIM image. \fIPATH\fR must specify the path inside the WIM image of the file or directory tree to delete. - +.PP The available options for the \fBdelete\fR command are: - .TP 6 \fB--force\fR Do not issue an error if the path to delete does not exist. @@ -78,24 +49,20 @@ Do not issue an error if the path to delete does not exist. \fB--recursive\fR Delete the file or directory tree recursively; if not specified, an error is issued if the path to delete is a directory. - .SS \fBrename\fR \fIOLD_PATH\fR \fINEW_PATH\fR -Renames a file or directory tree inside a WIM image. \fIOLD_PATH\fR must +Rename a file or directory tree inside the WIM image. \fIOLD_PATH\fR must specify the old path of the file or directory tree inside the WIM image, and \fINEW_PATH\fR must specify the new path for the file or directory tree. This command follows the semantics of the POSIX \fBrename\fR (3) function; in particular, a pre-existing file at \fINEW_PATH\fR will be deleted if present, except in certain cases such as attempting to rename a directory to a non-directory, which is not allowed. - +.PP There are no options available for the \fBrename\fR command. - .SH OPTIONS - +The following options are accepted on the command line by \fB@IMAGEX_PROGNAME@ +update\fR itself: .TP 6 -\fB--verbose\fR -Use \fB--verbose\fR for all \fBadd\fR commands. -.TP \fB--dereference\fR Use \fB--dereference\fR for all \fBadd\fR commands. .TP @@ -121,8 +88,8 @@ Use \fB--recursive\fR for all \fBdelete\fR commands. \fB--check\fR When reading \fIWIMFILE\fR, verify its integrity if the integrity table is present; in addition, include an integrity table in the updated WIM. If this -option is not specified, no integrity table is included in the updated WIM, even -if there was one in the original WIM. +option is not specified, an integrity table will be included in the updated WIM +if and only if one was present before. .TP \fB--threads\fR=\fINUM_THREADS\fR Number of threads to use for compressing newly added files. Default: autodetect @@ -133,39 +100,70 @@ Rebuild the entire WIM rather than appending the updated 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--command\fR=\fISTRING\fR +Instead of reading update commands from standard input, read a single update +command directly from the string \fISTRING\fR specified on the command line. +This option cannot be provided more than one time and cannot be used to specify +more than one update command. Note that the \fISTRING\fR, as well as any +paths containing spaces within the \fISTRING\fR must be appropriately quoted. +If running from cmd.exe on Windows, you should use double quotes for the outer +quotes and single quotes for the inner quotes. Example: +.RS +.RS +.PP +.nf +@IMAGEX_PROGNAME@ update boot.wim 1 \\ +.br +.RS +--command="add 'C:\\My Dir' '\\My Dir'" +.RE +.RE +.RE +.fi .SH NOTES - \fB@IMAGEX_PROGNAME@ update\fR is partly redundant with \fB@IMAGEX_PROGNAME@ mountrw\fR, since if a WIM image can be mounted read-write, then there theoretically is no need for \fB@IMAGEX_PROGNAME@ update\fR. The main advantage -of \fB@IMAGEX_PROGNAME@ update\fR is that is works on both UNIX and Windows, -whereas \fB@IMAGEX_PROGNAME@ mountrw\fR only works on UNIX. - +of \fB@IMAGEX_PROGNAME@ update\fR is that it works on both UNIX-like systems and +Windows, whereas \fB@IMAGEX_PROGNAME@ mountrw\fR is only available on UNIX-like +systems, and even then it only works on those with a compatible FUSE +implementation. +.PP Symbolic links inside a WIM image are not dereferenced when being interpreted. So, for example, if you have a WIM image that contains a symbolic link "/Documents and Settings" -> "/Users" where "/Users" is a directory, then a subdirectory named "Public" in this directory must be specified as "/Users/Public" rather than "/Documents and Settings/Public". - +.PP +All paths to files or directories within the WIM image must be specified +relative to the root of the image. However, the leading slash is optional, and +both forward slashes and backslashes are accepted. In addition, on Windows, the +paths are by default treated case-insensitively, while on UNIX-like systems, the +paths are by default treated case-sensitively. The default case sensitivity may +be changed by setting the \fBWIMLIB_IMAGEX_IGNORE_CASE\fR environmental +variable to 0 or 1. +.PP The command file (\fICMDFILE\fR) is parsed by \fB@IMAGEX_PROGNAME@ update\fR itself and not by the system shell. Therefore, its syntax is limited. However, comment lines beginning with '#' are allowed, and it is also possible to quote arguments with whitespace inside them. - -On UNIX, you cannot use \fB@IMAGEX_PROGNAME@ update\fR to add files to an image -directly from a NTFS volume using libntfs-3g, even though \fB@IMAGEX_PROGNAME@ -capture\fR supports capturing a full image this way. - +.PP +On UNIX-like systems, you cannot use \fB@IMAGEX_PROGNAME@ update\fR to add files +to an image directly from a NTFS volume using libntfs-3g, even though +\fB@IMAGEX_PROGNAME@ capture\fR supports capturing a full image this way. +.PP It is safe to abort an \fB@IMAGEX_PROGNAME@ update\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. - +not yet incorporated into the structure of the WIM, unless \fB--rebuild\fR was +specified, in which case you should delete the temporary file left over. .SH EXAMPLES - +All the examples below show the update command file to be created as well as the +\fB@IMAGEX_PROGNAME@ update\fR command to run to perform the updates. +.PP Delete two files from a WIM image: - +.PP .RS \fIupdate_commands.txt\fR: .RS @@ -176,15 +174,16 @@ delete /sources/setup.exe .fi .RE .RE - +.PP .RS $ @IMAGEX_PROGNAME@ update boot.wim 2 < update_commands.txt .RE - -Add some files and directories to a WIM image; note that the first paths specify -the files to add, while the second paths specify the locations at which to to -add them \fIinside the WIM image\fR: - +.PP +Add some files and directories to a WIM image. Note that the first path of each +\fBadd\fR command specifies the files to add, while the second path of each +\fBadd\fR command specify the locations at which to to add them inside the WIM +image: +.PP .RS \fIupdate_commands.txt\fR: .RS @@ -195,13 +194,13 @@ add somefile /dir/file .fi .RE .RE - +.PP .RS $ @IMAGEX_PROGNAME@ update boot.wim 2 < update_commands.txt .RE - +.PP Rename a file inside a WIM image. - +.PP .RS \fIupdate_commands.txt\fR: .RS @@ -211,21 +210,21 @@ rename /dir_in_wim/oldfile.txt /dir_in_wim/newfile.txt .fi .RE .RE - +.PP .RS $ @IMAGEX_PROGNAME@ update boot.wim 2 < update_commands.txt .RE - +.PP Using additional features, such as comments, options, and overlays, and including an integrity table in the updated WIM: - +.PP .RS \fIupdate_commands.txt\fR: .RS .PP .nf # -# This file specifies some changes to make to my WIM image. +# This file specifies some changes to make to a WIM image. # # Add a new directory containing files I want in the image. @@ -247,11 +246,11 @@ delete --recursive /Users/Me/Documents/Junk .fi .RE .RE - +.PP .RS $ @IMAGEX_PROGNAME@ update boot.wim 2 --check < update_commands.txt .RE - +.PP .SH SEE ALSO .BR @IMAGEX_PROGNAME@ (1) .BR @IMAGEX_PROGNAME@-capture (1)