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>，它会被添加到存档中的文件名前面。

当给定树 ID 与提交 ID 或标签 ID 时，'git archive' 的行为不同。当提供树 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> 而不是 stdout。

--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 存档，而是从远程存储库检索 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 格式是自动定义的，默认使用魔术命令 git archive gzip，它调用 gzip 的内部实现。

tar.<format>.remote

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

属性

export-ignore

具有 export-ignore 属性的文件和目录不会被添加到存档文件中。有关详细信息，请参阅 gitattributes(5)。

export-subst

如果为文件设置了 export-subst 属性，则 Git 在将此文件添加到存档时将展开几个占位符。有关详细信息，请参阅 gitattributes(5)。

请注意，属性默认取自正在存档的树中的 .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) 套件的一部分