Cruft: Template Management for Python Projects

2.16.0 · active · verified Thu Apr 16

Cruft is a Python library and CLI tool that allows developers to maintain essential boilerplate for packaging and building projects, separate from intentionally written code. Built on top of Cookiecutter, it enables automated project creation and, crucially, helps manage template updates and ensure project consistency over time by tracking template changes. The current version is 2.16.0, and it maintains an active release cadence with regular updates and feature enhancements.

Common errors

```
ModuleNotFoundError: No module named 'cruft'
```
cause The 'cruft' package is not installed in the current Python environment.

fix Ensure you have installed cruft: `pip install cruft` (or `poetry add cruft`, `pipenv install cruft`) and that your environment is correctly activated.
```
Failed to apply the update. Project directory may have *.rej files reflecting merge conflicts with the update. Please resolve those conflicts manually.
```
cause Cruft encountered conflicts when trying to merge changes from the template into your project, or a patch failed to apply. This usually happens when both the template and your project have modified the same lines of code.

fix Manually inspect the files with a `.rej` extension to understand the conflicts. Resolve the differences in your project files and then remove the `.rej` files. Once resolved, run `git add` and `git commit` to finalize the update.
```
error: repository lacks the necessary blob to perform 3-way merge. Falling back to direct application...
```
cause This error typically indicates that the Git repository history available to Cruft is insufficient to perform a full 3-way merge, often due to a shallow clone in CI/CD environments or a corrupted local repository.

fix If in CI/CD, configure your `actions/checkout` or equivalent step to perform a full clone (e.g., `fetch-depth: 0`). Locally, ensure your repository is not corrupted and has a complete history, e.g., by running `git pull --unshallow` if it was a shallow clone.
```
CRUFT_CHECK_FAILURE: Project is not up to date with the template. Run `cruft update` to clean this mess up.
```
cause `cruft check` exited with a non-zero status code (typically 1) because the project's boilerplate does not match the latest version of the template.

fix Run `cruft update` in the root of your project. Cruft will guide you through reviewing and applying the changes from the template. You can also use `cruft diff` to preview the changes.

Warnings

breaking Version 2.0.0 of Cruft involved a significant refactoring, moving from the 'hug' framework to 'typer' for its Python API. This change refactored the Python API, which could break integrations that directly imported and used Cruft's internal functions programmatically prior to 2.0.0. Initial Windows support was also dropped, though partially re-added in 2.10.0.
Fix: Review your code for direct imports and usage of `cruft`'s internal API. Adapt to the new `typer`-based API structure. For Windows users, ensure you are on version 2.10.0 or later, or use WSL.
gotcha When updating a project, certain files (e.g., test cases, `__init__.py` files) might not be suitable for automatic updates. If these files are modified by the template update, it can lead to conflicts or undesirable changes.
Fix: Use the `--skip` argument during `cruft create` or `cruft update` to define glob patterns for files to always skip, or add them to the `skip` section in your `.cruft.json` or `pyproject.toml` file. Example: `cruft create --skip '*/__init__.py' --skip 'tests/*'`.
gotcha Directly modifying the `.cruft.json` file without understanding its structure or deleting it can break Cruft's ability to track the template's state, leading to unexpected behavior during `check` or `update` operations.
Fix: Avoid manual editing of `.cruft.json` unless you are intimately familiar with its structure and purpose. For updating template variables, use `cruft update --variables-to-update` or `cruft update --variables-to-update-file`. If the file is corrupted, you might need to re-link the project using `cruft link <TEMPLATE_REPOSITORY>`.
gotcha `cruft update` can sometimes fail with 'error: repository lacks the necessary blob to perform 3-way merge. Falling back to direct application...' or 'error: patch failed' messages. This often occurs in CI/CD environments with shallow clones or incomplete Git history, where Cruft cannot properly compute the diff against the template's historical commits.
Fix: Ensure your CI/CD pipeline performs a full (non-shallow) clone of the repository, providing complete Git history. If conflicts occur, Cruft will create `.rej` files; resolve these manually. For automated workflows, consider strategies to pre-fetch template history or handle merge conflicts gracefully.

Install

pip install cruft pip
poetry add cruft Poetry
pipenv install cruft Pipenv

Imports

check
```
from cruft import check
```
create
```
from cruft import create
```
update
```
from cruft import update
```
link
```
from cruft import link
```
diff
```
from cruft import diff
```

Quickstart

Cruft is primarily a command-line interface tool. The quickstart involves using `cruft create` to generate a new project from a Cookiecutter template. Once a project is created, `cruft update` can be run within the project directory to apply changes from the template, and `cruft check` validates if the project is in sync with its template.

import os

# Example: Create a new project from a template
# In a real scenario, this would typically be run via CLI
# cruft create https://github.com/cookiecutter/cookiecutter-pypackage.git

print("To create a new project:")
print("  cruft create https://github.com/cookiecutter/cookiecutter-pypackage.git")
print("\nTo check if a project is up-to-date with its template (run in project root):")
print("  cruft check")
print("\nTo update an existing project (run in project root):")
print("  cruft update")

view raw JSON →