GIT-R3.ECLASS

章节: eclass-manpages (5)
更新: 2024 年 11 月
索引返回主目录

名称

git-r3.eclass - 用于获取和解压缩 git 存储库的 Eclass。

描述

第三代 Eclass，简化了使用 git 作为远程存储库的实时 ebuild 的维护。

支持的 EAPIS

7 8

函数

git-r3_fetch [<repo-uri> [<remote-ref> [<local-id> [<commit-date>]]]]

将新提交获取到存储库的本地克隆中。

<repo-uri> 指定要从中获取的存储库 URI，以空格分隔的列表形式。第一个 URI 将用作存储库组标识符，因此必须始终一致使用。如果未指定，则默认为 ${EGIT_REPO_URI}。

<remote-ref> 指定要获取的远程引用或提交 ID。建议使用 'refs/heads/<branch-name>' 表示分支，'refs/tags/<tag-name>' 表示标签。其他选项包括 'HEAD' 表示上游默认分支，以及十六进制提交 SHA1。默认情况下，优先级依次为 EGIT_COMMIT、EGIT_BRANCH 或文字 'HEAD'，只要其中一个被设置为非空值。

<local-id> 指定本地分支标识符，用于在本地存储获取结果。它应该在同一存储库中同时执行的多个获取操作（包括并行合并）之间保持唯一。它默认为 ${CATEGORY}/${PN}/${SLOT%/*}。除非您在同一 ebuild 中从同一存储库获取多个树，否则该默认值应该足够了。

<commit-date> 请求尝试使用特定日期的存储库状态。有关更多详细信息，请参阅 EGIT_COMMIT_DATE。

获取操作只会影响 EGIT_STORE。它不会触及工作副本，也不会导出任何环境变量。如果存储库包含子模块，则会递归获取它们。

git-r3_checkout [<repo-uri> [<checkout-path> [<local-id> [<checkout-paths>...]]]]

将先前获取的树检出到工作副本。

<repo-uri> 指定存储库 URI，以空格分隔的列表形式。第一个 URI 将用作存储库组标识符，因此必须与 git-r3_fetch 保持一致。其余 URI 不使用，因此可以省略。如果未指定，则默认为 ${EGIT_REPO_URI}。

<checkout-path> 指定放置检出操作的路径。如果设置了 ${EGIT_CHECKOUT_DIR}，则默认为该路径，否则默认为 ${WORKDIR}/${P}。

<local-id> 需要指定用于相应 git-r3_fetch 的本地标识符。

如果指定了 <checkout-paths>，则将指定的路径传递给 'git checkout' 以执行部分检出。请注意，此类检出不会导致存储库切换分支，并且目前将跳过子模块。匹配这些路径的子模块可能在将来的 Eclass 版本中被检出。

检出操作将写入工作副本，并将存储库状态导出到环境中。如果存储库包含子模块，则会递归检出它们。

git-r3_peek_remote_ref [<repo-uri> [<remote-ref>]]

查看远程存储库中的引用并打印匹配的（最新）提交 SHA1。

<repo-uri> 指定要从中获取的存储库 URI，以空格分隔的列表形式。如果未指定，则默认为 ${EGIT_REPO_URI}。

<remote-ref> 指定要查看的远程引用。建议使用 'refs/heads/<branch-name>' 表示分支，'refs/tags/<tag-name>' 表示标签。或者，可以使用 'HEAD' 表示上游默认分支。默认情况下，优先级依次为 EGIT_COMMIT、EGIT_BRANCH 或文字 'HEAD'，只要其中一个被设置为非空值。

该操作将在远程执行，不会使用本地存储。如果提交 SHA1 作为 <remote-ref> 提供，则由于 git 协议的限制，该函数将失败。

成功时，该函数返回 0 并将十六进制提交 SHA1 写入 stdout。失败时，该函数返回 1。

ECLASS 变量

EGIT_LFS (在继承之前设置)

如果设置，则启用 git lfs 支持。在继承此 Eclass 之前设置。

EGIT_CLONE_TYPE ?= single (用户变量)

应该针对远程存储库使用的克隆类型。可以是以下任一类型：'mirror'、'single'、'shallow'。

这旨在由用户在 make.conf 中设置。Ebuild 应该在必要时设置 EGIT_MIN_CLONE_TYPE 而不是这个。

'mirror' 类型克隆所有远程分支和标签，包括完整历史记录和所有注释。EGIT_COMMIT 可以指定任何提交哈希值。上游删除的分支和标签将在获取时从本地克隆中清除。此模式适合克隆本地副本以进行开发或托管本地 git 镜像。但是，克隆包含大量分叉分支的存储库可能会很快变得很大。

'single+tags' 类型克隆请求的分支和存储库中的所有标签。所有注释也将被获取。EGIT_COMMIT 可以安全地指定当前分支和所有标签中的哈希值。不会清除旧的引用（如果您经常切换分支，您可能需要自己删除过时的分支）。此模式主要用于 Google Code 等无法在 'single' 模式下与分支一起获取标签的损坏 git 服务器。

'single' 类型只克隆请求的分支或标签。引用整个分支历史记录的标签也将被获取，以及所有注释。EGIT_COMMIT 可以安全地只指定当前分支中的哈希值。不会清除旧的引用（如果您经常切换分支，您可能需要自己删除过时的分支）。此模式适合一般使用。

'shallow' 类型只克隆请求的分支或标签上的最新提交。EGIT_COMMIT 只能指定标签，并且由于历史记录不可用，'git describe' 等调用将不会引用以前的标签。不会清除旧的引用。此模式主要用于磁盘空间有限的嵌入式系统。

EGIT_MIN_CLONE_TYPE ?= shallow

Ebuild 支持的“最小”克隆类型。接受与 EGIT_CLONE_TYPE 相同的值。当用户设置的类型“低于”（即，在列表中排在后面）EGIT_MIN_CLONE_TYPE 时，Eclass 将改为使用 EGIT_MIN_CLONE_TYPE。

此变量旨在仅供 Ebuild 使用。用户应该改为设置 EGIT_CLONE_TYPE。

一个常见的情况是在构建系统需要访问完整的分支历史记录时使用 'single'，或者在 Google Code 或类似的远程服务器无法支持浅克隆和获取提交时的标签时使用 'single+tags'。请谨慎使用，并且仅用于修复致命错误，而不是“非漂亮版本”。

EGIT_LFS_CLONE_TYPE ?= shallow (用户变量)

应该针对远程存储库使用的 lfs 克隆类型。可以是以下任一类型：'mirror'、'single'、'shallow'。

这与 EGIT_CLONE_TYPE 的工作方式略有不同。

'mirror' 类型克隆从克隆的仓库中可用的所有 LFS 文件。这主要用于备份或重新托管目的，因为磁盘使用量会非常大。

'single' 类型只克隆当前提交的 LFS 文件。但是，与 'shallow' 不同，它不会清理过时的 LFS 文件。

'shallow' 类型只克隆当前提交的 LFS 文件。与当前提交无关且超过几天时间的 LFS 文件将自动删除，以节省磁盘空间。这是 LFS 仓库的推荐模式，可以防止过度使用磁盘空间。

EVCS_STORE_DIRS = () (由 Eclass 生成)

记录在 git3_src 中克隆的所有存储库目录的名称。这在 ebuild 同时获取多个存储库的情况下很有用，并且会由 eclean 用于清理它们。

EGIT3_STORE_DIR (用户变量)

git 源码的存储目录。

这旨在由用户在 make.conf 中设置。Ebuild 绝不能设置它。

EGIT3_STORE_DIR=${DISTDIR}/git3-src

EGIT_MIRROR_URI

指向本地 git 镜像的“顶部” URI。如果指定，Eclass 将尝试从本地镜像获取，而不是使用远程存储库。

镜像需要遵循 EGIT3_STORE_DIR 结构。由 Eclass 创建的目录可以用于此目的。

示例

EGIT_MIRROR_URI="git://mirror.lan/"

EGIT_REPO_URI (必需)

指向存储库的 URI，例如 https://foo. 如果提供多个 URI，Eclass 将认为其余 URI 是备选方案，如果第一个 URI 无法正常工作，则会尝试这些备选方案。有关支持的 URI 语法，请阅读 git-clone(1) 的手册页。

只要可能，URI 应该使用 https://。http:// 和 git:// URI 非常不安全，即使只作为备选方案使用，也会让 ebuild 完全容易受到中间人攻击。

可以是空格分隔的列表或数组。

示例

EGIT_REPO_URI="https://a/b.git https://c/d.git"

EVCS_OFFLINE

如果非空，则此变量会阻止任何在线操作。

EVCS_UMASK

将此变量设置为自定义 umask。这旨在由用户设置。通过将其设置为 002 等值，可以简化非 root 用户（但属于 portage 组）进行开发，然后切换到使用 FEATURES=userpriv 进行构建的操作。反之亦然。这应该不是安全问题，因为任何拥有 portage 组写入权限的人都可以用更巧妙的方式破坏系统。

EGIT_BRANCH

要检出的分支名称。如果未设置，将使用上游默认分支（HEAD）。

EGIT_COMMIT

要检出的标签名称或提交标识符。如果未设置，将使用分支上的最新提交。请注意，如果将其设置为不在 HEAD 分支上的提交，则需要将 EGIT_BRANCH 设置为该提交所在的可用分支。

EGIT_COMMIT_DATE

尝试检出指定时间戳的存储库状态。该日期应符合 'git rev-list' 理解的格式。将考虑 EGIT_BRANCH 上的提交。

Eclass 将选择提交日期在指定日期之前的最后一个提交。如果找到合并提交，则只考虑第一个父节点，以避免切换到外部分支（假设合并是正确完成的）。换句话说，每次合并都将被视为具有对应于合并提交日期的单个提交。

EGIT_CHECKOUT_DIR

将 git 源码检出到的目录。

EGIT_CHECKOUT_DIR=${WORKDIR}/${P}

EGIT_SUBMODULES

子模块名称的包含和排除通配符数组，用于指定哪些子模块被获取和检出。排除项以 '-' 开头，并排除先前匹配的子模块。

如果未设置，则启用所有子模块。空列表禁用所有子模块。为了使用仅排除列表，请在数组中以 '*' 开头。

请记住，通配符需要被引用，以防止文件名扩展。

示例

# Disable all submodules
EGIT_SUBMODULES=()

# Include only foo and bar
EGIT_SUBMODULES=( foo bar )

# Use all submodules except for test-* but include test-lib
EGIT_SUBMODULES=( '*' '-test-*' test-lib )

维护者

Michał Górny <[email protected]>

报告错误

请通过 https://bugs.gentoo.org/ 报告错误。

文件

git-r3.eclass

另请参阅

ebuild(5)
https://gitweb.gentoo.org/repo/gentoo.git/log/eclass/git-r3.eclass

此文档由 man2html 使用手册页创建。
时间：2024 年 11 月 12 日，格林威治标准时间 03:27:01