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.
pip install cruftVerified import paths — ran on the pinned version, not inferred.
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.
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.
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/*'`.
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>`.
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.
Ensure you have installed cruft: `pip install cruft` (or `poetry add cruft`, `pipenv install cruft`) and that your environment is correctly activated.
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.
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.
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.