{"id":8042,"library":"cruft","title":"Cruft: Template Management for Python Projects","description":"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.","status":"active","version":"2.16.0","language":"en","source_language":"en","source_url":"https://github.com/cruft/cruft","tags":["project management","cookiecutter","templating","boilerplate","ci-cd"],"install":[{"cmd":"pip install cruft","lang":"bash","label":"pip"},{"cmd":"poetry add cruft","lang":"bash","label":"Poetry"},{"cmd":"pipenv install cruft","lang":"bash","label":"Pipenv"}],"dependencies":[{"reason":"Cruft uses Cookiecutter as its template expansion engine, ensuring full compatibility with existing Cookiecutter templates.","package":"Cookiecutter"}],"imports":[{"symbol":"check","correct":"from cruft import check"},{"symbol":"create","correct":"from cruft import create"},{"symbol":"update","correct":"from cruft import update"},{"symbol":"link","correct":"from cruft import link"},{"symbol":"diff","correct":"from cruft import diff"}],"quickstart":{"code":"import os\n\n# Example: Create a new project from a template\n# In a real scenario, this would typically be run via CLI\n# cruft create https://github.com/cookiecutter/cookiecutter-pypackage.git\n\nprint(\"To create a new project:\")\nprint(\"  cruft create https://github.com/cookiecutter/cookiecutter-pypackage.git\")\nprint(\"\\nTo check if a project is up-to-date with its template (run in project root):\")\nprint(\"  cruft check\")\nprint(\"\\nTo update an existing project (run in project root):\")\nprint(\"  cruft update\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<2.0.0"},{"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/*'`.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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>`.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"`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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure you have installed cruft: `pip install cruft` (or `poetry add cruft`, `pipenv install cruft`) and that your environment is correctly activated.","cause":"The 'cruft' package is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'cruft'"},{"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.","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.","error":"Failed to apply the update. Project directory may have *.rej files reflecting merge conflicts with the update. Please resolve those conflicts manually."},{"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.","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.","error":"error: repository lacks the necessary blob to perform 3-way merge. Falling back to direct application..."},{"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.","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.","error":"CRUFT_CHECK_FAILURE: Project is not up to date with the template. Run `cruft update` to clean this mess up."}]}