cruft 2.15.0

热门贡献者

阅读最新文档 - 浏览GitHub代码仓库

cruft 允许您维护所有必要的样板代码，以便将项目打包和构建与您有意编写的代码分离。与现有的 Cookiecutter 模板完全兼容。

使用cruft从模板创建新项目非常简单

并且，随着模板的更新，更新它们也同样简单

许多项目模板实用工具存在，可以自动化代码的复制和粘贴以创建新项目。这看起来很棒！然而，一旦创建，大多数都会让你管理那些复制粘贴的代码，直到项目的生命周期结束。

cruft不同。它像其他工具一样自动化新项目的创建，但随后它还帮助你在项目的整个生命周期中管理样板代码。cruft确保您的代码与您从中来的模板保持同步。

主要功能

• Cookiecutter兼容：cruft使用 Cookiecutter 作为其模板扩展引擎。这意味着它与所有现有的 Cookiecutter 模板完全兼容。
• 模板验证：使用cruft check可以快速验证项目是否使用了模板的最新版本。此检查可以轻松添加到CI管道中，以确保项目保持同步。
• 自动模板更新：cruft自动化了将代码更新为与模板最新版本匹配的过程，使得在许多项目中利用模板改进变得容易。

安装

要开始使用，请使用Python包管理器安装cruft。

pip3 install cruft

或者

poetry add cruft

或者

pipenv install cruft

创建新项目

要从命令行使用cruft创建新项目，请运行cruft create PROJECT_URL。

例如

    cruft create https://github.com/timothycrosley/cookiecutter-python/

cruft将询问您创建新项目所需的任何问题。它将使用您的答案扩展提供的模板，然后返回放置扩展项目的目录。在幕后，cruft使用Cookiecutter来执行项目扩展。结果输出的唯一区别是一个包含模板使用的git hash以及指定的模板变量的.cruft.json文件。

更新项目

要更新使用cruft创建的现有项目，请在项目根目录中运行cruft update。如果有任何更新，cruft将让您在应用之前进行审查。如果您接受更改，cruft将应用它们到您的项目，并为您更新.cruft.json文件。

!!!技巧：有时某些文件并不适合更新。例如测试用例或__init__文件。您可以通过使用--skip cruft/__init__.py --skip tests参数生成项目或手动将它们添加到.cruft.json文件中的跳过部分，来告诉cruft在项目中始终跳过更新这些文件。

    {
        "template": "https://github.com/timothycrosley/cookiecutter-python",
        "commit": "8a65a360d51250221193ed0ec5ed292e72b32b0b",
        "skip": [
            "cruft/__init__.py",
            "tests"
        ],
        ...
    }

Or, if you have toml installed, you can add skip files directly to a `tool.cruft` section of your `pyproject.toml` file:

    [tool.cruft]
    skip = ["cruft/__init__.py", "tests"]

Note that it is possible to use glob patterns for selecting the files to skip:
    {
        "skip": [
            "**/__init__.py",
            "tests/*"
        ],
        ...
    }

更新模板变量的值

cruft还可以用于更新项目以使用模板变量的新值；避免需要使用cookiecutter从零开始重新生成项目。

例如，想象一个项目是在很久以前生成的，然后后来，您想更改某些模板变量的值，例如将use_some_feature更改为"yes"或将project_name更改为"new-project-name"。

以下有两种方法可以完成，如下所述。

通过命令行更新变量

如果您只有少数几个简单的变量，可以直接通过命令行执行更新。

这将将use_some_feature更改为"yes"，同时保持所有其他变量不变

cruft update --variables-to-update '{ "use_some_feature" : "yes" }'

这将同时将use_some_feature更改为"yes"并将project_name更改为"new-project-name"（同时保持所有其他变量不变）

cruft update --variables-to-update '{ "use_some_feature" : "yes", "project_name" : "new-project-name" }'

提供的参数必须是一个有效的JSON字符串（即使用双引号，没有尾随逗号等）。

通过Cruft文件更新变量

如果您更喜欢使用编辑器或者您有许多或复杂的变量，也可以通过提供更新的.cruft.json来执行更改。

# copy the existing cruft file to a temporary location (outside of your repo)
cp .cruft.json ~/tmp/new-cruft.json

# edit the file using your faviourite editor
edit ~/tmp/new-cruft.json

# perform the update
# (this will also update your original .cruft.json automatically)
cruft update --variables-to-update-file ~/tmp/new-cruft.json

检查项目

检查项目是否缺少模板更新就像运行cruft check一样简单。如果项目过时，将返回错误和退出代码1。cruft check可以添加到CI管道中，以确保项目不会意外漂移。

链接现有项目

您是否有使用Cookiecutter直接从模板创建的现有项目？您可以使用cruft link TEMPLATE_REPOSITORY将其链接到创建它的模板。

例如

    cruft link https://github.com/timothycrosley/cookiecutter-python/

然后，您可以指定项目已更新以保持一致的模板的最后一个提交，或者接受默认值，即使用模板的最新提交。

计算差异

随着时间的推移，您的基础模板可能会与实际的cookiecutter模板大相径庭。Cruft允许您快速查看本地项目与模板之间的差异。只需运行cruft diff即可，就像运行git diff一样，如果任何本地文件与模板不同，差异将在您的终端中以类似的方式显示。

cruft diff命令可以可选地接受一个--exit-code标志，如果发现任何差异，cruft将以非0的代码退出。您可以将此标志与.cruft.json中的skip部分结合使用，以创建更严格的CI检查，确保对模板的任何改进始终提交到上游。

使用GitHub Actions自动化更新

如果您要管理的仓库很多，可以使用GitHub Actions自动化更改检测过程。此示例每周一凌晨2点UTC运行，如果检测到更改，则创建一个新的拉取请求，维护者可以接受或拒绝这些更改。它创建了两个PR - 一个是将新文件拉入仓库的PR，另一个是仅更新.cruft.json文件的PR，这将导致拒绝上游仓库的更改。

自2022年1月起，注册表/组织必须明确授予创建拉取请求的权限。这可以在每个组织级别或每个注册表级别（个人项目）启用。有关详细信息，请参阅GitHub。

# /.github/workflows/cruft-update.yml
name: Update repository with Cruft
permissions:
  contents: write
  pull-requests: write
on:
  schedule:
    - cron: "0 2 * * 1" # Every Monday at 2am
jobs:
  update:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: true
      matrix:
        include:
          - add-paths: .
            body: Use this to merge the changes to this repository.
            branch: cruft/update
            commit-message: "chore: accept new Cruft update"
            title: New updates detected with Cruft
          - add-paths: .cruft.json
            body: Use this to reject the changes in this repository.
            branch: cruft/reject
            commit-message: "chore: reject new Cruft update"
            title: Reject new updates detected with Cruft
    steps:
      - uses: actions/checkout@v3

      - uses: actions/setup-python@v4
        with:
          python-version: "3.10"

      - name: Install Cruft
        run: pip3 install cruft

      - name: Check if update is available
        continue-on-error: false
        id: check
        run: |
          CHANGES=0
          if [ -f .cruft.json ]; then
            if ! cruft check; then
              CHANGES=1
            fi
          else
            echo "No .cruft.json file"
          fi

          echo "has_changes=$CHANGES" >> "$GITHUB_OUTPUT"

      - name: Run update if available
        if: steps.check.outputs.has_changes == '1'
        run: |
          git config --global user.email "you@example.com"
          git config --global user.name "GitHub"

          cruft update --skip-apply-ask --refresh-private-variables
          git restore --staged .

      - name: Create pull request
        if: steps.check.outputs.has_changes == '1'
        uses: peter-evans/create-pull-request@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          add-paths: ${{ matrix.add-paths }}
          commit-message: ${{ matrix.commit-message }}
          branch: ${{ matrix.branch }}
          delete-branch: true
          branch-suffix: timestamp
          title: ${{ matrix.title }}
          body: |
            This is an autogenerated PR. ${{ matrix.body }}

            [Cruft](https://cruft.github.io/cruft/) has detected updates from the Cookiecutter repository.

为什么创建cruft？

自从我第一次看到

希望您也能觉得cruft有用！

~Timothy Crosley