Update cookiecutter-generated files with cruft#
Ref: original docs and github repo.
Setup: cruft link#
Install: pip install cruft.
If this is your first time using cruft, you have to set it up using the cruft link command. You have to specify the URL of your cookiecutter on GitHub.
cruft link https://github.com/neuroinformatics-unit/python-cookiecutter
At this point, cruft will ask you the same questions you were asked when you first generated the repo with cookiecutter. Enter the same answers you did before, but make sure to enter “provide later” when it prompts for “github_repository_url”.
Why 🤷🏻♀️?
I have found that if you enter the correct link to your package’s repo in github_repository_url field, the command cruft diff fails 🤷🏻♀️
After you have answered all cookiecutter’s questions, cruft will prompt you to specify the commit hash, i.e. the older version of cookiecutter you had used to generate the repo. For now, we have to do this manually by searching the history. Example commit hash: 9daec12bffbc32da6a252605c5e67c90028fefc0. We need to do this because cruft will compare your repo with the template, and will only update the files that have changed since the commit hash you specify.
After you have entered the commit hash, cruft will create a .cruft.json file in your repo containing the URL to the cookicutter, the commit hash, and your responses to cookiecutter’s prompts. Please track the changes to this file with git.
Apply updates: cruft diff & cruft update#
Now that .cruft.json exists, we can run cruft diff to see the changes between your repo and the template. At this point, you could manually apply the subset of the changes you want.
You can also ask cruft to apply the changes for you by running cruft update. You will be prompted to confirm the changes with y before they are applied. You can also press v to see the changes before confirming.
Note
cruft update will not delete the files you have added to your repo since its creation. It only cares about the files that were generated by cookiecutter.
It also doesn’t delete the files that have since been removed from the template. You have to do this manually.
In case cruft update is not able to apply all the changes, it will create a your_file.rej file for each conflicting file. Based on these files’ contents you can then apply changes manually. Don’t forget to remove the .rej files when you’re done. This is a bit tedious, but it should get easier with more frequent updates.
When cruft update is done, you will notice that the .cruft.json file has been updated with the new commit hash of the template. Future updates will be based on this commit hash.
cruft check will check if your repo is up to date with the template and just give you a boolean response.
Commit#
Once you are satisfied, commit the changes to a new branch and open a PR to merge it into main.
Now, check if your GitHub actions fail… 🤦🏻♀️ If everything is fine, you can merge the PR. 🎉 If not, you will have to fix the errors and repeat the process. 😱