简体中文 ▾ 主题 ▾ 最新版本 ▾ git-archive 最后更新于 2.54.0

名称

git-archive - 从指定树创建文件归档

概要

git archive [--format=<fmt>] [--list] [--prefix=<prefix>/] [<extra>]
	      [-o <file> | --output=<file>] [--worktree-attributes]
	      [--remote=<repo> [--exec=<git-upload-archive>]] <tree-ish>
	      [<path>…​]

描述

创建指定格式的归档文件，其中包含所指定树的树结构，并将其写入标准输出。如果指定了 <prefix>（前缀），则将其置于归档文件中文件名的前面。

git archive 在使用树 ID 时与使用提交 ID 或标签 ID 时表现不同。当提供树 ID 时，当前时间被用作归档中每个文件的修改时间。另一方面，当提供提交 ID 或标签 ID 时，则使用引用的提交对象中记录的提交时间。此外，如果使用 tar 格式，提交 ID 会被存储在全局扩展 pax 头部中；可以使用 git get-tar-commit-id 进行提取。在 ZIP 文件中，它被存储为文件注释。

选项

--format=<fmt>

生成的归档格式。可能的值包括 tar、zip、tar.gz、tgz，以及任何通过配置选项 tar.<format>.command 定义的格式。如果没有给出 --format 且指定了输出文件，则尽可能从文件名推断格式（例如，写入 foo.zip 会使输出格式为 zip）。否则输出格式默认为 tar。

-l
--list

显示所有可用格式。

-v
--verbose

向 stderr 报告进度。

--prefix=<prefix>/

在归档文件的路径前添加 <prefix>/。该选项可重复使用；其最右侧的值将用于所有被跟踪的文件。参阅下文了解 --add-file 如何使用该值。

<prefix> 按原样使用，不会被规范化。它可能包含前导斜杠或父目录组件（例如 ../）。一些归档解压程序可能将此类路径视为潜在的不安全路径，并在解压时进行调整或发出警告。

-o <file>
--output=<file>

将归档写入 <file> 而不是标准输出。

--add-file=<file>

将非跟踪文件添加到归档中。可重复添加多个文件。在归档中的文件路径由在此 --add-file 之前最后一次出现的 --prefix 选项的值（如果有）与 <file> 的基名拼接而成。

--add-virtual-file=<path>:<content>

将指定内容添加到归档中。可重复添加多个文件。

<path> 参数可以以双引号字符开头和结尾；其中包含的文件名将被解释为 C 风格字符串，即反斜杠被解释为转义字符。如果路径包含冒号，则必须加引号，以避免冒号被误认为是路径与内容之间的分隔符；如果路径以双引号开头或结尾，也需要加引号。

文件模式仅限于常规文件，且该选项可能受限于平台相关的命令行长度限制。对于复杂情况，请先写入一个未跟踪的文件，然后改用 --add-file。

请注意，与 --add-file 不同，在归档中创建的路径不受 --prefix 选项的影响，因为该选项的值可以提供完整的 <path>。

--worktree-attributes

同时查找工作树中 .gitattributes 文件中的属性（参阅 属性）。

--mtime=<time>

设置归档条目的修改时间。如果不使用此选项，当 <tree-ish> 为提交或标签时使用提交者时间，如果为树对象则使用当前时间。

<extra>

这可以是归档后端支持的任何选项。请参阅下一节。

--remote=<repo>

不从本地仓库制作 tar 归档，而是从远程仓库获取。请注意，远程仓库可能会限制在 <tree-ish> 中允许使用的 sha1 表达式。详情请参阅 git-upload-archive[1]。

--exec=<git-upload-archive>

与 --remote 一起使用，用于指定远程端 git-upload-archive 的路径。

<tree-ish>

用于生成归档的树或提交。

<path>

如果没有可选的路径参数，当前工作目录的所有文件和子目录都将包含在归档中。如果指定了一个或多个路径，则仅包含这些路径。

后端额外选项

zip

-<digit>

指定压缩级别。较大的值会让命令花费更多时间以压缩到更小的尺寸。支持的值从 -0（仅存储）到 -9（最佳比例）。如果不指定，默认为 -6。

tar

-<number>

指定压缩级别。该值将传递给在 tar.<format>.command 中配置的压缩命令。请查阅已配置命令的手册页，以获取支持的级别列表以及未指定此选项时的默认级别。

配置

tar.umask

此变量可用于限制 tar 归档条目的权限位。默认值为 0002，即关闭全局写权限。特殊值 "user" 表示将使用归档用户的 umask。详情请参阅 umask(2)。如果使用了 --remote，则仅远程仓库的配置生效。

tar.<format>.command

此变量指定一个 shell 命令，通过该命令对 git archive 生成的 tar 输出进行管道传输。该命令使用 shell 执行，并将生成的 tar 文件作为其标准输入，应在标准输出上产生最终输出。任何压缩级别选项都将传递给该命令（例如 -9）。

tar.gz 和 tgz 格式是自动定义的，默认使用 magic 命令 git archive gzip，它会调用 gzip 的内部实现。

tar.<format>.remote

如果为 true，则启用该格式供远程客户端通过 git-upload-archive[1] 使用。对于用户定义的格式，默认值为 false，但对于 tar.gz 和 tgz 格式，默认值为 true。

属性 (ATTRIBUTES)
export-ignore

具有 export-ignore 属性的文件和目录不会被添加到归档文件中。详情请参阅 gitattributes[5]。

export-subst

如果一个文件设置了 export-subst 属性，Git 在将该文件添加到归档时会扩展几个占位符。详情请参阅 gitattributes[5]。

请注意，默认情况下，属性取自正在归档的树中的 .gitattributes 文件。如果你想在事后调整输出生成方式（例如，你在提交时没有在 .gitattributes 中添加适当的 export-ignore），请根据需要调整检出的 .gitattributes 文件并使用 --worktree-attributes 选项。或者，你可以将归档任何树时应应用的必要属性保留在 $GIT_DIR/info/attributes 文件中。

示例

git archive --format=tar --prefix=junk/ HEAD | (cd /var/tmp/ && tar xf -)

创建一个 tar 归档文件，其中包含当前分支上最新提交的内容，并将其解压到 /var/tmp/junk 目录中。

git archive --format=tar --prefix=git-1.4.0/ v1.4.0 | gzip >git-1.4.0.tar.gz

为 v1.4.0 版本创建一个压缩的 tarball。

git archive --format=tar.gz --prefix=git-1.4.0/ v1.4.0 >git-1.4.0.tar.gz

同上，但使用内置的 tar.gz 处理。

git archive --prefix=git-1.4.0/ -o git-1.4.0.tar.gz v1.4.0

同上，但格式从输出文件中推断得出。

git archive --format=tar --prefix=git-1.4.0/ v1.4.0^{tree} | gzip >git-1.4.0.tar.gz

为 v1.4.0 版本创建一个压缩的 tarball，但不包含全局扩展 pax 头部。

git archive --format=zip --prefix=git-docs/ HEAD:Documentation/ > git-1.4.0-docs.zip

将当前 head 的 Documentation/ 目录中的所有内容放入 git-1.4.0-docs.zip，前缀为 git-docs/。

git archive -o latest.zip HEAD

创建一个包含当前分支最新提交内容的 Zip 归档文件。请注意，输出格式由输出文件的扩展名推断。

git archive -o latest.tar --prefix=build/ --add-file=configure --prefix= HEAD

创建一个 tar 归档文件，其中包含当前分支上最新提交的内容（无前缀），以及前缀为 build/ 的未跟踪文件 configure。

git config tar.tar.xz.command "xz -c"

配置一个用于制作 LZMA 压缩 tar 文件的 "tar.xz" 格式。你可以通过指定 --format=tar.xz 或创建一个类似 -o foo.tar.xz 的输出文件来使用它。

另请参阅

gitattributes[5]

GIT

Git[1] 套件的一部分