wimlib.net Git - wimlib/blob - doc/imagex-extract.1.in

   1 .TH IMAGEX "1" "April 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
   2 .SH NAME
   3 @IMAGEX_PROGNAME@-extract \- Extract files or directories from a WIM image
   4
   5 .SH SYNOPSIS
   6 \fB@IMAGEX_PROGNAME@ extract\fR \fIWIMFILE\fR \fIIMAGE\fR \fI[PATH\fR]... [\fIOPTION\fR]...
   7
   8 .SH DESCRIPTION
   9 .PP
  10
  11 \fB@IMAGEX_PROGNAME@ extract\fR extracts one or more files or directory trees
  12 from the specified \fIIMAGE\fR contained in the Windows Imaging (WIM) file
  13 \fIWIMFILE\fR.
  14
  15 \fB@IMAGEX_PROGNAME@ extract\fR is intended for extracting only a subset of a
  16 WIM image.  If you want to extract or "apply" a full WIM image to a directory or
  17 NTFS volume, use \fB@IMAGEX_PROGNAME@ apply\fR (1) instead.
  18
  19 \fIIMAGE\fR specifies the image in \fIWIMFILE\fR that contains the files or
  20 directory trees to extract.  It may be a 1-based index of an image in the WIM or
  21 the name of an image in the WIM.  Use the \fB@IMAGEX_PROGNAME@ info\fR (1)
  22 command to show what images a WIM file contains.
  23
  24 Each \fIPATH\fR specifies a file or directory tree within the WIM image to
  25 extract.  See \fBPATH_SPECIFICATIONS\fR.
  26
  27 By default, files and directories are extracted to the current directory.  Use
  28 \fB--dest-dir\fR to choose an alternate target directory.
  29
  30 \fB@IMAGEX_PROGNAME@ extract\fR supports extracting files and directory trees
  31 from stand-alone WIMs as well as split WIMs.  See \fBSPLIT WIMS\fR.
  32
  33 .SH PATH SPECIFICATIONS
  34
  35 Each \fIPATH\fR specifies a file or directory tree within the WIM image to
  36 extract.  Each path must be specified as an absolute path starting from the root
  37 of the WIM image, like those output by the \fB@IMAGEX_PROGNAME@ dir\fR (1)
  38 command.  Path separators may be forward slashes on UNIX, or either forward
  39 slashes or backward slashes on Windows.  The leading slash is optional.
  40
  41 If no \fIPATH\fRs are provided, the default behavior is to extract the full
  42 image, as if the path "/" had been provided.
  43
  44 .SH SPLIT WIMS
  45
  46 You may use \fB@IMAGEX_PROGNAME@ extract\fR to extract files or directory trees
  47 from a split WIM.  This uses the \fB--refs\fR="\fIGLOB\fR" option in the same
  48 way as in other commands such as \fB@IMAGEX_PROGNAME@ apply\fR.  See
  49 \fB@IMAGEX_PROGNAME@ apply\fR (1) for more details.
  50
  51 .SH OPTIONS
  52 .TP 6
  53 \fB--check\fR
  54 When reading \fIWIMFILE\fR, verify its integrity if the integrity table is
  55 present.
  56 .TP
  57 \fB--verbose\fR
  58 Print the path to of each file or directory within the WIM image as it is
  59 extracted, and some additional informational messages.
  60 .TP
  61 \fB--ref\fR="\fIGLOB\fR"
  62 File glob of additional split WIM parts that are part of the split WIM.  See
  63 \fBSPLIT_WIMS\fR.
  64 .TP
  65 \fB--unix-data\fR
  66 Restore the UNIX-specific data captured using \fB@IMAGEX_PROGNAME@ capture\fR
  67 with the \fB--unix-data\fR option.  This option is only available on UNIX.
  68 .TP
  69 \fB--no-acls\fR
  70 Do not restore security descriptors on extracted files and directories.  This
  71 option is only available on Windows.
  72 .TP
  73 \fB--strict-acls\fR
  74 Fail immediately if the full security descriptor of any file or directory cannot
  75 be set exactly as specified in the WIM file.  The default behavior without this
  76 option is to fall back to setting a security descriptor with the SACL omitted,
  77 then only the default inherited security descriptor, if we do not have
  78 permission to set the desired one.  This option is only available on Windows.
  79 .TP
  80 \fB--to-stdout\fR
  81 Extract the files to standard output instead of to the filesystem.  This can
  82 only be provided if all the specified \fIPATH\fRs are to regular files (not
  83 directories or reparse points).  If present, alternate data streams are not
  84 extracted.
  85
  86 .SH NOTES
  87
  88 \fB@IMAGEX_PROGNAME@ extract\fR calculates the SHA1 message digest of every file
  89 stream it extracts and verifies that it is the same as the SHA1 message digest
  90 provided in the WIM file.  Thus, it should provide assurance of data integrity.
  91
  92 Reparse-point fixups (a.k.a. changing absolute symbolic links and junction to
  93 point within the extraction location) are never done by \fB@IMAGEX_PROGNAME@
  94 extract\fR.  Use \fB@IMAGEX_PROGNAME@ apply\fR if you want this behavior.
  95
  96 Unlike \fB@IMAGEX_PROGNAME@ apply\fR, \fB@IMAGEX_PROGNAME@ extract\fR does not
  97 support extracting files directly to a NTFS volume using libntfs-3g.
  98
  99 Not all data and metadata containing in each WIM \fIPATH\fR will necessarily be
 100 extracted, since \fB@IMAGEX_PROGNAME@ extract\fR does the best it can given the
 101 platform (UNIX or Windows) and supported features of the filesystem.  The
 102 documentation for \fB@IMAGEX_PROGNAME@ apply\fR (1) goes into more detail about
 103 what data and metadata is extracted and what is not.
 104
 105 .SH EXAMPLES
 106 Extract a file from the first image in "boot.wim" to the current directory:
 107 .RS
 108 .PP
 109 @IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/System32/notepad.exe
 110 .RE
 111 .PP
 112 Extract a file from the first image in "boot.wim" to standard output:
 113 .RS
 114 .PP
 115 @IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/System32/notepad.exe --to-stdout
 116 .RE
 117 .PP
 118 Extract a file from the first image in "boot.wim" to the specified directory:
 119 .RS
 120 .PP
 121 @IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/System32/notepad.exe --dest-dir=somedir
 122 .RE
 123 .PP
 124 Extract the "sources" directory from the first image in "boot.wim" to the
 125 current directory:
 126 .RS
 127 .PP
 128 @IMAGEX_PROGNAME@ extract boot.wim 1 /sources
 129 .RE
 130 .PP
 131 Extract multiple files and directories in one command:
 132 .RS
 133 .PP
 134 @IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/Fonts /sources /Windows/System32/cmd.exe
 135 .RE
 136 .PP
 137
 138 .SH SEE ALSO
 139 .BR @IMAGEX_PROGNAME@ (1)
 140 .BR @IMAGEX_PROGNAME@-apply (1)
 141 .BR @IMAGEX_PROGNAME@-dir (1)
 142 .BR @IMAGEX_PROGNAME@-info (1)