| '\" t |
| .\" Title: git-archive |
| .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author] |
| .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> |
| .\" Date: 2024-04-29 |
| .\" Manual: Git Manual |
| .\" Source: Git 2.45.0 |
| .\" Language: English |
| .\" |
| .TH "GIT\-ARCHIVE" "1" "2024\-04\-29" "Git 2\&.45\&.0" "Git Manual" |
| .\" ----------------------------------------------------------------- |
| .\" * Define some portability stuff |
| .\" ----------------------------------------------------------------- |
| .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| .\" http://bugs.debian.org/507673 |
| .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html |
| .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| .ie \n(.g .ds Aq \(aq |
| .el .ds Aq ' |
| .\" ----------------------------------------------------------------- |
| .\" * set default formatting |
| .\" ----------------------------------------------------------------- |
| .\" disable hyphenation |
| .nh |
| .\" disable justification (adjust text to left margin only) |
| .ad l |
| .\" ----------------------------------------------------------------- |
| .\" * MAIN CONTENT STARTS HERE * |
| .\" ----------------------------------------------------------------- |
| .SH "NAME" |
| git-archive \- Create an archive of files from a named tree |
| .SH "SYNOPSIS" |
| .sp |
| .nf |
| \fIgit archive\fR [\-\-format=<fmt>] [\-\-list] [\-\-prefix=<prefix>/] [<extra>] |
| [\-o <file> | \-\-output=<file>] [\-\-worktree\-attributes] |
| [\-\-remote=<repo> [\-\-exec=<git\-upload\-archive>]] <tree\-ish> |
| [<path>\&...] |
| .fi |
| .sp |
| .SH "DESCRIPTION" |
| .sp |
| 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\&. |
| .sp |
| \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\&. |
| .SH "OPTIONS" |
| .PP |
| \-\-format=<fmt> |
| .RS 4 |
| Format of the resulting archive\&. Possible values are |
| \fBtar\fR, |
| \fBzip\fR, |
| \fBtar\&.gz\fR, |
| \fBtgz\fR, and any format defined using the configuration option |
| \fBtar\&.<format>\&.command\fR\&. If |
| \fB\-\-format\fR |
| is not given, and the output file is specified, the format is inferred from the filename if possible (e\&.g\&. writing to |
| \fBfoo\&.zip\fR |
| makes the output to be in the |
| \fBzip\fR |
| format)\&. Otherwise the output format is |
| \fBtar\fR\&. |
| .RE |
| .PP |
| \-l, \-\-list |
| .RS 4 |
| Show all available formats\&. |
| .RE |
| .PP |
| \-v, \-\-verbose |
| .RS 4 |
| Report progress to stderr\&. |
| .RE |
| .PP |
| \-\-prefix=<prefix>/ |
| .RS 4 |
| 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 |
| \fB\-\-add\-file\fR |
| and |
| \fB\-\-add\-virtual\-file\fR\&. |
| .RE |
| .PP |
| \-o <file>, \-\-output=<file> |
| .RS 4 |
| Write the archive to <file> instead of stdout\&. |
| .RE |
| .PP |
| \-\-add\-file=<file> |
| .RS 4 |
| 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 |
| \fB\-\-prefix\fR |
| option (if any) before this |
| \fB\-\-add\-file\fR |
| and the basename of <file>\&. |
| .RE |
| .PP |
| \-\-add\-virtual\-file=<path>:<content> |
| .RS 4 |
| 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 |
| \fB\-\-prefix\fR |
| option (if any) before this |
| \fB\-\-add\-virtual\-file\fR |
| and |
| \fB<path>\fR\&. |
| .sp |
| The |
| \fB<path>\fR |
| 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\&. |
| .sp |
| 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 |
| \fB\-\-add\-file\fR |
| instead\&. |
| .RE |
| .PP |
| \-\-worktree\-attributes |
| .RS 4 |
| Look for attributes in \&.gitattributes files in the working tree as well (see |
| the section called \(lqATTRIBUTES\(rq)\&. |
| .RE |
| .PP |
| \-\-mtime=<time> |
| .RS 4 |
| Set modification time of archive entries\&. Without this option the committer time is used if |
| \fB<tree\-ish>\fR |
| is a commit or tag, and the current time if it is a tree\&. |
| .RE |
| .PP |
| <extra> |
| .RS 4 |
| This can be any options that the archiver backend understands\&. See next section\&. |
| .RE |
| .PP |
| \-\-remote=<repo> |
| .RS 4 |
| 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 |
| \fB<tree\-ish>\fR\&. See |
| \fBgit-upload-archive\fR(1) |
| for details\&. |
| .RE |
| .PP |
| \-\-exec=<git\-upload\-archive> |
| .RS 4 |
| Used with \-\-remote to specify the path to the |
| \fIgit\-upload\-archive\fR |
| on the remote side\&. |
| .RE |
| .PP |
| <tree\-ish> |
| .RS 4 |
| The tree or commit to produce an archive for\&. |
| .RE |
| .PP |
| <path> |
| .RS 4 |
| 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\&. |
| .RE |
| .SH "BACKEND EXTRA OPTIONS" |
| .SS "zip" |
| .PP |
| \-<digit> |
| .RS 4 |
| Specify compression level\&. Larger values allow the command to spend more time to compress to smaller size\&. Supported values are from |
| \fB\-0\fR |
| (store\-only) to |
| \fB\-9\fR |
| (best ratio)\&. Default is |
| \fB\-6\fR |
| if not given\&. |
| .RE |
| .SS "tar" |
| .PP |
| \-<number> |
| .RS 4 |
| Specify compression level\&. The value will be passed to the compression command configured in |
| \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\&. |
| .RE |
| .SH "CONFIGURATION" |
| .PP |
| tar\&.umask |
| .RS 4 |
| 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 |
| \fB\-\-remote\fR |
| is used then only the configuration of the remote repository takes effect\&. |
| .RE |
| .PP |
| tar\&.<format>\&.command |
| .RS 4 |
| This variable specifies a shell command through which the tar output generated by |
| \fBgit archive\fR |
| 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\&., |
| \fB\-9\fR)\&. |
| .sp |
| The |
| \fBtar\&.gz\fR |
| and |
| \fBtgz\fR |
| formats are defined automatically and use the magic command |
| \fBgit archive gzip\fR |
| by default, which invokes an internal implementation of gzip\&. |
| .RE |
| .PP |
| tar\&.<format>\&.remote |
| .RS 4 |
| If true, enable the format for use by remote clients via |
| \fBgit-upload-archive\fR(1)\&. Defaults to false for user\-defined formats, but true for the |
| \fBtar\&.gz\fR |
| and |
| \fBtgz\fR |
| formats\&. |
| .RE |
| .SH "ATTRIBUTES" |
| .PP |
| export\-ignore |
| .RS 4 |
| Files and directories with the attribute export\-ignore won\(cqt be added to archive files\&. See |
| \fBgitattributes\fR(5) |
| for details\&. |
| .RE |
| .PP |
| export\-subst |
| .RS 4 |
| If the attribute export\-subst is set for a file then Git will expand several placeholders when adding this file to an archive\&. See |
| \fBgitattributes\fR(5) |
| for details\&. |
| .RE |
| .sp |
| 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\&. |
| .SH "EXAMPLES" |
| .PP |
| \fBgit archive \-\-format=tar \-\-prefix=junk/ HEAD | (cd /var/tmp/ && tar xf \-)\fR |
| .RS 4 |
| Create a tar archive that contains the contents of the latest commit on the current branch, and extract it in the |
| \fB/var/tmp/junk\fR |
| directory\&. |
| .RE |
| .PP |
| \fBgit archive \-\-format=tar \-\-prefix=git\-1\&.4\&.0/ v1\&.4\&.0 | gzip >git\-1\&.4\&.0\&.tar\&.gz\fR |
| .RS 4 |
| Create a compressed tarball for v1\&.4\&.0 release\&. |
| .RE |
| .PP |
| \fBgit archive \-\-format=tar\&.gz \-\-prefix=git\-1\&.4\&.0/ v1\&.4\&.0 >git\-1\&.4\&.0\&.tar\&.gz\fR |
| .RS 4 |
| Same as above, but using the builtin tar\&.gz handling\&. |
| .RE |
| .PP |
| \fBgit archive \-\-prefix=git\-1\&.4\&.0/ \-o git\-1\&.4\&.0\&.tar\&.gz v1\&.4\&.0\fR |
| .RS 4 |
| Same as above, but the format is inferred from the output file\&. |
| .RE |
| .PP |
| \fBgit archive \-\-format=tar \-\-prefix=git\-1\&.4\&.0/ v1\&.4\&.0^{tree} | gzip >git\-1\&.4\&.0\&.tar\&.gz\fR |
| .RS 4 |
| Create a compressed tarball for v1\&.4\&.0 release, but without a global extended pax header\&. |
| .RE |
| .PP |
| \fBgit archive \-\-format=zip \-\-prefix=git\-docs/ HEAD:Documentation/ > git\-1\&.4\&.0\-docs\&.zip\fR |
| .RS 4 |
| Put everything in the current head\(cqs Documentation/ directory into |
| \fIgit\-1\&.4\&.0\-docs\&.zip\fR, with the prefix |
| \fIgit\-docs/\fR\&. |
| .RE |
| .PP |
| \fBgit archive \-o latest\&.zip HEAD\fR |
| .RS 4 |
| 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\&. |
| .RE |
| .PP |
| \fBgit archive \-o latest\&.tar \-\-prefix=build/ \-\-add\-file=configure \-\-prefix= HEAD\fR |
| .RS 4 |
| Creates a tar archive that contains the contents of the latest commit on the current branch with no prefix and the untracked file |
| \fIconfigure\fR |
| with the prefix |
| \fIbuild/\fR\&. |
| .RE |
| .PP |
| \fBgit config tar\&.tar\&.xz\&.command "xz \-c"\fR |
| .RS 4 |
| Configure a "tar\&.xz" format for making LZMA\-compressed tarfiles\&. You can use it specifying |
| \fB\-\-format=tar\&.xz\fR, or by creating an output file like |
| \fB\-o foo\&.tar\&.xz\fR\&. |
| .RE |
| .SH "SEE ALSO" |
| .sp |
| \fBgitattributes\fR(5) |
| .SH "GIT" |
| .sp |
| Part of the \fBgit\fR(1) suite |