Git¶

Git 辅助类是 git 命令的一个薄封装。它可以用于不同的目的

在 set_version() 方法中获取当前的标签，并将其赋值给 self.version
在第三方或开源软件包 recipe 的 source() 方法中克隆源码 (通常，优先使用 download() 或 get() 来获取发布的 tarball)
在 export() 方法中捕获你自己的软件包源码的 "scm" 坐标 (url, commit)，以便稍后能够从源码重现构建，并在 source() 方法中检索代码。参见 git-scm 捕获示例。

Git() 构造函数接收当前文件夹作为参数，但如果需要可以更改它，例如，在 source() 中克隆某个 repo 的源码

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 – 要从 "dirty" 检查中排除的文件。它将与配置 core.scm:excluded 组合（配置具有更高的优先级）。它是一个 fnmatch 的模式列表。

run(cmd, hidden_output=None)¶

执行 git <cmd>

返回值:: 命令的控制台输出。

get_commit(repository=False)¶

参数:: repository – 默认情况下获取定义文件夹的 commit，使用 repo=True 来获取仓库的 commit。
返回值:: 当前的 commit，使用 git rev-list HEAD -n 1 -- <folder>。返回最新的 commit，不考虑本地未提交的更改。

get_remote_url(remote='origin')¶

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

警告！ 请注意，此方法将从 git remote -v 获取输出。如果你将令牌或凭据添加到 URL 中的远程仓库，它们将被暴露。凭据不应添加到 git 远程仓库定义中，而应使用凭据管理器或类似的机制。如果你仍然想使用此方法，你有责任从结果中删除凭据。

参数:: remote – 远程 git 仓库的名称（默认为 'origin'）。
返回值:: 远程 git 仓库的 URL。

commit_in_remote(commit, remote='origin')¶

检查给定的 commit 是否存在于远程仓库中，使用 branch -r --contains <commit> 并检查在该远程仓库中是否存在分支。

参数:

commit – 要检查的 Commit。
remote – 远程 git 仓库的名称（默认为 'origin'）。

返回值:

如果给定的 commit 存在于远程仓库中，则为 True，否则为 False。

is_dirty(repository=False)¶

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

参数:: repository – 默认情况下检查当前文件夹是否是 dirty 的。如果 repository=True，它将检查根仓库文件夹，而不是当前的文件夹。
返回值:: 如果当前文件夹是 dirty 的，则为 True。否则，为 False。

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

这是一个高级方法，它返回当前的 commit 和远程仓库的 url。该方法旨在捕获包创建的当前远程坐标，以便以后可以从同一 commit 再次从源构建。这是该行为

如果仓库是 dirty 的，它将引发异常。捕获 dirty 的东西的坐标是没有意义的，因为它将不可重现。如果有本地更改，并且用户想要测试本地 conan create，则应首先提交更改（本地，而不是推送更改）。
如果仓库不是 dirty 的，但是给定的远程仓库中不存在 commit，则该方法将返回该 commit 和本地用户 checkout 的 URL。这样，可以在将一些更改推送到远程仓库之前，本地创建一个 conan create 包，测试一切正常。
如果仓库不是 dirty 的，并且 commit 存在于指定的远程仓库中，它将返回该 commit 和远程仓库的 url。

警告！ 请注意，此方法将从 git remote -v 获取输出。如果你将令牌或凭据添加到 URL 中的远程仓库，它们将被暴露。凭据不应添加到 git 远程仓库定义中，而应使用凭据管理器或类似的机制。如果你仍然想使用此方法，你有责任从结果中删除凭据。

参数:

remote – 远程 git 仓库的名称（默认为 'origin'）。
repository – 默认情况下获取定义文件夹的 commit，使用 repo=True 来获取仓库的 commit。

返回值:

(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)¶

实验性的：执行一个单 commit 的 fetch 和 checkout，而不是完整的克隆，应该更快。

参数:

url – 远程仓库的 URL。
commit – 要 checkout 的 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” 键下。此信息以后可用于克隆和检出用于创建此软件包的确切源点，即使 recipe 使用 exports_sources 作为嵌入源的机制也很有用。

参数:: repository – 默认情况下获取已定义文件夹的 commit，使用 repository=True 获取仓库的 commit。

checkout_from_conandata_coordinates()¶: 从 conandata.yml 读取 “scm” 字段，该字段必须至少包含 “url” 和 “commit”，然后执行 clone(url, target="."), fetch <commit>, 随后执行 checkout(commit)。