imagex_capture_or_append(): Correctly use template_wim
[wimlib] / doc / imagex-extract.1.in
1 .TH WIMLIB-IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
2 .SH NAME
3 @IMAGEX_PROGNAME@-extract \- Extract files or directories from a WIM image
4 .SH SYNOPSIS
5 \fB@IMAGEX_PROGNAME@ extract\fR \fIWIMFILE\fR \fIIMAGE\fR [\fIPATH\fR...]  [\fIOPTION\fR...]
6 .SH DESCRIPTION
7 \fB@IMAGEX_PROGNAME@ extract\fR extracts one or more files or directory trees
8 from the specified \fIIMAGE\fR contained in the Windows Imaging (WIM) file
9 \fIWIMFILE\fR.
10 This command is also available as simply \fBwimextract\fR if the appropriate hard
11 link or batch file has been installed.
12 .PP
13 \fB@IMAGEX_PROGNAME@ extract\fR is intended for extracting only a subset of a
14 WIM image.  If you want to extract or "apply" a full WIM image to a directory or
15 NTFS volume, use \fB@IMAGEX_PROGNAME@ apply\fR (1) instead.
16 .PP
17 \fIIMAGE\fR specifies the image in \fIWIMFILE\fR that contains the files or
18 directory trees to extract.  It may be a 1-based index of an image in the WIM or
19 the name of an image in the WIM.  Use the \fB@IMAGEX_PROGNAME@ info\fR (1)
20 command to show what images a WIM file contains.
21 .PP
22 Each \fIPATH\fR specifies a file or directory tree within the WIM image to
23 extract.  See \fBPATH_SPECIFICATIONS\fR.
24 .PP
25 By default, files and directories are extracted to the current directory.  Use
26 \fB--dest-dir\fR to choose an alternate target directory.  Alternatively, use
27 \fB--to-stdout\fR to extract a file to standard output to pipe into another
28 program.
29 .PP
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 .SH PATH SPECIFICATIONS
33 Each \fIPATH\fR specifies a file or directory tree within the WIM image to
34 extract.  Each path must be specified as an absolute path starting from the root
35 of the WIM image, like those output by the \fB@IMAGEX_PROGNAME@ dir\fR (1)
36 command.  However, path separators may be either forward or backward slashes,
37 and the leading slash is optional; also, on Windows, the paths are treated
38 case-insensitively, while on UNIX, paths are treated case-sensitively.
39 .PP
40 If no \fIPATH\fRs are provided, the default behavior is to extract the full
41 image, as if the path "/" had been provided.
42 .SH SPLIT WIMS
43 You may use \fB@IMAGEX_PROGNAME@ extract\fR to extract files or directory trees
44 from a split WIM.  This uses the \fB--refs\fR="\fIGLOB\fR" option in the same
45 way as in other commands such as \fB@IMAGEX_PROGNAME@ apply\fR.  See
46 \fB@IMAGEX_PROGNAME@ apply\fR (1) for more details.
47 .SH OPTIONS
48 .TP 6
49 \fB--check\fR
50 When reading \fIWIMFILE\fR, verify its integrity if an integrity table is
51 present.
52 .TP
53 \fB--ref\fR="\fIGLOB\fR"
54 File glob of additional WIMs or split WIM parts to reference resources from.
55 See \fBSPLIT_WIMS\fR.  Note: since \fIGLOB\fR is listed in quotes because it is
56 interpreted by \fB@IMAGEX_PROGNAME@\fR and may need to be quoted to protect
57 against shell expansion.
58 .TP
59 \fB--verbose\fR
60 This option no longer does anything but is reserved for future use.
61 .TP
62 \fB--unix-data\fR
63 See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
64 .TP
65 \fB--no-acls\fR
66 See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
67 .TP
68 \fB--strict-acls\fR
69 See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
70 .TP
71 \fB--include-invalid-names\fR
72 See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
73 .TP
74 \fB--to-stdout\fR
75 Extract the files to standard output instead of to the filesystem.  This can
76 only be provided if all the specified \fIPATH\fRs are to regular files (not
77 directories or reparse points).  If present, alternate data streams are not
78 extracted.
79 .TP
80 \fB--dest-dir\fR=\fIDIR\fR
81 Extract the files and directories to the directory \fIDIR\fR instead of to the
82 current working directory.
83 .SH NOTES
84 See the documentation \fB@IMAGEX_PROGNAME@ apply\fR (1) for documentation about
85 what data and metadata are extracted on UNIX-like systems versus on Windows.
86 .PP
87 On UNIX-like systems that support userspace filesystems with FUSE (e.g. Linux),
88 one can alternatively mount the WIM image with \fB@IMAGEX_PROGNAME@ mount\fR (1)
89 and then extract the desired files or directories using any standard
90 command-line or graphical program.
91 .PP
92 Reparse-point fixups (a.k.a. changing absolute symbolic links and junctions 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 .PP
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 .SH EXAMPLES
99 Extract a file from the first image in "boot.wim" to the current directory:
100 .RS
101 .PP
102 @IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/System32/notepad.exe
103 .RE
104 .PP
105 Extract a file from the first image in "boot.wim" to standard output:
106 .RS
107 .PP
108 @IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/System32/notepad.exe \\
109 .br
110 .RS
111 --to-stdout
112 .RE
113 .RE
114 .PP
115 Extract a file from the first image in "boot.wim" to the specified directory:
116 .RS
117 .PP
118 @IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/System32/notepad.exe \\
119 .br
120 .RS
121 --dest-dir=somedir
122 .RE
123 .RE
124 .PP
125 Extract the "sources" directory from the first image in "boot.wim" to the
126 current directory:
127 .RS
128 .PP
129 @IMAGEX_PROGNAME@ extract boot.wim 1 /sources
130 .RE
131 .PP
132 Extract multiple files and directories in one command:
133 .RS
134 .PP
135 @IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/Fonts \\
136 .br
137 .RS
138 /sources /Windows/System32/cmd.exe
139 .RE
140 .RE
141 .PP
142 .SH SEE ALSO
143 .BR @IMAGEX_PROGNAME@ (1)
144 .BR @IMAGEX_PROGNAME@-apply (1)
145 .BR @IMAGEX_PROGNAME@-dir (1)
146 .BR @IMAGEX_PROGNAME@-info (1)
147 .BR @IMAGEX_PROGNAME@-mount (1)