oasis-root

git-archive.1 (10955B)

'\" t
.\"     Title: git-archive
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
.\"      Date: 2025-03-14
.\"    Manual: Git Manual
.\"    Source: Git 2.49.0
.\"  Language: English
.\"
.TH "GIT\-ARCHIVE" "1" "2025-03-14" "Git 2\&.49\&.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
.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\&.\fR\fI<format>\fR\fB\&.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\&.
.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\&.
.sp
The
\fI<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\&.
.sp
Note that unlike
\fB\-\-add\-file\fR
the path created in the archive is not affected by the
\fB\-\-prefix\fR
option, as a full
\fI<path>\fR
can be given as the value of the option\&.
.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
\fI<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
\fI<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\&.\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\&.
.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\fR
\fBarchive\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\fR
\fBarchive\fR
\fBgzip\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 \&.\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\&.
.SH "EXAMPLES"
.PP
\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)
.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\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
.RS 4
Create a compressed tarball for v1\&.4\&.0 release\&.
.RE
.PP
\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
.RS 4
Same as above, but using the builtin tar\&.gz handling\&.
.RE
.PP
\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
.RS 4
Same as above, but the format is inferred from the output file\&.
.RE
.PP
\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
.RS 4
Create a compressed tarball for v1\&.4\&.0 release, but without a global extended pax header\&.
.RE
.PP
\fBgit\fR \fBarchive\fR \fB\-\-format=zip\fR \fB\-\-prefix=git\-docs/\fR \fBHEAD:Documentation/\fR > \fBgit\-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\fR \fBarchive\fR \fB\-o\fR \fBlatest\&.zip\fR \fBHEAD\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\fR \fBarchive\fR \fB\-o\fR \fBlatest\&.tar\fR \fB\-\-prefix=build/\fR \fB\-\-add\-file=configure\fR \fB\-\-prefix=\fR \fBHEAD\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\fR \fBconfig\fR \fBtar\&.tar\&.xz\&.command\fR "xz \fB\-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\fR
\fBfoo\&.tar\&.xz\fR\&.
.RE
.SH "SEE ALSO"
.sp
\fBgitattributes\fR(5)
.SH "GIT"
.sp
Part of the \fBgit\fR(1) suite