| blob | ca5378b16b4aa7e326bfe43b7cefd1ecd1671e62 |
1 '\" t
2 .\" Title: git-archive
3 .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
4 .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
5 .\" Date: 2025-01-23
6 .\" Manual: Git Manual
7 .\" Source: Git 2.48.1.91.g5f8f7081f7
8 .\" Language: English
9 .\"
10 .TH "GIT\-ARCHIVE" "1" "2025-01-23" "Git 2\&.48\&.1\&.91\&.g5f8f708" "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 .SH "DESCRIPTION"
41 .sp
42 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\&.
43 .sp
44 \fIgit archive\fR behaves differently when given a tree ID as opposed to a commit ID or tag ID\&. When a tree ID is provided, the current time is used as the modification time of each file in the archive\&. On the other hand, when a commit ID or tag ID is provided, 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\&.
45 .SH "OPTIONS"
46 .PP
47 \-\-format=<fmt>
48 .RS 4
49 Format of the resulting archive\&. Possible values are
50 \fBtar\fR,
51 \fBzip\fR,
52 \fBtar\&.gz\fR,
53 \fBtgz\fR, and any format defined using the configuration option
54 \fBtar\&.\fR\fI<format>\fR\fB\&.command\fR\&. If
55 \fB\-\-format\fR
56 is not given, and the output file is specified, the format is inferred from the filename if possible (e\&.g\&. writing to
57 \fBfoo\&.zip\fR
58 makes the output to be in the
59 \fBzip\fR
60 format)\&. Otherwise the output format is
61 \fBtar\fR\&.
62 .RE
63 .PP
64 \-l, \-\-list
65 .RS 4
66 Show all available formats\&.
67 .RE
68 .PP
69 \-v, \-\-verbose
70 .RS 4
71 Report progress to stderr\&.
72 .RE
73 .PP
74 \-\-prefix=<prefix>/
75 .RS 4
76 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
77 \fB\-\-add\-file\fR\&.
78 .RE
79 .PP
80 \-o <file>, \-\-output=<file>
81 .RS 4
82 Write the archive to <file> instead of stdout\&.
83 .RE
84 .PP
85 \-\-add\-file=<file>
86 .RS 4
87 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
88 \fB\-\-prefix\fR
89 option (if any) before this
90 \fB\-\-add\-file\fR
91 and the basename of <file>\&.
92 .RE
93 .PP
94 \-\-add\-virtual\-file=<path>:<content>
95 .RS 4
96 Add the specified contents to the archive\&. Can be repeated to add multiple files\&.
97 .sp
98 The
99 \fI<path>\fR
100 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\&.
101 .sp
102 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
103 \fB\-\-add\-file\fR
104 instead\&.
105 .sp
106 Note that unlike
107 \fB\-\-add\-file\fR
108 the path created in the archive is not affected by the
109 \fB\-\-prefix\fR
110 option, as a full
111 \fI<path>\fR
112 can be given as the value of the option\&.
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 \fI<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 \fI<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\&.\fR\fI<format>\fR\fB\&.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\fR
190 \fBarchive\fR
191 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\&.,
192 \fB\-9\fR)\&.
193 .sp
194 The
195 \fBtar\&.gz\fR
196 and
197 \fBtgz\fR
198 formats are defined automatically and use the magic command
199 \fBgit\fR
200 \fBarchive\fR
201 \fBgzip\fR
202 by default, which invokes an internal implementation of gzip\&.
203 .RE
204 .PP
205 tar\&.<format>\&.remote
206 .RS 4
207 If true, enable the format for use by remote clients via
208 \fBgit-upload-archive\fR(1)\&. Defaults to false for user\-defined formats, but true for the
209 \fBtar\&.gz\fR
210 and
211 \fBtgz\fR
212 formats\&.
213 .RE
214 .SH "ATTRIBUTES"
215 .PP
216 export\-ignore
217 .RS 4
218 Files and directories with the attribute export\-ignore won\(cqt be added to archive files\&. See
219 \fBgitattributes\fR(5)
220 for details\&.
221 .RE
222 .PP
223 export\-subst
224 .RS 4
225 If the attribute export\-subst is set for a file then Git will expand several placeholders when adding this file to an archive\&. See
226 \fBgitattributes\fR(5)
227 for details\&.
228 .RE
229 .sp
230 Note that attributes are by default taken from the \&.\fBgitattributes\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 \&.\fBgitattributes\fR), adjust the checked out \&.\fBgitattributes\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\&.
231 .SH "EXAMPLES"
232 .PP
233 \fBgit\fR \fBarchive\fR \fB\-\-format=tar\fR \fB\-\-prefix=junk/\fR \fBHEAD\fR | (\fBcd\fR \fB/var/tmp/\fR && \fBtar\fR \fBxf\fR \fB\-\fR)
234 .RS 4
235 Create a tar archive that contains the contents of the latest commit on the current branch, and extract it in the
236 \fB/var/tmp/junk\fR
237 directory\&.
238 .RE
239 .PP
240 \fBgit\fR \fBarchive\fR \fB\-\-format=tar\fR \fB\-\-prefix=git\-1\&.4\&.0/\fR \fBv1\&.4\&.0\fR | \fBgzip\fR >\fBgit\-1\&.4\&.0\&.tar\&.gz\fR
241 .RS 4
242 Create a compressed tarball for v1\&.4\&.0 release\&.
243 .RE
244 .PP
245 \fBgit\fR \fBarchive\fR \fB\-\-format=tar\&.gz\fR \fB\-\-prefix=git\-1\&.4\&.0/\fR \fBv1\&.4\&.0\fR >\fBgit\-1\&.4\&.0\&.tar\&.gz\fR
246 .RS 4
247 Same as above, but using the builtin tar\&.gz handling\&.
248 .RE
249 .PP
250 \fBgit\fR \fBarchive\fR \fB\-\-prefix=git\-1\&.4\&.0/\fR \fB\-o\fR \fBgit\-1\&.4\&.0\&.tar\&.gz\fR \fBv1\&.4\&.0\fR
251 .RS 4
252 Same as above, but the format is inferred from the output file\&.
253 .RE
254 .PP
255 \fBgit\fR \fBarchive\fR \fB\-\-format=tar\fR \fB\-\-prefix=git\-1\&.4\&.0/\fR \fBv1\&.4\&.0^\fR{tree} | \fBgzip\fR >\fBgit\-1\&.4\&.0\&.tar\&.gz\fR
256 .RS 4
257 Create a compressed tarball for v1\&.4\&.0 release, but without a global extended pax header\&.
258 .RE
259 .PP
260 \fBgit\fR \fBarchive\fR \fB\-\-format=zip\fR \fB\-\-prefix=git\-docs/\fR \fBHEAD:Documentation/\fR > \fBgit\-1\&.4\&.0\-docs\&.zip\fR
261 .RS 4
262 Put everything in the current head\(cqs Documentation/ directory into
263 \fIgit\-1\&.4\&.0\-docs\&.zip\fR, with the prefix
264 \fIgit\-docs/\fR\&.
265 .RE
266 .PP
267 \fBgit\fR \fBarchive\fR \fB\-o\fR \fBlatest\&.zip\fR \fBHEAD\fR
268 .RS 4
269 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\&.
270 .RE
271 .PP
272 \fBgit\fR \fBarchive\fR \fB\-o\fR \fBlatest\&.tar\fR \fB\-\-prefix=build/\fR \fB\-\-add\-file=configure\fR \fB\-\-prefix=\fR \fBHEAD\fR
273 .RS 4
274 Creates a tar archive that contains the contents of the latest commit on the current branch with no prefix and the untracked file
275 \fIconfigure\fR
276 with the prefix
277 \fIbuild/\fR\&.
278 .RE
279 .PP
280 \fBgit\fR \fBconfig\fR \fBtar\&.tar\&.xz\&.command\fR "xz \fB\-c\fR"
281 .RS 4
282 Configure a "tar\&.xz" format for making LZMA\-compressed tarfiles\&. You can use it specifying
283 \fB\-\-format=tar\&.xz\fR, or by creating an output file like
284 \fB\-o\fR
285 \fBfoo\&.tar\&.xz\fR\&.
286 .RE
287 .SH "SEE ALSO"
288 .sp
289 \fBgitattributes\fR(5)
290 .SH "GIT"
291 .sp
292 Part of the \fBgit\fR(1) suite