Git

Git 助手是对 git 命令的轻量级封装。它可用于多种目的

  • set_version() 方法中获取当前标签并将其赋值给 self.version

  • source() 方法中克隆第三方或开源包配方中的源代码(通常,建议使用 download()get() 来获取发布版的 tarball 文件)

  • export() 方法中捕获您自己的包源的“scm”坐标(url、commit),以便稍后能够从源代码重现构建,并在 source() 方法中检索代码。请参阅git-scm 捕获示例

Git() 构造函数接收当前文件夹作为参数,但如有必要可以更改,例如,在 source() 中克隆某个仓库的源代码

def source(self):
   git = Git(self)  # by default, the current folder "."
   git.clone(url="<repourl>", target="target") # git clone url target
   # we need to cd directory for next command "checkout" to work
   git.folder = "target"                       # cd target
   git.checkout(commit="<commit>")             # git checkout commit

另一种等效方法是

def source(self):
   git = Git(self, "target")
   # Cloning in current dir, not a children folder
   git.clone(url="<repourl>", target=".")
   git.checkout(commit="<commit>")
class Git(conanfile, folder='.', excluded=None)

Git 是用于 git 工具的几种常用模式的包装器。

参数:
  • conanfile – Conanfile 实例。

  • folder – 当前目录,默认为 .,即当前工作目录。

  • excluded – 从“脏”检查中排除的文件。它将与配置 core.scm:excluded 组合(该配置具有更高优先级)。它是一个用于 fnmatch 的模式列表。

run(cmd, hidden_output=None)

执行 git <cmd>

返回:

命令的控制台输出。

get_commit(repository=False)
参数:

repository – 默认情况下获取指定文件夹的提交,使用 repo=True 获取仓库的提交。

返回:

当前提交,通过 git rev-list HEAD -n 1 -- <folder>。返回最新的提交,不考虑本地未提交的更改。

get_remote_url(remote='origin')

使用 git remote -v 获取远程 Git 仓库的 URL

警告!请注意,此方法将从 git remote -v 获取输出。如果您在 URL 中向远程添加了令牌或凭据,它们将被暴露。凭据不应添加到 Git 远程定义中,而应使用凭据管理器或类似机制。如果您仍想使用此方法,您有责任从结果中剥离凭据。

参数:

remote – 远程 Git 仓库的名称(默认为 'origin')。

返回:

远程 Git 仓库的 URL。

commit_in_remote(commit, remote='origin')

检查给定提交是否存在于远程仓库中,通过 branch -r --contains <commit> 并检查该远程仓库中是否存在一个分支。

参数:
  • commit – 要检查的提交。

  • remote – 远程 Git 仓库的名称(默认为 'origin')。

返回:

如果给定提交存在于远程仓库中则为 True,否则为 False。

is_dirty(repository=False)

通过运行 git status -s 返回当前文件夹是否为脏。 Git(..., excluded=[]) 参数和 core.scm:excluded 配置将定义在此检查中跳过的文件模式。

参数:

repository – 默认情况下检查当前文件夹是否为脏。如果 repository=True,它将检查根仓库文件夹而不是当前文件夹。

返回:

如果当前文件夹为脏,则为 True。否则为 False。

get_url_and_commit(remote='origin', repository=False)

这是一个高级方法,它返回当前提交和远程仓库 URL。此方法旨在捕获用于包创建的当前远程坐标,以便以后可以从同一提交的源代码再次构建。其行为如下:

  • 如果仓库是脏的,它将引发异常。捕获脏内容的坐标没有意义,因为它将无法重现。如果存在本地更改,并且用户想要测试本地 Conan 创建,则应首先提交更改(本地提交,而不是推送到远程)。

  • 如果仓库不是脏的,但提交在给定远程仓库中不存在,该方法将返回该提交以及本地用户检出的 URL。这样,可以在将更改推送到远程之前,先在本地创建 Conan 包并测试一切是否正常工作。

  • 如果仓库不是脏的,并且提交存在于指定的远程仓库中,它将返回该提交和远程仓库的 URL。

警告!请注意,此方法将从 git remote -v 获取输出。如果您在 URL 中向远程添加了令牌或凭据,它们将被暴露。凭据不应添加到 Git 远程定义中,而应使用凭据管理器或类似机制。如果您仍想使用此方法,您有责任从结果中剥离凭据。

参数:
  • remote – 远程 Git 仓库的名称(默认为 'origin')。

  • repository – 默认情况下获取指定文件夹的提交,使用 repo=True 获取仓库的提交。

返回:

(url, commit) 元组

get_repo_root()

使用 git rev-parse --show-toplevel 获取当前仓库的根文件夹

返回:

仓库根文件夹。

clone(url, target='', args=None, hide_url=True)

执行 git clone <url> <args> <target> 操作,其中 target 是目标目录。

参数:
  • url – 远程仓库的 URL。

  • target – 目标文件夹。

  • args – 作为列表传递给 git clone 的额外参数。

  • hide_url – 从日志输出中隐藏 URL,以防止意外的凭据泄漏。可以通过传递 False 来禁用。

fetch_commit(url, commit, hide_url=True)

实验性:执行单个提交的抓取和检出,而不是完整克隆,这应该会更快。

参数:
  • url – 远程仓库的 URL。

  • commit – 要检出的提交引用。

  • hide_url – 从日志输出中隐藏 URL,以防止意外的凭据泄漏。可以通过传递 False 来禁用。

checkout(commit)

使用 git checkout <commit> 检出给定提交。

参数:

commit – 要检出的提交。

included_files()
运行 git ls-files --full-name --others --cached --exclude-standard 以获取列表

未被 .gitignore 忽略的文件

返回:

文件列表。

coordinates_to_conandata(repository=False)

从 Git 仓库捕获“url”和“commit”,调用 get_url_and_commit(),然后将这些信息存储在 conandata.yml 的“scm”键下。此信息可用于后续克隆和检出用于创建此包的精确源点,即使配方使用 exports_sources 作为嵌入源代码的机制,此信息也很有用。

参数:

repository – 默认情况下获取指定文件夹的提交,使用 repository=True 获取仓库的提交。

checkout_from_conandata_coordinates()

conandata.yml 读取“scm”字段,该字段必须至少包含“url”和“commit”,然后执行 clone(url, target="."), fetch <commit>,接着执行 checkout(commit)