ce1e8e4fa598d08f937faabb0a1ac6809ff4dfa1
[wimlib] / 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.
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.
71 .TP
72 \fB--strict-acls\fR
73 Fail immediately if the full security descriptor of any file or directory cannot
74 be set exactly as specified in the WIM file.  The default behavior without this
75 option is to fall back to setting a security descriptor with the SACL omitted,
76 then only the default inherited security descriptor, if we do not have
77 permission to set the desired one.
78 .TP
79 \fB--to-stdout\fR
80 Extract the files to standard output instead of to the filesystem.  This can
81 only be provided if all the specified \fIPATH\fRs are to regular files (not
82 directories or reparse points).  If present, alternate data streams are not
83 extracted.
84
85 .SH NOTES
86
87 \fB@IMAGEX_PROGNAME@ extract\fR calculates the SHA1 message digest of every file
88 stream it extracts and verifies that it is the same as the SHA1 message digest
89 provided in the WIM file.  Thus, it should provide assurance of data integrity.
90
91 Reparse-point fixups (a.k.a. changing absolute symbolic links and junctions to
92 point within the extraction location) are never done by \fB@IMAGEX_PROGNAME@
93 extract\fR.  Use \fB@IMAGEX_PROGNAME@ apply\fR if you want this behavior.
94
95 Unlike \fB@IMAGEX_PROGNAME@ apply\fR, \fB@IMAGEX_PROGNAME@ extract\fR does not
96 support extracting files directly to a NTFS volume using libntfs-3g.
97
98 Not all data and metadata contained in each WIM \fIPATH\fR will necessarily be
99 extracted, since \fB@IMAGEX_PROGNAME@ extract\fR does the best it can given the
100 platform (UNIX or Windows) and supported features of the filesystem.  The
101 documentation for \fB@IMAGEX_PROGNAME@ apply\fR (1) goes into more detail about
102 what data and metadata is extracted and what is not.
103
104 .SH EXAMPLES
105 Extract a file from the first image in "boot.wim" to the current directory:
106 .RS
107 .PP
108 @IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/System32/notepad.exe
109 .RE
110 .PP
111 Extract a file from the first image in "boot.wim" to standard output:
112 .RS
113 .PP
114 @IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/System32/notepad.exe --to-stdout
115 .RE
116 .PP
117 Extract a file from the first image in "boot.wim" to the specified directory:
118 .RS
119 .PP
120 @IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/System32/notepad.exe --dest-dir=somedir
121 .RE
122 .PP
123 Extract the "sources" directory from the first image in "boot.wim" to the
124 current directory:
125 .RS
126 .PP
127 @IMAGEX_PROGNAME@ extract boot.wim 1 /sources
128 .RE
129 .PP
130 Extract multiple files and directories in one command:
131 .RS
132 .PP
133 @IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/Fonts /sources /Windows/System32/cmd.exe
134 .RE
135 .PP
136
137 .SH SEE ALSO
138 .BR @IMAGEX_PROGNAME@ (1)
139 .BR @IMAGEX_PROGNAME@-apply (1)
140 .BR @IMAGEX_PROGNAME@-dir (1)
141 .BR @IMAGEX_PROGNAME@-info (1)