秘鲁

有时可能比复制粘贴更好。

秘鲁是一个将他人的代码包含到您的项目中的工具。它可以从任何地方获取代码 -- git, hg, svn, tarballs -- 并将文件放置在您喜欢的位置。秘鲁帮助您跟踪依赖项的确切版本，确保您的历史记录始终可重复。它还可以集成到您的脚本和Makefiles中，从而使您的构建过程保持简单且无懈可击。

为什么？

如果您使用make进行构建，当您切换分支或拉取新的提交时，您不需要做任何特别的事情。构建工具会自动检测这些更改。但是，如果您依赖于他人的代码，工具就不再那么自动化了。您需要记住何时执行git submodule update或go get -u或pip install -r。如果您忘记了一个步骤，可能会破坏您的构建，或者更糟的是，您可能会在未察觉的情况下构建错误的内容。

秘鲁希望您像自动化构建的其他部分一样自动化依赖项管理。它不会干扰您的源代码控制或安装任何全局软件，因此您只需在脚本开头添加它并忘记它即可。它将始终运行，并且您的依赖项永远不会不同步。简单，而且非常快速。

“秘鲁”这个名字，以及我们对可重复构建的热爱，灵感来源于亚马逊的巴西构建系统。它还恰好是"reup"的谐音。

安装

秘鲁支持Linux、macOS和Windows。它需要

• python 3.8或更高版本
• git，任何版本
• 可选，如果您需要从以下类型的仓库获取
  • hg，任何版本
  • svn，任何版本

git 是必需的，即使你不是在检索基于 git 的模块，因为 Peru 在内部使用它。

使用 pip

使用 pip 来安装它

pip install peru

请注意，根据您机器上的 Python 设置，您可能需要与 sudo 一起使用它，并且 Python 3 的 pip 可能被称为 pip3。

使用操作系统包管理器

在 Arch Linux 上，您可以从 AUR 安装 peru，链接为 此处。

Homebrew 为 macOS 和 Linux 提供了 Peru 公式。使用 brew install peru 将在 Homebrew 支持的最新 Python 版本上安装它。

入门指南

以下是从 Git Book 的第一个 git 子模块示例的 peru 版本。我们将把 Rack 库添加到我们的项目中。首先，创建一个类似这样的 peru.yaml 文件

imports:
    rack_example: rack/  # This is where we want peru to put the module.

git module rack_example:
    url: git://github.com/chneukirchen/rack.git

现在运行 peru sync。

这到底是怎么回事？

Peru 为您克隆了 Rack，并在 rack 目录下导入了一份副本。它还创建了一个名为 .peru 的神奇目录来存放该克隆和一些其他业务。如果您使用源代码控制，现在将这些目录添加到忽略列表（如 .gitignore）中是个好主意。您通常不想将这些目录提交。

运行 peru clean 将使导入的目录消失。再次运行 peru sync 将使其回来，这一次会快得多，因为 Peru 缓存了一切。

提高档次

为了一个更复杂的例子，让我们使用 Peru 来管理一些 dotfiles。我们非常喜欢 Solarized 颜色方案，并想在 ls 和 vim 中使用它。对于 ls，我们只需要 Peru 获取 Solarized dircolors 文件。（这将加载到像 .bashrc 这样的地方，不包括在这个示例中。）对于 vim，我们需要 Solarized vim 插件，我们还想要 Pathogen，它使得插件安装更为干净。以下是一个 peru.yaml

imports:
    # The dircolors file just goes at the root of our project.
    dircolors: ./
    # We're going to merge Pathogen's autoload directory into our own.
    pathogen: .vim/autoload/
    # The Solarized plugin gets its own directory, where Pathogen expects it.
    vim-solarized: .vim/bundle/solarized/

git module dircolors:
    url: https://github.com/seebi/dircolors-solarized
    # Only copy this file. Can be a list of files. Accepts * and ** globs.
    pick: dircolors.ansi-dark

curl module pathogen:
    url: https://codeload.github.com/tpope/vim-pathogen/tar.gz/v2.3
    # Untar the archive after fetching.
    unpack: tar
    # After the unpack, use this subdirectory as the root of the module.
    export: vim-pathogen-2.3/autoload/

git module vim-solarized:
    url: https://github.com/altercation/vim-colors-solarized
    # Fetch this exact commit, instead of master or main.
    rev: 7a7e5c8818d717084730133ed6b84a3ffc9d0447

dircolors 模块的包含内容被复制到我们的仓库的根目录。该 pick 字段限制只复制一个文件，即 dircolors.ansi-dark。

pathogen 模块使用 curl 类型而不是 git，其 URL 指向一个 tarball。（这是示例的目的。在现实生活中，您可能在这里也使用 git。）unpack 字段表示我们得到 tarball 的内容，而不是 tarball 文件本身。由于模块指定了 export 目录，因此复制到导入路径的是该目录而不是整个模块，即 .vim/autoload。结果是 Pathogen 的 autoload 目录与我们自己的目录合并，这是安装 Pathogen 的标准方式。

vim-solarized 模块被复制到 bundle 目录下的自己的目录中，这是 Pathogen 会查找它的地方。注意，它有一个明确的 rev 字段，它告诉 Peru 获取确切的修订版本，而不是默认分支（git 中的 master 或 main）。这是一个 Super Serious Best Practice™，因为它意味着您的依赖关系始终是一致的，即使您查看很久以前的提交。

您确实希望所有依赖项都有哈希值，但手动编辑这些值是痛苦的。下一节将介绍如何使其更容易。

神奇的更新

如果您运行 peru reup，Peru 将与您的所有上游仓库通信，获取它们的最新版本，然后使用任何更新编辑您的 peru.yaml 文件。如果您还没有将 peru.yaml 检入某种源代码控制，您可能应该首先这样做，因为重新上传将就地修改它。当我们重新上传上面的示例时，更改看起来像这样：

diff --git a/peru.yaml b/peru.yaml
index 15c758d..7f0e26b 100644
--- a/peru.yaml
+++ b/peru.yaml
@@ -6,12 +6,14 @@ imports:
 git module dircolors:
     url: https://github.com/seebi/dircolors-solarized
     pick: dircolors.ansi-dark
+    rev: a5e130c642e45323a22226f331cb60fd37ce564f

 curl module pathogen:
     url: https://codeload.github.com/tpope/vim-pathogen/tar.gz/v2.3
     unpack: tar
     export: vim-pathogen-2.3/autoload/
+    sha1: 9c3fd6d9891bfe2cd3ed3ddc9ffe5f3fccb72b6a

 git module vim-solarized:
     url: https://github.com/altercation/vim-colors-solarized
-    rev: 7a7e5c8818d717084730133ed6b84a3ffc9d0447
+    rev: 528a59f26d12278698bb946f8fb82a63711eec21

Peru 进行了三次更改

• 之前没有 rev 的 dircolors 模块现在获得了一个。对于默认的 git，这是当前的 master 或 main。要更改它，您可以将 reup 字段设置为不同分支的名称。
• pathogen 模块获得了一个 sha1 字段。与 git 不同，一个 curl 模块是普通的 HTTP，因此它只能下载 url 中的任何文件。但在下载完成后，它将检查这个散列，如果存在不匹配，将引发错误。
• vim-solarized 模块之前有一个散列，但现在已经更新了。同样，新值默认来自 master 或 main。

此时，您可能想为新提交的 peru.yaml 创建一个新提交以记录版本升级。您可以不时这样做以保持插件更新，并且您总是能够在历史记录中访问旧版本。

命令

• sync
  • 拉取您的导入。 sync 会提醒您而不是覆盖现有的或已修改的文件。使用 --force/-f 来告诉它您是认真的。
• clean
  • 删除导入的文件。与 sync 一样，使用 --force/-f 标志。
• reup
  • 使用新修订信息更新模块字段。对于 git、hg 和 svn，这会更新 rev 字段。对于 curl，这将设置 sha1 字段。您可以选择性地指定特定的模块名称作为参数。
• copy
  • 制作模块中所有文件的副本。您可以指定一个目录来放置它们，或者 Peru 将为您创建一个临时目录。您可以使用此功能查看通常不导入的模块，或者尝试不同的模块/规则组合（见下文 "规则"）。
• override
  • 使用本地目录路径替换模块的内容，通常是您克隆的同一仓库。这允许您在不需要将更改推送到上游或编辑 peru.yaml 的情况下测试导入模块的更改。

模块类型

git、hg、svn

用于克隆仓库。这些类型都提供相同的字段

• url：必需，任何由底层 VCS 支持的协议
• rev：可选，要获取的特定修订/分支/标签
• reup：可选，当运行 peru reup 时，从最新修订获取的分支/标签

git 类型还支持设置 submodules: false 以跳过获取 Git 子模块。否则默认包括在内。

curl

从 URL 下载文件。此类型由 Python 的标准库提供支持，而不是外部程序。

• url：必需，由 urllib 支持的任何类型（HTTP、FTP、file://）
• filename：可选，覆盖默认文件名
• sha1：可选，检查下载的文件是否与校验和匹配
• unpack：可选，tar 或 zip

Peru 包含一些其他类型，主要用于测试目的。有关 Bash 中实现的示例，请参阅 rsync。

创建新的模块类型

模块类型插件是最简单的脚本，只知道如何同步，可选地重新上传。Peru将它们外包出去，然后自己处理大部分缓存魔法，尽管插件也可以根据需要执行自己的缓存。例如，git和hg插件会跟踪它们克隆的仓库。Peru本身不需要知道如何做这件事。有关所有详细信息，请参阅架构：插件。

规则

某些字段（如rev和unpack）特定于某些模块类型。还有一些可以在任何模块中使用的字段，它们在获取后修改文件树。其中一些在上面的复杂示例中出现过

• copy：一个从源路径到目标路径的映射或多映射，用于复制。它像命令行上的cp一样工作，所以如果目标是一个目录，它会保留源文件名并将它复制到目标目录中。
• move：一个从源路径到目标路径的映射或多映射，用于移动。与上面的copy类似，但会删除源。
• drop：一个文件或目录，或一个文件和目录的列表，需要从模块中删除。路径可以包含*或**通配符。
• pick：一个文件或目录，或一个文件和目录的列表，需要包含在模块中。其余的所有内容都将被删除。路径可以包含*或**通配符。
• executable：一个文件或文件列表，需要设置为可执行，就像调用chmod +x一样。也接受通配符。
• export：Peru应将其视为模块树根的子目录。其余的所有内容都将被删除，包括父目录。

请注意，这些字段始终按照上述顺序生效，无论它们在peru.yaml中给出的顺序如何。例如，移动操作总是在选择之前执行。此外，这些字段不能重复给出。例如，不要使用两个不同的move字段（其中一个将被忽略），而应使用包含多个移动的单个move字段。实际上，由于这些字段被解析为字典中的键，它们不保留顺序且不能重复，因此事情是这样的。

除了在模块中使用这些字段外，您还可以在“命名规则”中使用它们，这允许您以多种方式转换一个模块。例如，如果您想从Tulip项目中获取asyncio子目录，但您还想将许可文件放在其他地方。而不是定义两个相同的模块，您可以使用一个模块和两个命名规则，如下所示

imports:
    tulip|asyncio: python/asyncio/
    tulip|license: licenses/

git module tulip:
    url: https://github.com/python/asyncio

rule asyncio:
    export: asyncio/

rule license:
    pick: COPYING

正如这个示例所示，命名规则声明得与模块非常相似，然后在imports列表中使用，语法为module|rule。那里的|运算符有点像shell管道，所以您甚至可以执行一些复杂的事情，如module|rule1|rule2，每个规则都应用于上一个规则的输出树。

递归

如果您导入了一个具有自己的Peru文件的模块，Peru可以包括该模块的导入，这与git子模块的行为类似，使用git clone --recursive。要启用此功能，请在模块定义中添加recursive: true。

您还可以直接导入在其他模块的peru.yaml文件中定义的模块。如果您的项目定义了一个名为foo的模块，并且foo中有一个定义了名为bar的模块的Peru文件，您可以在自己的导入中使用foo.bar。即使您从未实际导入foo，这也适用，并且不需要设置recursive: true。

配置

您可以设置几个标志和环境变量，以控制Peru放置内容的位置。标志始终具有优先级。

• --file=<file>：您的Peru YAML文件的路径。默认情况下，Peru在当前目录或其父目录中查找peru.yaml。此设置告诉Peru使用特定文件。如果设置了此设置，则必须也设置--sync-dir。
• --sync-dir=<dir>：所有 imports 解释的路径。也就是说，如果您将模块导入到 ./，则该模块的内容将直接放入同步目录。默认情况下，这是包含您的 peru.yaml 文件的目录。如果设置了此选项，则必须同时设置 --file。
• --state-dir=<dir>：Peru 存储所有状态元数据的目录，也是缓存目录的父目录。默认情况下，这是同步目录中的 .peru。您不应该在两个项目之间共享此目录，否则 peru sync 将会混乱。
• --cache-dir=<dir> 或 PERU_CACHE_DIR：Peru 存储所有已获取内容的目录。如果您有多个项目获取相同的依赖项，可以使用共享的缓存目录来加快速度。
• --file-basename=<name>：更改默认的 Peru 文件名（通常是 peru.yaml）。按照惯例，Peru 将在当前目录及其父目录中搜索该名称的文件，并使用该文件的父目录作为同步目录。与 --file 不兼容。

链接

• 讨论和公告（Google Group）
• 架构文档
• 使用 Peru 与 make