Providing updates to cookiecutter projects.
Battenberg is a tool built atop of Cookiecutter to keep Cookiecut projects in sync with their parent templates. Under the hood, Battenberg relies on Git to manage the merging, diffing, and conflict resolution story. The first goal of Battenberg is to provide an upgrade feature to Cookiecutter.
battenberg to PyPI for easy consumption.
pip install battenberg
If you're on Mac OS X or Windows please follow the installation guides in the
as well as
battenberg relies on
libgit2 which needs to be installed first.
It is assumed that your cookiecutter template contains a
.cookiecutter.json file at the root directory, or you can override its location by
--context-file. Please use the
jsonify Jinja2 extension to dump the
cookiecutter template context to
Tip: One problem
battenberg has that as divergence between the cookiecutter template and the project itself increase as will the volume of
conflicts needed to be manually resolved for each upgrade merge. To minimize these it is often advisable to fit templates with a
generate_example boolean flag which will disable including any example code, instead replacing implementation with a
pass for example.
Install a Cookiecutter template:
battenberg [-O <root path>] [--verbose] install [--checkout v1.0.0] <cookiecutter template path/URL>
--checkout- Specifies a target reference (branch, tag or commit) from the cookiecutter template repo.
-O- Specifies an output folder path, defaults to the current directory.
--verbose- Enables extra debug logging.
Upgrade your repository with last version of a template:
battenberg upgrade [--no-input] [--context-file <context filename>] [--merge-target <branch, tag or commit>]
--context-file- Specifies where to read in the template context from, defaults to
--no-input- Read in the template context from
--context-fileinstead of asking the
cookiecuttertemplate questions again.
--merge-target- Specify where to merge the eventual template updates.
--merge-targetis useful to set if you are a template owner but each cookiecut repo is owned independently. The value you pass to
--merge-targetshould be the source branch for a PR that'd target
masterin the cookiecut repo so they can approve any changes.
Onboarding existing cookiecutter projects
A great feature of
battenberg is that it's relatively easy to onboard existing projects you've already cookiecut from an existing template.
To do this you need to follow the
battenberg install instructions above but use the
-O output to specify the directory of the existing
project and it'll create you a new
template branch and attempt to merge just like an upgrade operation.
Once you've completed your first merge from
master you can then follow the
battenberg upgrade instructions as though it was
At a high level
battenberg attempts to provide a continuous history between the upstream template project and the cookiecut project. It does this by maintaining a disjoint
battenberg attempts to keep in sync with the upstream template, it therefore will contain no project-specific changes beyond replacing the template values. Then changes
template are incorporated into the
master and other branches via a
git merge --allow-unrelated-histories command for each template update pulled in. This merge commit
should be used to resolve any conflicts between the upstream template and the specialized project.
This shows the repo structure immediately after running a
battenberg install <template> command
This shows the repo structure immediately after running a
battenberg upgrade command on the previously installed project
To get set up run:
python3 -m venv env source env/bin/activate # Install in editable mode so you get the updates propagated. pip install -e . # If you want to be able to run tests & linting install via: pip install -e ".[dev]"
Then to actually perform any operations just use the
battenberg command which should now be on your
To run tests:
To run linting:
flake8 --config flake8.cfg battenberg
Releasing a new version to PyPI
Reminder to update
HISTORY.md with a summary of any updates, especially breaking changes.
We utilize Travis CI's built in deploy to PyPI functionality. Specifically
we've limited it to just publish on
git tags. To release run:
# Change to the appropriate commit you want to base the release on. vi battenberg/__init__.py # Update the version string. git tag <version> git push origin <version>
Then watch Travis CI build for any errors, eventually it should appear on the
battenberg PyPI project.
Why are you using a new
.cookiecutter.jsonpattern instead of using the
Frankly the implementation was quite convoluted to get the intentions of these features to align. With the
.cookiecutter.jsonapproach we're intended for template state to live at the project level instead of at the user level which the
replayfunctionality defaults to. Overriding that behaviour, whilst possible was convoluted in the current
cookiecutterAPI and would require upstream changes so instead we decided against trying to align these features.
Free software: Apache Software License 2.0
- Adds in remote fetching of
origin/templatebranch during upgrades. (See #12)
- Revert back to relying on mainline
cookiecutterinstead of Zillow fork. (See #9)
- Add in support for reading template context from
.cookiecutter.json. (See #2)
- Add in
--merge-targetCLI option. (See #4)
- Expanded test coverage, added in CI/CD via Travis CI. (See #8)
Prior to v0.1.0
battenberg was developed under the
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
|Filename, size||File type||Python version||Upload date||Hashes|
|Filename, size battenberg-0.2.0.tar.gz (27.1 kB)||File type Source||Python version None||Upload date||Hashes View hashes|