{ "info": { "author": "Zillow", "author_email": "", "bugtrack_url": null, "classifiers": [ "Development Status :: 2 - Pre-Alpha", "Intended Audience :: Developers", "License :: OSI Approved :: Apache Software License", "Natural Language :: English", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.6", "Programming Language :: Python :: 3.7", "Programming Language :: Python :: 3.8" ], "description": "# Battenberg\n\n[![image](https://img.shields.io/pypi/v/battenberg.svg)](https://pypi.python.org/pypi/battenberg)\n[![image](https://img.shields.io/travis/zillow/battenberg.svg)](https://travis-ci.org/zillow/battenberg)\n\nBattenberg is a tool built atop of [Cookiecutter](https://github.com/audreyr/cookiecutter) to keep Cookiecut projects\nin sync with their parent templates. Under the hood, Battenberg relies on Git to manage the merging, diffing, and\nconflict resolution story. The first goal of Battenberg is to provide an *upgrade* feature to Cookiecutter.\n\n## Installation\n\nWe publish `battenberg` to [PyPI](https://pypi.org/project/battenberg/) for easy consumption.\n\n```bash\npip install battenberg\n```\n\nIf you're on Mac OS X or Windows please follow the [installation guides](https://www.pygit2.org/install.html#) in the `pygit2` documentation\nas well as `battenberg` relies on `libgit2` which needs to be installed first. **Please install `libgit2 >= 1.0`.**\n\nIf you use SSH to connect to `git`, please also install `libssh2` **prior to installing `libgit2`!!** Most like you can do this via `brew install libssh2`\nif you are on Mac OS X.\n\n## Prerequistes\n\nIt is assumed that your cookiecutter template contains a `.cookiecutter.json` file at the root directory, or you can override its location by\npassing in `--context-file`. Please use the [`jsonify`](https://github.com/cookiecutter/cookiecutter/pull/791) Jinja2 extension to dump the\n`cookiecutter` template context to `.cookiecutter.json`.\n\n**Tip:** One problem `battenberg` has that as divergence between the cookiecutter template and the project itself increase as will the volume of\nconflicts needed to be manually resolved for each upgrade merge. To minimize these it is often advisable to fit templates with a\n`generate_example` boolean flag which will disable including any example code, instead replacing implementation with a\n[`pass`](https://docs.python.org/3/reference/simple_stmts.html#the-pass-statement) for example.\n\n## Usage\n\nInstall a [Cookiecutter](https://github.com/audreyr/cookiecutter) template:\n\n```bash\nbattenberg [-O ] [--verbose] install [--checkout v1.0.0] [--initial-branch main] \n```\n\n* `--checkout` - Specifies a target reference (branch, tag or commit) from the cookiecutter template repo, if not specified is it inferred from the default branch for the template repo.\n* `-O` - Specifies an output folder path, defaults to the current directory.\n* `--initial-branch` - The default branch for the newly created `git` repo, if not specified is it inferred from the default branch for the template repo.\n* `--verbose` - Enables extra debug logging.\n\nUpgrade your repository with last version of a template:\n\n```bash\nbattenberg upgrade [--checkout v1.0.0] [--no-input] [--merge-target ] [--context-file ]\n```\n\n* `--checkout` - Specifies a target reference (branch, tag or commit) from the cookiecutter template repo, if not specified is it inferred from the default branch for the template repo.\n* `--no-input` - Read in the template context from `--context-file` instead of asking the `cookiecutter` template questions again.\n* `--merge-target` - Specify where to merge the eventual template updates.\n* `--context-file` - Specifies where to read in the template context from, defaults to `.cookiecutter.json`.\n\n *Note: `--merge-target` is useful to set if you are a template owner but each cookiecut repo is owned independently. The value you pass*\n *to `--merge-target` should be the source branch for a PR that'd target `main` in the cookiecut repo so they can approve any changes.*\n\n## Onboarding existing cookiecutter projects\n\nA great feature of `battenberg` is that it's relatively easy to onboard existing projects you've already cookiecut from an existing template.\nTo do this you need to follow the `battenberg install` instructions above but use the `-O` output to specify the directory of the existing\nproject and it'll create you a new `template` branch and attempt to merge just like an upgrade operation.\n\nOnce you've completed your first merge from `template` -> `main` you can then follow the `battenberg upgrade` instructions as though it was\ngenerated using `battenberg` initially.\n\n## High-level design\n\nAt 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 `template`\nbranch which `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\nto the `template` are incorporated into the `main` and other branches via a `git merge --allow-unrelated-histories` command for each template update pulled in. This merge commit\nshould be used to resolve any conflicts between the upstream template and the specialized project.\n\n![A new project in battenberg](https://github.com/zillow/battenberg/raw/main/img/new.png)\n\n*This shows the repo structure immediately after running a `battenberg install