Package: retrocookie
Retrocookie updatesCookiecuttertemplates with changes from generated projects.When developing Cookiecutter templates,
you often need to work in a generated project rather than the template itself.
Reasons for this include the following:You need to run the Continuous Integration suite for the generated projectYour development tools choke when running on the templated projectAny changes you make in the generated project
need to be backported into the template,
carefully replacing expanded variables fromcookiecutter.jsonby templating tags,
and escaping any use of{{and}}or other tokens with special meaning in Jinja.✨ Retrocookie helps you in this situation. ✨It is designed to fetch commits from the repository of a generated project,
and import them into your Cookiecutter repository,
rewriting them on the fly to insert templating tags,
escape Jinja-special constructs,
and place files in the template directory.Under the hood,
Retrocookie rewrites the selected commits usinggit-filter-repo,
saving them to a temporary repository.
It then fetches and cherry-picks the rewritten commits
from the temporary repository into the Cookiecutter template,
usingpygit2.Maybe you’re thinking,
how can this possibly work?
One cannot reconstruct a Jinja template from its rendered output.
However, simple replacements of template variables work well in practice
when you’re only importing a handful of commits at a time.Important:Retrocookie relies on a.cookiecutter.jsonfile in the generated project
to work out how to rewrite commits.
This file is similar to thecookiecutter.jsonfile in the template,
but contains the specific values chosen during project generation.
You can generate this file by putting it into the template directory in the Cookiecutter,
with the following contents:{{cookiecutter|jsonify}}RequirementsPython 3.7+git >= 2.22.0InstallationYou can installRetrocookieviapipfromPyPI:$pipinstallretrocookieOptionally, install theprextra for theretrocookie-prcommand:$pipinstallretrocookie[pr]ExampleHere’s an example to demonstrate the general workflow.To start with, we clone the repository of your Cookiecutter template.
For this example, I’ll use my ownHypermodern Python Cookiecutter.$gitclonehttps://github.com/cjolowicz/cookiecutter-hypermodern-pythonNext, we’ll create a project from the template,
and set up a git repository for it:$cookiecutter--no-inputcookiecutter-hypermodern-python$cdhypermodern-python$gitinit$gitadd.$gitcommit--message="Initial commit"Let’s open a feature branch in the project repository,
and make a fictitious change involving the default project namehypermodern-python:$gitswitch--createadd-example$echo'# hypermodern-python'>EXAMPLE.md$gitaddEXAMPLE.md$gitcommit--message="Add example"Back in the Cookiecutter repository,
we can now invoke retrocookie to import the changes from the feature branch:$cd../cookiecutter-hypermodern-python$retrocookie--branchadd-example--create../hypermodern-pythonAgit showin the Cookiecutter shows the file under the template directory,
on a branch named as in the original repository,
with the project name replaced by a Jinja tag:commit abb4f823b9f1760e3a678c927ec9797c0a40a9b6 (HEAD -> add-example)Author: Your Name <your.name@example.com>Date:   Fri Dec 4 23:40:41 2020 +0100Add examplediff --git a/{{cookiecutter.project_name}}/EXAMPLE.md b/{{cookiecutter.project_name}}/EXAMPLE.mdnew file mode 100644index 0000000..a158618--- /dev/null+++ b/{{cookiecutter.project_name}}/EXAMPLE.md@@ -0,0 +1 @@+# {{cookiecutter.project_name}}UsageThe basic form:$ retrocookie <repository> [<commits>...]
$ retrocookie <repository> -b <branch> [--create]The<repository>is a filesystem path to the source repository.
For<commits>, seegitrevisions(7).ImportHEADfrom<repository>:$ retrocookie <repository>Import the last two commits:$ retrocookie <repository> HEAD~2..Import by commit hash:$ retrocookie <repository> 53268f7 6a3368a c0b4c6cImport commits from branchtopic:$ retrocookie <repository> --branch=topicEquivalently:$ retrocookie <repository> master..topicImport commits fromtopicinto a branch with the same name:$ retrocookie <repository> --branch=topic --createEquivalently, using short options:$ retrocookie <repository> -cb topicImport commits from branchtopic, which was branched off1.0:$ retrocookie <repository> --branch=topic --upstream=1.0Equivalently:$ retrocookie <repository> 1.0..topicImportHEADinto a new branchtopic:$ retrocookie <repository> --create-branch=topicPlease see theCommand-line Referencefor further details.Importing pull requests from generated projects with retrocookie-prYou can import pull requests from a generated project to the project template,
assuming their repositories are onGitHub.
This requires activating theprextra when installing withpip:$ pip install retrocookie[pr]The commandretrocookie-prhas the basic form:$ retrocookie-pr [-R <repository>] [<pr>...]
$ retrocookie-pr [-R <repository>] --user=<user>
$ retrocookie-pr [-R <repository>] --allCommand-line arguments specify pull requests to import, by number or by branch.
Pull requests from forks are currently not supported.Use the-R<repository>option to specify the GitHub repository of the generated project
from which the pull requests should be imported.
Provide the full name of the repository on GitHub in the formowner/name.
The owner can be omitted if the repository is owned by the authenticated user.
This option can be omitted when the command is invoked from a local clone.You can also select pull requests by specifying the user that opened them, via the--useroption.
This is handy for importing automated pull requests, such as dependency updates fromDependabot.Use the--alloption to import all open pull requests in the generated project.You can update previously imported pull requests by specifying--force.
By default,retrocookie-prrefuses to overwrite existing pull requests.The command needs apersonal access tokento access the GitHub API.
(This token is also used to push to the GitHub repository of the project template.)
You will be prompted for the token when you invoke the command for the first time.
On subsequent invocations, the token is read from the application cache.
Alternatively, you can specify the token using the--tokenoption or theGITHUB_TOKENenvironment variable;
both of these methods bypass the cache.Use the--openoption to open each imported pull request in a web browser.Please see theCommand-line Referencefor further details.ContributingContributions are very welcome.
To learn more, see theContributor Guide.LicenseDistributed under the terms of theMITlicense,Retrocookieis free and open source software.IssuesIf you encounter any problems,
pleasefile an issuealong with a detailed description.CreditsThis project was generated from@cjolowicz’sHypermodern Python Cookiecuttertemplate.