| blob | ee82a7f35a03d09a2c54f9c65d237e51bfe273af |
1 '\" t
2 .\" Title: git-archive
3 .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
5 .\" Date: 04/25/2023
6 .\" Manual: Git Manual
7 .\" Source: Git 2.40.1.423.g2807bd2c10
8 .\" Language: English
9 .\"
10 .TH "GIT\-ARCHIVE" "1" "04/25/2023" "Git 2\&.40\&.1\&.423\&.g2807bd" "Git Manual"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 git-archive \- Create an archive of files from a named tree
32 .SH "SYNOPSIS"
33 .sp
34 .nf
35 \fIgit archive\fR [\-\-format=<fmt>] [\-\-list] [\-\-prefix=<prefix>/] [<extra>]
36 [\-o <file> | \-\-output=<file>] [\-\-worktree\-attributes]
37 [\-\-remote=<repo> [\-\-exec=<git\-upload\-archive>]] <tree\-ish>
38 [<path>\&...]
39 .fi
40 .sp
41 .SH "DESCRIPTION"
42 .sp
43 Creates an archive of the specified format containing the tree structure for the named tree, and writes it out to the standard output\&. If <prefix> is specified it is prepended to the filenames in the archive\&.
44 .sp
45 \fIgit archive\fR behaves differently when given a tree ID versus when given a commit ID or tag ID\&. In the first case the current time is used as the modification time of each file in the archive\&. In the latter case the commit time as recorded in the referenced commit object is used instead\&. Additionally the commit ID is stored in a global extended pax header if the tar format is used; it can be extracted using \fIgit get\-tar\-commit\-id\fR\&. In ZIP files it is stored as a file comment\&.
46 .SH "OPTIONS"
47 .PP
48 \-\-format=<fmt>
49 .RS 4
50 Format of the resulting archive\&. Possible values are
51 \fBtar\fR,
52 \fBzip\fR,
53 \fBtar\&.gz\fR,
54 \fBtgz\fR, and any format defined using the configuration option
55 \fBtar\&.<format>\&.command\fR\&. If
56 \fB\-\-format\fR
57 is not given, and the output file is specified, the format is inferred from the filename if possible (e\&.g\&. writing to
58 \fBfoo\&.zip\fR
59 makes the output to be in the
60 \fBzip\fR
61 format)\&. Otherwise the output format is
62 \fBtar\fR\&.
63 .RE
64 .PP
65 \-l, \-\-list
66 .RS 4
67 Show all available formats\&.
68 .RE
69 .PP
70 \-v, \-\-verbose
71 .RS 4
72 Report progress to stderr\&.
73 .RE
74 .PP
75 \-\-prefix=<prefix>/
76 .RS 4
77 Prepend <prefix>/ to paths in the archive\&. Can be repeated; its rightmost value is used for all tracked files\&. See below which value gets used by
78 \fB\-\-add\-file\fR
79 and
80 \fB\-\-add\-virtual\-file\fR\&.
81 .RE
82 .PP
83 \-o <file>, \-\-output=<file>
84 .RS 4
85 Write the archive to <file> instead of stdout\&.
86 .RE
87 .PP
88 \-\-add\-file=<file>
89 .RS 4
90 Add a non\-tracked file to the archive\&. Can be repeated to add multiple files\&. The path of the file in the archive is built by concatenating the value of the last
91 \fB\-\-prefix\fR
92 option (if any) before this
93 \fB\-\-add\-file\fR
94 and the basename of <file>\&.
95 .RE
96 .PP
97 \-\-add\-virtual\-file=<path>:<content>
98 .RS 4
99 Add the specified contents to the archive\&. Can be repeated to add multiple files\&. The path of the file in the archive is built by concatenating the value of the last
100 \fB\-\-prefix\fR
101 option (if any) before this
102 \fB\-\-add\-virtual\-file\fR
103 and
104 \fB<path>\fR\&.
105 .sp
106 The
107 \fB<path>\fR
108 argument can start and end with a literal double\-quote character; the contained file name is interpreted as a C\-style string, i\&.e\&. the backslash is interpreted as escape character\&. The path must be quoted if it contains a colon, to avoid the colon from being misinterpreted as the separator between the path and the contents, or if the path begins or ends with a double\-quote character\&.
109 .sp
110 The file mode is limited to a regular file, and the option may be subject to platform\-dependent command\-line limits\&. For non\-trivial cases, write an untracked file and use
111 \fB\-\-add\-file\fR
112 instead\&.
113 .RE
114 .PP
115 \-\-worktree\-attributes
116 .RS 4
117 Look for attributes in \&.gitattributes files in the working tree as well (see
118 the section called \(lqATTRIBUTES\(rq)\&.
119 .RE
120 .PP
121 \-\-mtime=<time>
122 .RS 4
123 Set modification time of archive entries\&. Without this option the committer time is used if
124 \fB<tree\-ish>\fR
125 is a commit or tag, and the current time if it is a tree\&.
126 .RE
127 .PP
128 <extra>
129 .RS 4
130 This can be any options that the archiver backend understands\&. See next section\&.
131 .RE
132 .PP
133 \-\-remote=<repo>
134 .RS 4
135 Instead of making a tar archive from the local repository, retrieve a tar archive from a remote repository\&. Note that the remote repository may place restrictions on which sha1 expressions may be allowed in
136 \fB<tree\-ish>\fR\&. See
137 \fBgit-upload-archive\fR(1)
138 for details\&.
139 .RE
140 .PP
141 \-\-exec=<git\-upload\-archive>
142 .RS 4
143 Used with \-\-remote to specify the path to the
144 \fIgit\-upload\-archive\fR
145 on the remote side\&.
146 .RE
147 .PP
148 <tree\-ish>
149 .RS 4
150 The tree or commit to produce an archive for\&.
151 .RE
152 .PP
153 <path>
154 .RS 4
155 Without an optional path parameter, all files and subdirectories of the current working directory are included in the archive\&. If one or more paths are specified, only these are included\&.
156 .RE
157 .SH "BACKEND EXTRA OPTIONS"
158 .SS "zip"
159 .PP
160 \-<digit>
161 .RS 4
162 Specify compression level\&. Larger values allow the command to spend more time to compress to smaller size\&. Supported values are from
163 \fB\-0\fR
164 (store\-only) to
165 \fB\-9\fR
166 (best ratio)\&. Default is
167 \fB\-6\fR
168 if not given\&.
169 .RE
170 .SS "tar"
171 .PP
172 \-<number>
173 .RS 4
174 Specify compression level\&. The value will be passed to the compression command configured in
175 \fBtar\&.<format>\&.command\fR\&. See manual page of the configured command for the list of supported levels and the default level if this option isn\(cqt specified\&.
176 .RE
177 .SH "CONFIGURATION"
178 .PP
179 tar\&.umask
180 .RS 4
181 This variable can be used to restrict the permission bits of tar archive entries\&. The default is 0002, which turns off the world write bit\&. The special value "user" indicates that the archiving user\(cqs umask will be used instead\&. See umask(2) for details\&. If
182 \fB\-\-remote\fR
183 is used then only the configuration of the remote repository takes effect\&.
184 .RE
185 .PP
186 tar\&.<format>\&.command
187 .RS 4
188 This variable specifies a shell command through which the tar output generated by
189 \fBgit archive\fR
190 should be piped\&. The command is executed using the shell with the generated tar file on its standard input, and should produce the final output on its standard output\&. Any compression\-level options will be passed to the command (e\&.g\&.,
191 \fB\-9\fR)\&.
192 .sp
193 The
194 \fBtar\&.gz\fR
195 and
196 \fBtgz\fR
197 formats are defined automatically and use the magic command
198 \fBgit archive gzip\fR
199 by default, which invokes an internal implementation of gzip\&.
200 .RE
201 .PP
202 tar\&.<format>\&.remote
203 .RS 4
204 If true, enable the format for use by remote clients via
205 \fBgit-upload-archive\fR(1)\&. Defaults to false for user\-defined formats, but true for the
206 \fBtar\&.gz\fR
207 and
208 \fBtgz\fR
209 formats\&.
210 .RE
211 .SH "ATTRIBUTES"
212 .PP
213 export\-ignore
214 .RS 4
215 Files and directories with the attribute export\-ignore won\(cqt be added to archive files\&. See
216 \fBgitattributes\fR(5)
217 for details\&.
218 .RE
219 .PP
220 export\-subst
221 .RS 4
222 If the attribute export\-subst is set for a file then Git will expand several placeholders when adding this file to an archive\&. See
223 \fBgitattributes\fR(5)
224 for details\&.
225 .RE
226 .sp
227 Note that attributes are by default taken from the \fB\&.gitattributes\fR files in the tree that is being archived\&. If you want to tweak the way the output is generated after the fact (e\&.g\&. you committed without adding an appropriate export\-ignore in its \fB\&.gitattributes\fR), adjust the checked out \fB\&.gitattributes\fR file as necessary and use \fB\-\-worktree\-attributes\fR option\&. Alternatively you can keep necessary attributes that should apply while archiving any tree in your \fB$GIT_DIR/info/attributes\fR file\&.
228 .SH "EXAMPLES"
229 .PP
230 \fBgit archive \-\-format=tar \-\-prefix=junk/ HEAD | (cd /var/tmp/ && tar xf \-)\fR
231 .RS 4
232 Create a tar archive that contains the contents of the latest commit on the current branch, and extract it in the
233 \fB/var/tmp/junk\fR
234 directory\&.
235 .RE
236 .PP
237 \fBgit archive \-\-format=tar \-\-prefix=git\-1\&.4\&.0/ v1\&.4\&.0 | gzip >git\-1\&.4\&.0\&.tar\&.gz\fR
238 .RS 4
239 Create a compressed tarball for v1\&.4\&.0 release\&.
240 .RE
241 .PP
242 \fBgit archive \-\-format=tar\&.gz \-\-prefix=git\-1\&.4\&.0/ v1\&.4\&.0 >git\-1\&.4\&.0\&.tar\&.gz\fR
243 .RS 4
244 Same as above, but using the builtin tar\&.gz handling\&.
245 .RE
246 .PP
247 \fBgit archive \-\-prefix=git\-1\&.4\&.0/ \-o git\-1\&.4\&.0\&.tar\&.gz v1\&.4\&.0\fR
248 .RS 4
249 Same as above, but the format is inferred from the output file\&.
250 .RE
251 .PP
252 \fBgit archive \-\-format=tar \-\-prefix=git\-1\&.4\&.0/ v1\&.4\&.0^{tree} | gzip >git\-1\&.4\&.0\&.tar\&.gz\fR
253 .RS 4
254 Create a compressed tarball for v1\&.4\&.0 release, but without a global extended pax header\&.
255 .RE
256 .PP
257 \fBgit archive \-\-format=zip \-\-prefix=git\-docs/ HEAD:Documentation/ > git\-1\&.4\&.0\-docs\&.zip\fR
258 .RS 4
259 Put everything in the current head\(cqs Documentation/ directory into
260 \fIgit\-1\&.4\&.0\-docs\&.zip\fR, with the prefix
261 \fIgit\-docs/\fR\&.
262 .RE
263 .PP
264 \fBgit archive \-o latest\&.zip HEAD\fR
265 .RS 4
266 Create a Zip archive that contains the contents of the latest commit on the current branch\&. Note that the output format is inferred by the extension of the output file\&.
267 .RE
268 .PP
269 \fBgit archive \-o latest\&.tar \-\-prefix=build/ \-\-add\-file=configure \-\-prefix= HEAD\fR
270 .RS 4
271 Creates a tar archive that contains the contents of the latest commit on the current branch with no prefix and the untracked file
272 \fIconfigure\fR
273 with the prefix
274 \fIbuild/\fR\&.
275 .RE
276 .PP
277 \fBgit config tar\&.tar\&.xz\&.command "xz \-c"\fR
278 .RS 4
279 Configure a "tar\&.xz" format for making LZMA\-compressed tarfiles\&. You can use it specifying
280 \fB\-\-format=tar\&.xz\fR, or by creating an output file like
281 \fB\-o foo\&.tar\&.xz\fR\&.
282 .RE
283 .SH "SEE ALSO"
284 .sp
285 \fBgitattributes\fR(5)
286 .SH "GIT"
287 .sp
288 Part of the \fBgit\fR(1) suite