]> wimlib.net Git - wimlib/blobdiff - doc/imagex-extract.1.in
imagex-extract.1.in: Add example for wildcard path
[wimlib] / doc / imagex-extract.1.in
index 33bf9f7e3bd30cda020691a8672eb34c07eb0466..a7dfd0758d01057f2d2ee5788fc4f2413a33d553 100644 (file)
@@ -2,9 +2,7 @@
 .SH NAME
 @IMAGEX_PROGNAME@-extract \- Extract files or directories from a WIM image
 .SH SYNOPSIS
 .SH NAME
 @IMAGEX_PROGNAME@-extract \- Extract files or directories from a WIM image
 .SH SYNOPSIS
-\fB@IMAGEX_PROGNAME@ extract\fR \fIWIMFILE\fR \fIIMAGE\fR [\fIPATH\fR...]  [\fIOPTION\fR...]
-.br
-\fB@IMAGEX_PROGNAME@ extract\fR \fIWIMFILE\fR \fIIMAGE\fR @\fILISTFILE\fR  [\fIOPTION\fR...]
+\fB@IMAGEX_PROGNAME@ extract\fR \fIWIMFILE\fR \fIIMAGE\fR [(\fIPATH\fR | @\fILISTFILE\fR)...]  [\fIOPTION\fR...]
 .SH DESCRIPTION
 \fB@IMAGEX_PROGNAME@ extract\fR extracts one or more files or directory trees
 from the specified \fIIMAGE\fR contained in the Windows Imaging (WIM) file
 .SH DESCRIPTION
 \fB@IMAGEX_PROGNAME@ extract\fR extracts one or more files or directory trees
 from the specified \fIIMAGE\fR contained in the Windows Imaging (WIM) file
@@ -21,46 +19,66 @@ directory trees to extract.  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 show what images a WIM file contains.
 .PP
 the name of an image in the WIM.  Use the \fB@IMAGEX_PROGNAME@ info\fR (1)
 command to show what images a WIM file contains.
 .PP
-Each \fIPATH\fR specifies a file or directory tree within the WIM image to
-extract.  Alternatively, a single \fILISTFILE\fR beginning with the '@'
-character is taken as a file that itself contains a list of files or directory
-trees to extract.  See \fBPATH_SPECIFICATIONS\fR.
+If no additional arguments are given, the entire WIM image is extracted.
+Otherwise, each additional argument is interpreted as a \fIPATH\fR if it does
+not begin with the '@' character, or a \fILISTFILE\fR if it does.  Each
+\fIPATH\fR specifies a file or directory tree within the WIM image to extract,
+whereas each \fILISTFILE\fR specifies a file that itself contains a list of
+paths to extract.  See \fBPATHS AND LISTFILES\fR for more details.
 .PP
 By default, files and directories are extracted to the current directory.  Use
 .PP
 By default, files and directories are extracted to the current directory.  Use
-\fB--dest-dir\fR to choose an alternate target directory.  Alternatively, use
-\fB--to-stdout\fR to extract a file to standard output to pipe into another
+\fB--dest-dir\fR to select a different destination directory.  Alternatively,
+use \fB--to-stdout\fR to extract a file to standard output to pipe into another
 program.
 .PP
 program.
 .PP
+A file or directory extracted from a \fIPATH\fR argument is by default extracted
+directly into the destination directory, whereas a file or directory extracted
+from a \fILISTFILE\fR argument is by default extracted into the destination
+directory in such a way that the archive's directory structure is
+preserved.  Use \fB--preserve-dir-structure\fR to always get the latter
+behavior.
+.PP
 \fB@IMAGEX_PROGNAME@ extract\fR supports extracting files and directory trees
 from stand-alone WIMs as well as split WIMs.  See \fBSPLIT WIMS\fR.
 \fB@IMAGEX_PROGNAME@ extract\fR supports extracting files and directory trees
 from stand-alone WIMs as well as split WIMs.  See \fBSPLIT WIMS\fR.
-.SH PATH SPECIFICATIONS
-Except when a single path is specified and prefixd by the '@' character, each
-\fIPATH\fR specifies a file or directory tree within the WIM image to extract.
-Each such path must be specified as an absolute path starting from the root of
-the WIM image, like those output by the \fB@IMAGEX_PROGNAME@ dir\fR (1) command.
-However, path separators may be either forward or backward slashes, and the
-leading slash is optional; also, on Windows, the paths are treated
-case-insensitively, while on UNIX, paths are treated case-sensitively, except
-when overwritten through the \fBWIMLIB_IMAGEX_IGNORE_CASE\fR environmental
-variable, as documented in \fB@IMAGEX_PROGNAME@\fR (1).
-.PP
-If no \fIPATH\fRs are provided, the default behavior is to extract the full
-image, as if the path "/" had been provided.
-.PP
-If a single \fIPATH\fR is provided and is prefixed with the '@' character, it is
-interpreted as the path to a \fILISTFILE\fR which must be a UTF-8 text file that
-contains a list of paths (files or directories) to extract, one per line.  In
-each line, leading and trailing whitespace is ignored, and lines beginning with
-the ';' character and otherwise empty lines are ignored.  Each path must be
-unquoted and must specify a full path in the WIM image, as described above.
-However, unless \fB--no-wildcards\fR is specified, each path in the list file
-may also contain the wildcard characters '?' and '*', and therefore may expand
-to multiple actual files or directories.  By default, a path or wildcard glob
-that matches no files or directories in the WIM image only produces a warning;
-use \fB--strict-wildcards\fR if you want an error instead.  Also, when using a
-list file, files and directories not located at the root of the WIM image will
-be extracted to a corresponding subdirectory of the destination directory rather
-than directly to the destination directory itself.
+.SH PATHS AND LISTFILES
+Each path, including those on the command line and those in listfiles, must be
+specified as an absolute path starting from the root of the WIM image, like
+those output by the \fB@IMAGEX_PROGNAME@ dir\fR (1) command.  However, path
+separators may be either forward or backward slashes, and the leading slash is
+optional.
+.PP
+On Windows, by default paths are treated case-insensitively, whereas on
+UNIX-like systems, by default paths are treated case-sensitively.  In either
+case, the default behavior may be overridden through the
+\fBWIMLIB_IMAGEX_IGNORE_CASE\fR environmental variable, as documented in
+\fB@IMAGEX_PROGNAME@\fR (1).
+.PP
+By default, each path may contain the wildcard characters '?' and '*'.  The '?'
+character matches any non-path-separator character, whereas the '*' character
+matches zero or more non-path-separator characters.  Consequently, a single
+wildcard pattern may expand to multiple actual files or directories.  Use the
+\fB--no-wildcards\fR option to disable wildcard matching and search for each
+path literally.
+.PP
+Each \fILISTFILE\fR must be a UTF-8 text file that contains a list of paths to
+extract, one per line.  Wildcard characters are allowed by default.  The
+following demonstrates an example listfile:
+.PP
+.RS
+.nf
+
+; This is a comment (begins with semicolon)
+/Users
+/Windows/explorer.exe
+/Windows/System32/en-US/*
+
+; Both forward and backslashes are valid.
+; Don't quote paths containing spaces.
+\\Program Files\\A*
+
+; Leading and trailing whitespace is ignored
+    \\Windows\\notepad*
+
 .SH SPLIT WIMS
 You may use \fB@IMAGEX_PROGNAME@ extract\fR to extract files or directory trees
 from a split WIM.  This uses the \fB--refs\fR="\fIGLOB\fR" option in the same
 .SH SPLIT WIMS
 You may use \fB@IMAGEX_PROGNAME@ extract\fR to extract files or directory trees
 from a split WIM.  This uses the \fB--refs\fR="\fIGLOB\fR" option in the same
@@ -78,6 +96,16 @@ See \fBSPLIT_WIMS\fR.  Note: \fIGLOB\fR is listed in quotes because it is
 interpreted by \fB@IMAGEX_PROGNAME@\fR and may need to be quoted to protect
 against shell expansion.
 .TP
 interpreted by \fB@IMAGEX_PROGNAME@\fR and may need to be quoted to protect
 against shell expansion.
 .TP
+\fB--dest-dir\fR=\fIDIR\fR
+Extract the files and directories to the directory \fIDIR\fR instead of to the
+current working directory.
+.TP
+\fB--to-stdout\fR
+Extract the files to standard output instead of to the filesystem.  This can
+only be provided if all the specified paths are to regular files (not
+directories or reparse points).  If present, alternate data streams are not
+extracted.
+.TP
 \fB--unix-data\fR
 See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
 .TP
 \fB--unix-data\fR
 See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
 .TP
@@ -87,25 +115,31 @@ See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
 \fB--strict-acls\fR
 See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
 .TP
 \fB--strict-acls\fR
 See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
 .TP
-\fB--include-invalid-names\fR
+\fB--no-attributes\fR
 See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
 .TP
 See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
 .TP
-\fB--to-stdout\fR
-Extract the files to standard output instead of to the filesystem.  This can
-only be provided if all the specified \fIPATH\fRs are to regular files (not
-directories or reparse points).  If present, alternate data streams are not
-extracted.
-.TP
-\fB--dest-dir\fR=\fIDIR\fR
-Extract the files and directories to the directory \fIDIR\fR instead of to the
-current working directory.
+\fB--include-invalid-names\fR
+See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
 .TP
 \fB--no-wildcards\fR
 .TP
 \fB--no-wildcards\fR
-Do not interpret wildcard characters in paths in the \fILISTFILE\fR.
+Do not interpret wildcard characters in paths.  Each path will be searched for
+literally.
 .TP
 .TP
-\fB--strict-wildcards\fR
-Fail if any wildcards or paths in \fILISTFILE\fR do not match any files in the
-WIM image.  The default behavior is to warn only.
+\fB--nullglob\fR
+If a wildcard pattern (a.k.a. a "glob") does not match any paths, ignore it and
+print a warning instead of failing with an error.  In other words, this option
+allows a wildcard pattern to successfully match zero files.  Note that this
+applies even if one of the paths does not contain wildcard characters.  Such a
+path is still treated as a "wildcard pattern", so with this option it may not
+match anything and therefore produce no error.  This option cannot be combined
+with \fB--no-wildcards\fR, as that would be meaningless.
+.TP
+\fB--preserve-dir-structure\fR
+When extracting paths, preserve the archive directory structure instead of
+extracting the file or directory tree named by each path directly to the
+destination directory.  Note: \fB--preserve-dir-structure\fR is already the
+default behavior for paths in listfiles, but not paths directly specified on the
+command line.
 .SH NOTES
 See the documentation \fB@IMAGEX_PROGNAME@ apply\fR (1) for documentation about
 what data and metadata are extracted on UNIX-like systems versus on Windows.
 .SH NOTES
 See the documentation \fB@IMAGEX_PROGNAME@ apply\fR (1) for documentation about
 what data and metadata are extracted on UNIX-like systems versus on Windows.
@@ -172,6 +206,12 @@ Extract multiple files and directories in one command:
 .RE
 .RE
 .PP
 .RE
 .RE
 .PP
+Extract many files to the current directory using a wildcard pattern:
+.RS
+.PP
+@IMAGEX_PROGNAME@ extract install.wim 1 "/Windows/Fonts/*.ttf"
+.RE
+.PP
 Extract files using a list file:
 .RS
 .PP
 Extract files using a list file:
 .RS
 .PP