# footing - Keep projects in sync with templates
Footing provides templated project creation and management.
The main functionality of footing includes:
1. Creating new projects from [cookiecutter](https://cookiecutter.readthedocs.io/en/latest/) templates.
2. Listing all available templates under a git forge such as Github or Gitlab, along with listing all projects created from those templates.
3. Keeping projects up to date with the template as it changes.
A quick start is provided below. Be sure to go through the [installation](docs/installation.md) section before starting. It's also useful to read about [cookiecutter](https://cookiecutter.readthedocs.io/en/latest/) templates since they form the foundation of this tool.
## Quick Start
### Listing templates and projects
Footing manages projects that are started from templates (specifically, [cookiecutter](https://cookiecutter.readthedocs.io/en/latest/) templates). In order to see what templates are available for use, do:
footing ls <forge>
This will list all of the paths of templates that are available under a particular git forge. A git forge can be:
1. A Github user or organization, such as `github.com/OrganizationName`
2. A Gitlab group, such as `gitlab.com/Group` or `gitlab.com/Nested/Group`
Doing:
footing ls <forge> -l
will also display the extended description of the template.
To list all projects created with a template (and the project's descriptions), take the template path from `footing ls` and use it as the second argument like so::
footing ls <forge> <git@github.com:user/cookiecutter-template-path.git> -l
**Note** Be sure to provision a `GITHUB_API_TOKEN` or a `GITLAB_API_TOKEN` environment variable in order for this command to work. The environment variable needs to contain a personal access token to the appropriate forge.
**Note** This command only works with Gitlab when advanced search is enabled. See more [here](https://docs.gitlab.com/ee/user/search/advanced_search.html).
### Starting new projects
A new project can be set up from a template with:
footing setup <template_path>
What happens next is dependent on how the template is configured. By default, [cookiecutter](https://cookiecutter.readthedocs.io/en/latest/) will prompt the user for template parameters, defined in the `cookiecutter.json` file of the template repository. If any [cookiecutter hooks](http://cookiecutter.readthedocs.io/en/latest/advanced/hooks.html) are defined in the project, additional setup steps will happen that are specific to the type of project being started.
### Keeping your project up to date with the latest template
If a template is ever updated, changes can be pulled into a footing-created project with:
footing update
This will git merge the template changes into your repository into a special `_footing_update` branch. You will need to review the changes, resolve conflicts, and then `git add` and `git push` these changes yourself.
Sometimes it is desired that projects always remain up to date with the latest template - for example, ensuring that each project obtains a security patch to a dependency or doing an organization-wide upgrade to a new version of Python.
Using `footing update --check` from the repository will succeed if the project is up to date with the latest template or return a non-zero exit code if it isn't. This command can be executed as part of automated testing that happens in continuous integration in order to ensure all projects remain up to date with changes before being deployed.
**Note** Updating your project with the latest template does not result in [cookiecutter hooks](http://cookiecutter.readthedocs.io/en/latest/advanced/hooks.html) being executed again.
**Note** If a `_footing_update` branch already exists from a previous update, call `footing clean` to delete the branch.
### Switching your project to another template
Sometimes it is desirable to switch a project to another template, like when open sourcing a private package. Projects can be switched to another template with::
footing switch <template_path>
Similar to `footing update`, you will need to review the changes, resolve conflicts, and then `git add` and `git push` these changes.
**Note** Switching templates does not trigger any [cookiecutter hooks](http://cookiecutter.readthedocs.io/en/latest/advanced/hooks.html). Users must manually do any project setup and must similarly do any project teardown that might have resulted from the previously template. The authors have intentionally left out this convenience for now since footing currently has no way to spin down projects.
## Compatibility
`footing` is compatible with Python 3.9 - 3.13.
## Next Steps
[Check out the official docs for more examples on creating footing templates](https://footing.readthedocs.io).
Raw data
{
"_id": null,
"home_page": "https://github.com/AmbitionEng/footing",
"name": "footing",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.9.0",
"maintainer_email": null,
"keywords": null,
"author": "Wes Kendall",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/b1/50/b33162614bc8423cbba84f620848e55f780ca70c61fe2b75463cf7fd129b/footing-1.0.1.tar.gz",
"platform": null,
"description": "# footing - Keep projects in sync with templates\n\nFooting provides templated project creation and management.\n\nThe main functionality of footing includes:\n\n1. Creating new projects from [cookiecutter](https://cookiecutter.readthedocs.io/en/latest/) templates.\n2. Listing all available templates under a git forge such as Github or Gitlab, along with listing all projects created from those templates.\n3. Keeping projects up to date with the template as it changes.\n\nA quick start is provided below. Be sure to go through the [installation](docs/installation.md) section before starting. It's also useful to read about [cookiecutter](https://cookiecutter.readthedocs.io/en/latest/) templates since they form the foundation of this tool.\n\n## Quick Start\n\n### Listing templates and projects\n\nFooting manages projects that are started from templates (specifically, [cookiecutter](https://cookiecutter.readthedocs.io/en/latest/) templates). In order to see what templates are available for use, do:\n\n footing ls <forge>\n\nThis will list all of the paths of templates that are available under a particular git forge. A git forge can be:\n\n1. A Github user or organization, such as `github.com/OrganizationName`\n2. A Gitlab group, such as `gitlab.com/Group` or `gitlab.com/Nested/Group`\n\nDoing:\n\n footing ls <forge> -l\n\nwill also display the extended description of the template.\n\nTo list all projects created with a template (and the project's descriptions), take the template path from `footing ls` and use it as the second argument like so::\n\n footing ls <forge> <git@github.com:user/cookiecutter-template-path.git> -l\n\n**Note** Be sure to provision a `GITHUB_API_TOKEN` or a `GITLAB_API_TOKEN` environment variable in order for this command to work. The environment variable needs to contain a personal access token to the appropriate forge.\n\n**Note** This command only works with Gitlab when advanced search is enabled. See more [here](https://docs.gitlab.com/ee/user/search/advanced_search.html).\n\n### Starting new projects\n\nA new project can be set up from a template with:\n\n footing setup <template_path>\n\nWhat happens next is dependent on how the template is configured. By default, [cookiecutter](https://cookiecutter.readthedocs.io/en/latest/) will prompt the user for template parameters, defined in the `cookiecutter.json` file of the template repository. If any [cookiecutter hooks](http://cookiecutter.readthedocs.io/en/latest/advanced/hooks.html) are defined in the project, additional setup steps will happen that are specific to the type of project being started.\n\n### Keeping your project up to date with the latest template\n\nIf a template is ever updated, changes can be pulled into a footing-created project with:\n\n footing update\n\nThis will git merge the template changes into your repository into a special `_footing_update` branch. You will need to review the changes, resolve conflicts, and then `git add` and `git push` these changes yourself.\n\nSometimes it is desired that projects always remain up to date with the latest template - for example, ensuring that each project obtains a security patch to a dependency or doing an organization-wide upgrade to a new version of Python.\n\nUsing `footing update --check` from the repository will succeed if the project is up to date with the latest template or return a non-zero exit code if it isn't. This command can be executed as part of automated testing that happens in continuous integration in order to ensure all projects remain up to date with changes before being deployed.\n\n**Note** Updating your project with the latest template does not result in [cookiecutter hooks](http://cookiecutter.readthedocs.io/en/latest/advanced/hooks.html) being executed again.\n\n**Note** If a `_footing_update` branch already exists from a previous update, call `footing clean` to delete the branch.\n\n### Switching your project to another template\n\nSometimes it is desirable to switch a project to another template, like when open sourcing a private package. Projects can be switched to another template with::\n\n\tfooting switch <template_path>\n\nSimilar to `footing update`, you will need to review the changes, resolve conflicts, and then `git add` and `git push` these changes.\n\n**Note** Switching templates does not trigger any [cookiecutter hooks](http://cookiecutter.readthedocs.io/en/latest/advanced/hooks.html). Users must manually do any project setup and must similarly do any project teardown that might have resulted from the previously template. The authors have intentionally left out this convenience for now since footing currently has no way to spin down projects.\n\n## Compatibility\n\n`footing` is compatible with Python 3.9 - 3.13.\n\n## Next Steps\n\n[Check out the official docs for more examples on creating footing templates](https://footing.readthedocs.io).\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Keep templated projects in sync with their template",
"version": "1.0.1",
"project_urls": {
"Documentation": "https://footing.readthedocs.io",
"Homepage": "https://github.com/AmbitionEng/footing",
"Repository": "https://github.com/AmbitionEng/footing"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "78e0dd52badfb7d3a20c698f7fbd38b2a654f1e4d6d86bd0e960897afaa9f370",
"md5": "66d7cb1753b983568f7046d1de0751ea",
"sha256": "1c8d6c0640304dda1c7bdfe610e0d2f0935ae01fc8a315d0f6899544045b9c25"
},
"downloads": -1,
"filename": "footing-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "66d7cb1753b983568f7046d1de0751ea",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.9.0",
"size": 19236,
"upload_time": "2024-12-15T21:52:53",
"upload_time_iso_8601": "2024-12-15T21:52:53.270249Z",
"url": "https://files.pythonhosted.org/packages/78/e0/dd52badfb7d3a20c698f7fbd38b2a654f1e4d6d86bd0e960897afaa9f370/footing-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b150b33162614bc8423cbba84f620848e55f780ca70c61fe2b75463cf7fd129b",
"md5": "645fc0d1d1c2ea7d69e187ad086259c3",
"sha256": "3ea9cba0222d6516cb24af725a6dcfe8a4c715e7888c3f2fc7f4ac198b12f17c"
},
"downloads": -1,
"filename": "footing-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "645fc0d1d1c2ea7d69e187ad086259c3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.9.0",
"size": 16844,
"upload_time": "2024-12-15T21:52:55",
"upload_time_iso_8601": "2024-12-15T21:52:55.225588Z",
"url": "https://files.pythonhosted.org/packages/b1/50/b33162614bc8423cbba84f620848e55f780ca70c61fe2b75463cf7fd129b/footing-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-15 21:52:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AmbitionEng",
"github_project": "footing",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"circle": true,
"tox": true,
"lcname": "footing"
}
JSON
