blob: cfa1e4ebe4860d4905c44c5428b541ce3967826b [file] [log] [blame]
Franck Bui-Huu4df096a2006-09-07 15:12:02 +02001git-archive(1)
2==============
3
4NAME
5----
william pursell29cf5e12007-06-09 16:44:12 +01006git-archive - Create an archive of files from a named tree
Franck Bui-Huu4df096a2006-09-07 15:12:02 +02007
8
9SYNOPSIS
10--------
Matthias Kestenholze448ff82007-05-18 15:39:33 +020011[verse]
Wesley J. Landaker82d97da2009-08-27 20:55:43 -060012'git archive' [--format=<fmt>] [--list] [--prefix=<prefix>/] [<extra>]
Felipe Contreras0460ed22013-05-08 20:16:55 -050013 [-o <file> | --output=<file>] [--worktree-attributes]
Michele Ballabioc005c6a2007-10-05 00:41:11 +020014 [--remote=<repo> [--exec=<git-upload-archive>]] <tree-ish>
Štěpán Němec62b46982010-10-08 19:31:15 +020015 [<path>...]
Franck Bui-Huu4df096a2006-09-07 15:12:02 +020016
17DESCRIPTION
18-----------
19Creates an archive of the specified format containing the tree
Jari Aalto42b5f862007-09-14 21:38:02 +030020structure for the named tree, and writes it out to the standard
21output. If <prefix> is specified it is
Franck Bui-Huu4df096a2006-09-07 15:12:02 +020022prepended to the filenames in the archive.
23
Thomas Rast0b444cd2010-01-10 00:33:00 +010024'git archive' behaves differently when given a tree ID versus when
Franck Bui-Huu4df096a2006-09-07 15:12:02 +020025given a commit ID or tag ID. In the first case the current time is
David J. Mellor3f7cdf32009-03-16 23:16:14 -070026used as the modification time of each file in the archive. In the latter
Franck Bui-Huu4df096a2006-09-07 15:12:02 +020027case the commit time as recorded in the referenced commit object is
28used instead. Additionally the commit ID is stored in a global
29extended pax header if the tar format is used; it can be extracted
Thomas Rast0b444cd2010-01-10 00:33:00 +010030using 'git get-tar-commit-id'. In ZIP files it is stored as a file
Franck Bui-Huu4df096a2006-09-07 15:12:02 +020031comment.
32
33OPTIONS
34-------
35
36--format=<fmt>::
Dmitry Potapov0f4b3772009-09-14 00:17:01 +040037 Format of the resulting archive: 'tar' or 'zip'. If this option
38 is not given, and the output file is specified, the format is
39 inferred from the filename if possible (e.g. writing to "foo.zip"
40 makes the output to be in the zip format). Otherwise the output
41 format is `tar`.
Franck Bui-Huu4df096a2006-09-07 15:12:02 +020042
Stephan Beyer32402402008-06-08 03:36:09 +020043-l::
44--list::
Franck Bui-Huu4df096a2006-09-07 15:12:02 +020045 Show all available formats.
46
Stephan Beyer32402402008-06-08 03:36:09 +020047-v::
48--verbose::
Andrew Ruder27c8f8c2007-04-18 22:03:14 -050049 Report progress to stderr.
50
Franck Bui-Huu4df096a2006-09-07 15:12:02 +020051--prefix=<prefix>/::
52 Prepend <prefix>/ to each filename in the archive.
53
Dmitry Potapov05d39512009-09-13 16:05:52 +040054-o <file>::
Carlos Manuel Duclos Vergaraaec0c1b2009-02-16 18:20:25 +010055--output=<file>::
56 Write the archive to <file> instead of stdout.
57
Nguyễn Thái Ngọc Duyba053ea2009-04-18 00:18:05 +020058--worktree-attributes::
René Scharfe59a77142013-04-10 19:49:57 +020059 Look for attributes in .gitattributes files in the working tree
60 as well (see <<ATTRIBUTES>>).
Nguyễn Thái Ngọc Duyba053ea2009-04-18 00:18:05 +020061
Franck Bui-Huu4df096a2006-09-07 15:12:02 +020062<extra>::
David J. Mellor3f7cdf32009-03-16 23:16:14 -070063 This can be any options that the archiver backend understands.
Franck Bui-Huue8daf782006-09-25 12:31:52 +020064 See next section.
Franck Bui-Huu4df096a2006-09-07 15:12:02 +020065
66--remote=<repo>::
David J. Mellor3f7cdf32009-03-16 23:16:14 -070067 Instead of making a tar archive from the local repository,
Jeff King69897bc2014-02-28 05:01:29 -050068 retrieve a tar archive from a remote repository. Note that the
69 remote repository may place restrictions on which sha1
70 expressions may be allowed in `<tree-ish>`. See
71 linkgit:git-upload-archive[1] for details.
Franck Bui-Huu4df096a2006-09-07 15:12:02 +020072
Michele Ballabioc005c6a2007-10-05 00:41:11 +020073--exec=<git-upload-archive>::
74 Used with --remote to specify the path to the
Jonathan Niederba020ef2008-07-03 00:41:41 -050075 'git-upload-archive' on the remote side.
Michele Ballabioc005c6a2007-10-05 00:41:11 +020076
Franck Bui-Huu4df096a2006-09-07 15:12:02 +020077<tree-ish>::
78 The tree or commit to produce an archive for.
79
Štěpán Němec62b46982010-10-08 19:31:15 +020080<path>::
René Scharfe165ca622009-12-05 00:11:01 +010081 Without an optional path parameter, all files and subdirectories
82 of the current working directory are included in the archive.
83 If one or more paths are specified, only these are included.
Franck Bui-Huu4df096a2006-09-07 15:12:02 +020084
Franck Bui-Huue8daf782006-09-25 12:31:52 +020085BACKEND EXTRA OPTIONS
86---------------------
87
88zip
89~~~
90-0::
91 Store the files instead of deflating them.
92-9::
93 Highest and slowest compression level. You can specify any
94 number from 1 to 9 to adjust compression speed and ratio.
95
96
Franck Bui-Huu4df096a2006-09-07 15:12:02 +020097CONFIGURATION
98-------------
Franck Bui-Huu4df096a2006-09-07 15:12:02 +020099
René Scharfe687157c2007-08-21 20:01:16 +0200100tar.umask::
101 This variable can be used to restrict the permission bits of
102 tar archive entries. The default is 0002, which turns off the
103 world write bit. The special value "user" indicates that the
104 archiving user's umask will be used instead. See umask(2) for
René Scharfe810cae52011-04-14 20:04:57 +0200105 details. If `--remote` is used then only the configuration of
106 the remote repository takes effect.
Franck Bui-Huu4df096a2006-09-07 15:12:02 +0200107
Jeff King767cf452011-06-21 21:26:31 -0400108tar.<format>.command::
109 This variable specifies a shell command through which the tar
110 output generated by `git archive` should be piped. The command
111 is executed using the shell with the generated tar file on its
112 standard input, and should produce the final output on its
113 standard output. Any compression-level options will be passed
114 to the command (e.g., "-9"). An output file with the same
115 extension as `<format>` will be use this format if no other
116 format is given.
Jeff King0e804e02011-06-21 21:27:35 -0400117+
118The "tar.gz" and "tgz" formats are defined automatically and default to
119`gzip -cn`. You may override them with custom commands.
Jeff King767cf452011-06-21 21:26:31 -0400120
Jeff King7b977302011-06-21 23:17:35 -0400121tar.<format>.remote::
122 If true, enable `<format>` for use by remote clients via
123 linkgit:git-upload-archive[1]. Defaults to false for
124 user-defined formats, but true for the "tar.gz" and "tgz"
125 formats.
126
René Scharfe59a77142013-04-10 19:49:57 +0200127[[ATTRIBUTES]]
Roy Lee8d1b9d22009-03-04 00:49:29 +0800128ATTRIBUTES
129----------
130
131export-ignore::
132 Files and directories with the attribute export-ignore won't be
133 added to archive files. See linkgit:gitattributes[5] for details.
134
135export-subst::
Thomas Ackermann2de9b712013-01-21 20:17:53 +0100136 If the attribute export-subst is set for a file then Git will
Roy Lee8d1b9d22009-03-04 00:49:29 +0800137 expand several placeholders when adding this file to an archive.
138 See linkgit:gitattributes[5] for details.
139
Junio C Hamano9b4c8b02010-02-10 12:33:58 -0800140Note that attributes are by default taken from the `.gitattributes` files
141in the tree that is being archived. If you want to tweak the way the
142output is generated after the fact (e.g. you committed without adding an
143appropriate export-ignore in its `.gitattributes`), adjust the checked out
Thomas Rastfc7642a2011-01-10 13:57:43 +0100144`.gitattributes` file as necessary and use `--worktree-attributes`
Junio C Hamano9b4c8b02010-02-10 12:33:58 -0800145option. Alternatively you can keep necessary attributes that should apply
146while archiving any tree in your `$GIT_DIR/info/attributes` file.
147
Franck Bui-Huu4df096a2006-09-07 15:12:02 +0200148EXAMPLES
149--------
Jeff King5d2fc912011-08-03 20:13:29 -0600150`git archive --format=tar --prefix=junk/ HEAD | (cd /var/tmp/ && tar xf -)`::
Franck Bui-Huu4df096a2006-09-07 15:12:02 +0200151
152 Create a tar archive that contains the contents of the
David J. Mellor3f7cdf32009-03-16 23:16:14 -0700153 latest commit on the current branch, and extract it in the
Franck Bui-Huu4df096a2006-09-07 15:12:02 +0200154 `/var/tmp/junk` directory.
155
Jeff King5d2fc912011-08-03 20:13:29 -0600156`git archive --format=tar --prefix=git-1.4.0/ v1.4.0 | gzip >git-1.4.0.tar.gz`::
Franck Bui-Huu4df096a2006-09-07 15:12:02 +0200157
158 Create a compressed tarball for v1.4.0 release.
159
Jeff King5d2fc912011-08-03 20:13:29 -0600160`git archive --format=tar.gz --prefix=git-1.4.0/ v1.4.0 >git-1.4.0.tar.gz`::
Jeff King0e804e02011-06-21 21:27:35 -0400161
162 Same as above, but using the builtin tar.gz handling.
163
Jeff King5d2fc912011-08-03 20:13:29 -0600164`git archive --prefix=git-1.4.0/ -o git-1.4.0.tar.gz v1.4.0`::
Jeff King0e804e02011-06-21 21:27:35 -0400165
166 Same as above, but the format is inferred from the output file.
167
Jeff King6cf378f2012-04-26 04:51:57 -0400168`git archive --format=tar --prefix=git-1.4.0/ v1.4.0^{tree} | gzip >git-1.4.0.tar.gz`::
Franck Bui-Huu4df096a2006-09-07 15:12:02 +0200169
170 Create a compressed tarball for v1.4.0 release, but without a
171 global extended pax header.
172
Jeff King5d2fc912011-08-03 20:13:29 -0600173`git archive --format=zip --prefix=git-docs/ HEAD:Documentation/ > git-1.4.0-docs.zip`::
Franck Bui-Huu4df096a2006-09-07 15:12:02 +0200174
175 Put everything in the current head's Documentation/ directory
176 into 'git-1.4.0-docs.zip', with the prefix 'git-docs/'.
177
Jeff King5d2fc912011-08-03 20:13:29 -0600178`git archive -o latest.zip HEAD`::
Dmitry Potapov0f4b3772009-09-14 00:17:01 +0400179
180 Create a Zip archive that contains the contents of the latest
181 commit on the current branch. Note that the output format is
182 inferred by the extension of the output file.
183
Jeff King5d2fc912011-08-03 20:13:29 -0600184`git config tar.tar.xz.command "xz -c"`::
Jeff King767cf452011-06-21 21:26:31 -0400185
186 Configure a "tar.xz" format for making LZMA-compressed tarfiles.
187 You can use it specifying `--format=tar.xz`, or by creating an
188 output file like `-o foo.tar.xz`.
189
Roy Lee8d1b9d22009-03-04 00:49:29 +0800190
191SEE ALSO
192--------
193linkgit:gitattributes[5]
194
Franck Bui-Huu4df096a2006-09-07 15:12:02 +0200195GIT
196---
Christian Couder9e1f0a82008-06-06 09:07:32 +0200197Part of the linkgit:git[1] suite