{"id":21618888,"url":"https://github.com/nickderobertis/flexlate","last_synced_at":"2025-04-11T08:42:37.584Z","repository":{"id":39253683,"uuid":"435028391","full_name":"nickderobertis/flexlate","owner":"nickderobertis","description":"A CLI tool for managing project generator templates such as Cookiecutter and Copier","archived":false,"fork":false,"pushed_at":"2022-08-14T15:53:45.000Z","size":7001,"stargazers_count":22,"open_issues_count":39,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-23T17:19:02.732Z","etag":null,"topics":["cli","cookiecutter","copier","git","python","scaffolding","template"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nickderobertis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-12-04T23:08:43.000Z","updated_at":"2024-12-18T04:19:36.000Z","dependencies_parsed_at":"2022-08-29T06:50:53.422Z","dependency_job_id":null,"html_url":"https://github.com/nickderobertis/flexlate","commit_stats":null,"previous_names":[],"tags_count":52,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickderobertis%2Fflexlate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickderobertis%2Fflexlate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickderobertis%2Fflexlate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickderobertis%2Fflexlate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nickderobertis","download_url":"https://codeload.github.com/nickderobertis/flexlate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248362487,"owners_count":21091140,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","cookiecutter","copier","git","python","scaffolding","template"],"created_at":"2024-11-24T23:07:15.285Z","updated_at":"2025-04-11T08:42:37.553Z","avatar_url":"https://github.com/nickderobertis.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\n[![](https://codecov.io/gh/nickderobertis/flexlate/branch/master/graph/badge.svg)](https://codecov.io/gh/nickderobertis/flexlate)\n[![PyPI](https://img.shields.io/pypi/v/flexlate)](https://pypi.org/project/flexlate/)\n![PyPI - License](https://img.shields.io/pypi/l/flexlate)\n[![Documentation](https://img.shields.io/badge/documentation-pass-green)](https://nickderobertis.github.io/flexlate/)\n![Tests Run on Ubuntu Python Versions](https://img.shields.io/badge/Tests%20Ubuntu%2FPython-3.8%20%7C%203.9%20%7C%203.10-blue)\n![Tests Run on Macos Python Versions](https://img.shields.io/badge/Tests%20Macos%2FPython-3.8%20%7C%203.9%20%7C%203.10-blue)\n[![Github Repo](https://img.shields.io/badge/repo-github-informational)](https://github.com/nickderobertis/flexlate/)\n\n\n#  flexlate\n\n## Overview\n\nFlexlate is a composable, maintainable system for managing [project \nand file generator templates](https://nickderobertis.github.io/flexlate/faqs.html#what-is-a-project-or-file-generator).\n\nUpdate your projects generated from [`cookiecutter`](https://github.com/cookiecutter/cookiecutter) \n  and [`copier`](https://github.com/copier-org/copier) and compose projects \nfrom multiple templates.\n\n### Features\n\n- [**Update template outputs**](https://nickderobertis.github.io/flexlate/tutorial/updating.html) \n  after there are changes to the template\n  - When there is a conflict, it creates a \n    [Git merge conflict](https://nickderobertis.github.io/flexlate/core-concepts.html#real-merge-conflicts) \n    so that you can resolve it with your favorite tooling\n  - It keeps a history of the conflict resolution so you are not resolving \n    the same conflicts repeatedly\n  - Use [pre-built Github Actions](https://nickderobertis.github.io/flexlate/core-concepts.html#ci-workflows) \n    to automatically get a PR in your project after \n    the template has been updated\n- **Compose a project** with multiple templates\n  - [Add template sources and then you can apply outputs](https://nickderobertis.github.io/flexlate/tutorial/get-started/add-to-project.html)\n    anywhere with a simple \n    CLI command\n- **[Use your existing templates](https://nickderobertis.github.io/flexlate/faqs.html#what-templates-can-i-use-what-projects-can-i-generate-with-flexlate)**: \n  both [`cookiecutter`](https://github.com/cookiecutter/cookiecutter) \n  and [`copier`](https://github.com/copier-org/copier) templates are supported\n  - [Works with both local and remote templates](https://nickderobertis.github.io/flexlate/core-concepts.html#local-and-remote-template-sources). \n    You can even keep a template \n    in your project and be able to update outputs whenever it changes\n- **Apply it to your existing projects** with [a `bootstrap` functionality](https://nickderobertis.github.io/flexlate/tutorial/get-started/existing-project.html)\n- **Update your projects automatically on CI** with [official Github Actions](https://nickderobertis.github.io/flexlate/core-concepts.html#ci-workflows)\n- (planned) **Use flexlate projects as templates themselves**, enabling nested templates\n  and sharing data across templates\n- (planned) **Allow multiple templates to coordinate on specific files** in arbitrary \n  ways, e.g. think about applying a template and it adds its required packages \n  to `package.json` in a JS project\n\n### Use Cases\n\n- You want to create or already have projects that are generated from a `cookiecutter`\n  or `copier` template, and keep those projects up to date with changes in the template\n- You want to create a project from standard building blocks that can also be \n  updated systematically. For example think of something like a React component \n  with tests, a Java class and tests, or any set of files you want to generate\n\n### Locally or Remote With a Team\n\nIn either case, you can use Flexlate 100% locally even on a team project \nwithout anyone else knowing you are using it via \n[the `user` mode](https://nickderobertis.github.io/flexlate/core-concepts.html#project-and-user-configuration).\n\nBut Flexlate really shines when you embrace it fully and include it in\nyour remote repo. This enables you [use CI](https://nickderobertis.github.io/flexlate/core-concepts.html#ci-workflows) \nto automatically open PRs with \ntemplate updates and merge Flexlate branches.\n\n### Why Flexlate?\n\nFlexlate is born out of frustration with using project generator templates. \nYou generate your project from a template, but later update the template \nand need to bring the changes back to your project. There are only a \nfew tools for this and they do not have a great developer experience. \nFlexlate is [Git-native](https://nickderobertis.github.io/flexlate/core-concepts.html#git-native), \nso you resolve template conflicts in Git as you would any \nother merge conflicts. \n\nFurther, there is not really any ability to compose a project template from \nsmaller templates with any existing tools.\n\nCheck out a [much more detailed explanation and story](https://nickderobertis.github.io/flexlate/faqs.html#why-create-flexlate) \nas well as a \n[comparison to other tools](https://nickderobertis.github.io/flexlate/faqs.html#existing-tools-to-update-applied-templates). \n\n### How does it Work?\n\nFlexlate is [Git-native](https://nickderobertis.github.io/flexlate/core-concepts.html#git-native): \nit carries out all its operations via commits to \n[Git branches](https://nickderobertis.github.io/flexlate/core-concepts.html#branches-for-flexlate-operations). \nIt maintains two branches, one that contains the history of \nthe template output and the other than contains the merged output between\nyour project and the template. This means that you resolve any conflicts \nwith the template changes in Git and the merge conflict resolution is stored \nin the output branch.\n\nIt enables composability by using [config files](https://nickderobertis.github.io/flexlate/core-concepts.html#flexlate-json) \nto keep track of where \nmultiple templates should be rendered and with what data.\n\n[Learn more about Flexlate core concepts here.](https://nickderobertis.github.io/flexlate/core-concepts.html)\n\n## Getting Started\n\n### Documentation\n\nVisit the [documentation](https://nickderobertis.github.io/flexlate/) for \nmore detail on getting started. Start by learning about \n[Flexlate core concepts](https://nickderobertis.github.io/flexlate/core-concepts.html)\nbefore reading the [user guide](https://nickderobertis.github.io/flexlate/tutorial/index.html),\nwhich contains more detailed information on \n[getting started](https://nickderobertis.github.io/flexlate/tutorial/get-started/index.html).\n\nOr, you can keep reading this high-level overview for abbreviated \ngetting started steps.\n\n### Installing\n\nFlexlate is a Python package that includes the `fxt` command line utility. \nIf you do not have Python, you will need to [install it](https://www.python.org/downloads/) \nfirst (required version is `\u003e=3.8`).\n\nThe recommended way to install Flexlate is with [`pipx`](https://github.com/pypa/pipx),\nthough it can also be installed with `pip`.\n\n```\npipx install flexlate\n```\n\nOr, if you don't have/don't want to install `pipx`:\n\n```\npip install flexlate\n```\n\nBefore using Flexlate, you will also need to have \n[Git installed](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git). \n\nSee the [install guide](https://nickderobertis.github.io/flexlate/tutorial/get-started/installing.html) \nfor more information.\n\n### First Steps\n\nYour first steps will depend on what you are trying to accomplish. \nSee the [\"Next Steps\" section of the installing guide](https://nickderobertis.github.io/flexlate/tutorial/get-started/installing.html#next-steps) \nfor more information.\n\n#### New Project from a Template\n\nTo generate a new project from a template, use \n[`init-from`](https://nickderobertis.github.io/flexlate/commands.html#fxt-init-from), \ne.g.:\n\n```shell\nfxt init-from https://github.com/nickderobertis/copier-pypi-sphinx-flexlate\n```\n\nSee the user guide on [creating a new project](https://nickderobertis.github.io/flexlate/tutorial/get-started/new-project.html)\nfor more information.\n\n#### Existing Project from a Template\n\nTo add Flexlate to your project that is already generated from a `cookiecutter`\nor `cruft` template, use \n[`bootstrap`](https://nickderobertis.github.io/flexlate/commands.html#fxt-bootstrap), \ne.g.:\n\n```shell\nfxt bootstrap https://github.com/nickderobertis/copier-pypi-sphinx-flexlate\n```\n\nSee the user guide on [adding Flexlate to an existing project from a template](https://nickderobertis.github.io/flexlate/tutorial/get-started/existing-project.html)\nfor more information.\n\n#### Compose a Project from Multiple Templates\n\nYou can \n[add a template source](https://nickderobertis.github.io/flexlate/commands.html#fxt-add-source) \nand then [add as many outputs from that source](https://nickderobertis.github.io/flexlate/commands.html#fxt-add-output) \nas you want. \n\nBefore you can do this, you must \n[initialize a Flexlate project](https://nickderobertis.github.io/flexlate/commands.html#fxt-init):\n\n```shell\nfxt init\n```\n\nThen you can add the template source:\n\n```shell\nfxt add source https://github.com/nickderobertis/copier-pypi-sphinx-flexlate\n```\n\nThen you can apply the output anywhere in the project:\n\n```shell\nfxt add output copier-pypi-sphinx-flexlate\n```\n\nSee the user guide on [adding templates within an existing project](https://nickderobertis.github.io/flexlate/tutorial/get-started/add-to-project.html)\nfor more information.\n\n### Updating a Template\n\nSee the user guide on [updating a template](https://nickderobertis.github.io/flexlate/tutorial/updating.html)\nfor more information, but here's some quick info.\n\n#### Re-prompt Questions\n\nOnce you have updates in the template that you want to bring to your project,\nuse [the update command](https://nickderobertis.github.io/flexlate/commands.html#fxt-update):\n\n```shell\nfxt update\n```\n\nThis will prompt for all the questions again, using your previous answers \nas defaults. If there are new questions from the update, or if you want \nto change any of the answers, you should follow this flow. \n\n#### No Question Prompts\n\nIf instead you \nknow that there are only changes in the outputs and not questions/answers, \nyou can pass `--no-input` or `-n` to skip the questions:\n\n```shell\nfxt update -n\n```\n\n#### Saving your Work\n\nSee the user guide on [saving Flexlate updates](https://nickderobertis.github.io/flexlate/tutorial/saving.html)\nfor more information, but here's some quick info.\n\n##### Local Repo Flows\n\nIf you are following a local repo flow, then you can use the \n[`fxt merge`](https://nickderobertis.github.io/flexlate/commands.html#fxt-merge) command \nto merge the Flexlate feature branches into the Flexlate main branches. If \nyou are using a feature-branch flow, then you would want to run `fxt merge` just \nbefore merging your feature branch into the main branch. If you are simply \ncommititng to the main branch, just run `fxt merge` after any Flexlate command.\n\n##### Remote Repo/PR Flows\n\nIf you are merging PRs in your repo rather than following a local flow, then \nyou will want to \n[`fxt push feature`](https://nickderobertis.github.io/flexlate/commands.html#fxt-push-feature) \njust before/after your push your feature branch \nand open a PR. If you use the official Flexlate Github Merge Action, \nthe Flexlate branches will be merged automatically after the PR is merged.\n\n### Get Help\n\nYou can run `--help` on the end of any command to see documentation.\nYou will see similar output to what is in the \n[command reference](https://nickderobertis.github.io/flexlate/commands.html). \n\n```shell\n$ fxt --help\nUsage: fxt [OPTIONS] COMMAND [ARGS]...\n\n  fxt is a CLI tool to manage project and file generator templates.\n\n  [See the Flexlate documentation](\n  https://nickderobertis.github.io/flexlate/ ) for more information.\n\nOptions:\n  -v, --version         Show Flexlate version and exit\n  --install-completion  Install completion for the current shell.\n  --show-completion     Show completion for the current shell, to copy it or\n                        customize the installation.\n\n  --help                Show this message and exit.\n\nCommands:\n  add        Add template sources and generate new projects and files from...\n  bootstrap  Sets up a Flexlate project from an existing project that was...\n  check      Checks whether there are any updates available for the current...\n  config     Modify Flexlate configs via CLI\n  init       Initializes a flexlate project.\n  init-from  Generates a project from a template and sets it up as a...\n  merge      Merges feature flexlate branches into the main flexlate...\n  push       Push Flexlate branches to remote repositories.\n  remove     Remove template sources and previously generated outputs\n  sync       Syncs manual changes to the flexlate branches, and updates...\n  undo       Undoes the last flexlate operation, like ctrl/cmd + z for...\n  update     Updates applied templates in the project to the newest\n             versions...\n```\n\nPlease raise an issue if anything is confusing or does not work properly.\n\nSee a\n[more in-depth tutorial here.](\nhttps://nickderobertis.github.io/flexlate/tutorial/\n)\n\n## Development Status\n\nThis project is currently in early-stage development. There may be\nbreaking changes often. While the major version is 0, minor version\nupgrades will often have breaking changes.\n\n## Developing\n\nFirst ensure that you have `pipx` installed, if not, install it with `pip install pipx`.\n\nThen clone the repo and run `npm install` and `pipenv sync`. Run `pipenv shell`\nto use the virtual environment. Make your changes and then run `nox` to run formatting,\nlinting, and tests.\n\nDevelop documentation by running `nox -s docs` to start up a dev server.\n\nTo run tests only, run `nox -s test`. You can pass additional arguments to pytest\nby adding them after `--`, e.g. `nox -s test -- -k test_something`.\n\n## Author\n\nCreated by Nick DeRobertis. MIT License.\n\n## Links\n\nSee the\n[documentation here.](\nhttps://nickderobertis.github.io/flexlate/\n)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnickderobertis%2Fflexlate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnickderobertis%2Fflexlate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnickderobertis%2Fflexlate/lists"}