巴滕堡

巴滕堡是建立在Cookiecutter之上的工具，用于保持Cookiecutter项目与其父模板同步。在内部，巴滕堡依赖于Git来管理合并、差异比较和冲突解决。巴滕堡的第一个目标是向Cookiecutter提供升级功能。

安装

我们将battenberg发布到PyPI以方便使用。

pip install battenberg

如果您使用Mac OS X或Windows，请遵循pygit2文档中的安装指南，因为battenberg依赖于libgit2，需要先安装。 请安装libgit2 >= 1.0。

如果您使用SSH连接到git，请先安装libssh2 在安装libgit2之前!!如果您在Mac OS X上，您可能可以通过brew install libssh2来完成此操作。

先决条件

假设您的cookiecutter模板在根目录中包含一个.cookiecutter.json文件，或者您可以通过传递--context-file来覆盖其位置。请使用jsonify Jinja2扩展将cookiecutter模板上下文导出到.cookiecutter.json。

提示： battenberg 有一个问题，那就是随着cookiecutter模板和项目本身的差异增加，每个升级合并所需的手动解决冲突的量也会增加。为了最小化这些问题，通常建议将带有 generate_example 布尔标志的模板进行适配，这将禁用包含任何示例代码，例如，替换实现为 pass。

使用方法

安装一个 Cookiecutter 模板

battenberg [-O <root path>] [--verbose] install [--checkout v1.0.0] [--initial-branch main] <cookiecutter template path/URL>

• --checkout - 指定从cookiecutter模板仓库的目标引用（分支、标签或提交），如果未指定，则从模板仓库的默认分支推断。
• -O - 指定输出文件夹路径，默认为当前目录。
• --initial-branch - 新创建的 git 仓库的默认分支，如果未指定，则从模板仓库的默认分支推断。
• --verbose - 启用额外的调试日志。

使用最新版本的模板升级您的仓库

battenberg upgrade [--checkout v1.0.0] [--no-input] [--merge-target <branch, tag or commit>] [--context-file <context filename>]

• --checkout - 指定从cookiecutter模板仓库的目标引用（分支、标签或提交），如果未指定，则从模板仓库的默认分支推断。

• --no-input - 从 --context-file 读取模板上下文，而不是再次询问 cookiecutter 模板问题。

• --merge-target - 指定合并最终模板更新的位置。

• --context-file - 指定从哪里读取模板上下文，默认为 .cookiecutter.json。

  注意：如果您是模板所有者但每个cookiecut仓库都是独立拥有的，则 --merge-target 非常有用。传递给 --merge-target 的值应该是PR的源分支，该PR的目标是cookiecut仓库中的 main，这样他们可以批准任何更改。

将现有cookiecutter项目纳入

battenberg 的一个很棒的特性是，相对容易将您已经从现有模板cookiecutter的现有项目纳入。为此，您需要按照上面提到的 battenberg install 说明进行操作，但使用 -O 输出指定现有项目的目录，它将为您创建一个新的 template 分支，并尝试合并，就像升级操作一样。

一旦您完成了从 template -> main 的第一次合并，您就可以按照 battenberg upgrade 说明进行操作，就像最初使用 battenberg 生成一样。

高级设计

在高级上，battenberg 试图在上游模板项目和cookiecut项目之间提供连续的历史记录。它是通过维护一个不连续的 template 分支来实现的，battenberg 尝试将其与上游模板保持同步，因此它将不包含除替换模板值之外的项目特定更改。然后通过为每个拉取的模板更新执行 git merge --allow-unrelated-histories 命令将 template 的更改合并到 main 和其他分支。此合并提交应用于解决上游模板和专用项目之间的任何冲突。

这显示了在运行 battenberg install <template> 命令后立即的仓库结构

这显示了在运行 battenberg upgrade 命令在之前安装的项目后立即的仓库结构

开发

要设置环境，请运行

python3 -m venv env
source env/bin/activate

# Install in editable mode so you get the updates propagated.
pip install -e .

# If you want to be able to run tests & linting install via:
pip install -e ".[dev]"

然后要执行任何操作，只需使用 battenberg 命令，现在它应该在您的 $PATH 上。

要运行测试

pytest

要运行代码风格检查

flake8 --config flake8.cfg battenberg

将新版本发布到PyPI

提醒更新 HISTORY.md，其中包含任何更新的摘要，特别是破坏性更改。

我们使用GitHub Actions来部署到PyPI。我们将其限制为仅发布到 git tags。要发布，请运行

# Change to the appropriate commit you want to base the release on.
vi battenberg/__init__.py  # Update the version string.
git tag <version>
git push origin <version>

然后查看构建中是否有错误，最终它应该出现在 battenberg PyPI 项目上。

常见问题解答

• 我遇到了像 _pygit2.GitError: unsupported URL protocol 这样的错误，我该如何修复？

  可能你正在使用带有 ssh 的 git URL，并且在没有访问底层 libssh2 库的情况下安装了 pygit2。要测试这一点，请运行

  $ python -c "import pygit2; print(bool(pygit2.features & pygit2.GIT_FEATURE_SSH))"
  False
  

  要解决这个问题，请运行

  $ pip uninstall pygit2
  ...
  # Hopefully you have this, but this will install the compiler toolchain for OS X.
  $ xcode-select --install
  ...
  $ brew install libssh2
  ...
  $ brew install libgit2
  ...
  # The python wheels for Mac OS X for pygit2 are not built with SSH support by default so tell pip
  # to install pygit2 from source.
  $ pip install pygit2 --no-binary pygit2
  ...
  # Finally test out to ensure pygit2 picks up the SSH features.
  $ python -c "import pygit2; print(bool(pygit2.features & pygit2.GIT_FEATURE_SSH))"
  True
  

• 为什么您要使用新的 .cookiecutter.json 模式，而不是使用 replay 模式呢？

  坦白说，为了使这些功能的意图一致，实现相当复杂。在 .cookiecutter.json 方法中，我们旨在使模板状态位于项目级别而不是用户级别，这是 replay 功能的默认设置。虽然可以覆盖这种行为，但在当前的 cookiecutter API 中，这很复杂，并且需要上游更改，所以我们决定不尝试使这些功能一致。

• 为什么是 battenberg？

  这是对这个项目所站立的肩膀的致敬，cookiecutter 和 milhoja，以及本身也是一种美味的蛋糕。

致谢

原始代码 由 Raphael Medaer 编写，灵感来自 Abdó Roig-Maranges 的 原始想法。

许可协议

免费软件：Apache 软件许可证 2.0

发布历史

0.5.1 (2023-08-08)

• 更新 Python 版本到 3.9+

0.5.0 (2023-03-31)

• 更新 Python 版本到 3.7+

0.4.1 (2021-01-25)

• 当钩子失败时，抑制堆栈跟踪日志（见 #23）
• 确保我们与更新的 Repository.__init__ 构造函数兼容（见 #23）

0.4.0 (2020-10-13)

• 删除 master 作为默认的 git 目标分支术语，以促进公平感和归属感。相反，依赖于远程 HEAD 来推断默认分支命名约定。
• 在 battenberg install 中添加 --initial-branch 可选参数，以指定初始化新项目时创建的初始分支。

0.3.0 (2020-05-29)

• 更新 pygit2 依赖项到 >= 1.0，现在也可以依赖于 libgit2 >= 1.0。 （见 #18）
• 添加更好的调试日志（见 #16）

0.2.3 (2020-05-19)

• 重构在 cookiecutting 后删除顶级目录的代码，以避免冲突。（见 #15）
• 设置 pygit2 依赖项的上限（见 #14）

0.2.2 (2020-01-29)

• 修复了升级时停止注入上下文的回归问题。

0.2.1 (2020-01-29)

• 清理合并结果导致冲突时的错误消息。（见 #13）

0.2.0 (2019-10-29)

• 在升级期间添加了对 origin/template 分支的远程获取。（见 #12）

0.1.1 (2019-10-17)

• 恢复依赖于主线 cookiecutter 而不是 Zillow 分支。（见 #9）

0.1.0 (2019-10-10)

• 添加了从 .cookiecutter.json 读取模板上下文的功能。（见 #2）
• 添加了 --merge-target CLI 选项。（见 #4）
• 扩展了测试覆盖率，添加了通过 Travis CI 的 CI/CD。（见 #8）

在 v0.1.0 之前，battenberg 在 milhoja 项目下开发。