What is Cruft
One of the most widely used tools for project scaffolding in the Python ecosystem is Cookiecutter. It lets you define reusable project templates using Jinja2. You generate new projects by filling in values like project_name or author. Cookiecutter is simple to use and mature, having been around for a long time.
However, Cookiecutter has a significant limitation: it only works at the time of project creation. Once a project has been generated, there’s no built-in way to track updates to the template. You also can’t apply those changes to existing projects. This becomes a problem when you’re working at scale.
Imagine you have a shared template used across dozens of services, pipelines, or internal tools. Over time, that template changes. Maybe you need to include new CI/CD jobs, adjust configuration defaults, or add new features. Without an automated way to propagate those changes, you’re left manually applying edits to every project. That’s manageable with two or three repositories. But it becomes nearly impossible when the number reaches dozens or hundreds.
This is the gap that Cruft fills. In our case, we had already been generating projects with a Cookiecutter template, so integrating Cruft was straightforward because it builds directly on top of Cookiecutter. It adds functionality to track and update any Cookiecutter-based projects. When you create a project using Cruft, it records metadata about the template. This includes the Git source, the exact commit used, and the context variables. All of this gets stored in a .cruft.json file inside the generated project. This link allows Cruft to later fetch updates from the template and apply them to your project.
Cruft in practice
When updating, Cruft checks the current state of your project against the latest version of the template. It regenerates the template with the same context and compares the result to your local codebase. Then it applies the differences. If changes conflict with local edits, you’re prompted to resolve them using your regular Git merge workflow.
That said, running cruft update and resolving conflicts manually for each repo is still a fair bit of work. To cut down on developer work, we integrated Cruft into our CI/CD pipeline. If there are any changes to the template, a merge request is automatically created once a week. This includes all changes since the last update. The responsible developer can then review, approve, and resolve any merge conflicts as needed.
The main challenge we ran into was how Cruft handles merge conflicts.
When a conflict occurs during an update, Cruft generates a .rej file to indicate that it couldn’t apply certain changes from the template. This caused a couple of problems for us.
First, the original file stays unchanged, even if the update partially fails. That means our CI/CD pipeline might still succeed, even though the update wasn’t fully applied. This is especially problematic because Cruft still updates the commit hash in .cruft.json to the latest version. This happens even if the template changes aren’t relevant to a specific repository. As a result, a merge request might be accepted and merged with unresolved conflicts. Important changes could be silently skipped.
Second, .rej files are inconvenient to deal with. Unlike conflict markers that show changes inline and are easy to resolve, .rej files require manual patching. For example, an inline conflict might look like this:
