Warning
This project is still in development and may contain bugs. Use it at your own risk.
- Introduction
- Features
- Installation
- Quick Start
- Usage
- YAML Configuration
- Development
- License
- Funding
- Contributing
- Acknowledgments
- Known Issues
STRUCT is a powerful and flexible script designed to automate the creation of project structures based on YAML configurations. It supports template variables, custom file permissions, remote content fetching, and multiple file handling strategies to streamline your development setup process.
This is targeted towards developers, DevOps engineers, and anyone who wants to automate the creation of project structures. It can be used to generate boilerplate code, configuration files, documentation, and more.
- YAML Configuration: Define your project structure in a simple YAML file.
- Template Variables: Use placeholders in your configuration and replace them with actual values at runtime.
- Custom File Permissions: Set custom permissions for your files directly from the YAML configuration.
- Remote Content Fetching: Include content from remote files by specifying their URLs.
- File Handling Strategies: Choose from multiple strategies (overwrite, skip, append, rename, backup) to manage existing files.
- Dry Run: Preview the actions without making any changes to your file system.
- Configuration Validation: Ensure your YAML configuration is valid before executing the script.
- Verbose Logging: Get detailed logs of the script's actions for easy debugging and monitoring.
You can install STRUCT using pip:
pip install git+https://github.com/httpdss/struct.git
Alternatively, you can clone the repository and install it locally. See the Development section for more details.
You can use the Docker image to run the script without installing it on your system. See the Quick Start section for more details.
- Create a YAML configuration file for your project structure. See sample configuration here.
- Run the following command to generate the project structure:
docker run \
-v $(pwd):/workdir \
-u $(id -u):$(id -g) \
ghcr.io/httpdss/struct:main generate \
/workdir/example/structure.yaml \
/workdir/example_output
For testing, you can run an alpine Docker container and install the script inside it:
docker run -it --entrypoint="" python:3.10-alpine sh -l
Inside the container:
apk add python-pip git vim
pip install git+https://github.com/httpdss/struct.git
mkdir example
cd example/
touch structure.yaml
vim structure.yaml # copy the content from the example folder
struct generate structure.yaml .
Run the script with the following command:
usage: struct [-h] [--log LOG] [--dry-run] [--vars VARS] [--backup BACKUP] [--file-strategy {overwrite,skip,append,rename,backup}] [--log-file LOG_FILE] yaml_file base_path
-h
or--help
: Show help and exit--log
: Set the logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL). Default is INFO.--dry-run
: Perform a dry run without creating any files or directories.--vars
: Template variables in the formatKEY1=value1,KEY2=value2
.--backup
: Path to the backup folder.--file-strategy
: Strategy for handling existing files (overwrite, skip, append, rename, backup). Default is overwrite.--log-file
: Path to a log file.
struct generate /path/to/your/structure.yaml /path/to/your/output/directory
struct generate \
--log=DEBUG \
--dry-run \
--vars="project_name=MyProject,author_name=JohnDoe" \
--backup=/path/to/backup \
--file-strategy=rename \
--log-file=/path/to/logfile.log \
/path/to/your/structure.yaml \
/path/to/your/output/directory
Here is an example of a YAML configuration file:
structure:
- README.md:
content: |
# {{@ project_name @}}
This is a template repository.
- script.sh:
permissions: '0777'
content: |
#!/bin/bash
echo "Hello, {{@ author_name @}}!"
- LICENSE:
remote_file: https://raw.githubusercontent.com/nishanths/license/master/LICENSE
- src/main.py:
content: |
print("Hello, World!")
You can use template variables in your configuration file by enclosing them in {{@
and @}}
. For example, {{@ project_name @}}
will be replaced with the value of the project_name
variable at runtime.
If you need to define blocks you can use starting block notation {%@
and end block notation %@}
.
To define comments you can use the comment start notation {#@
and end comment notation @#}
.
file_name
: The name of the file being processed.file_directory
: The name of the directory of file that is being processed.
This filter fetches the latest release version of a GitHub repository. It takes the repository name as an argument.
structure:
- README.md:
content: |
# MyProject
Latest release: {{@ "httpdss/struct" | latest_release @}}
This uses PyGithub to fetch the latest release of the repository so setting the GITHUB_TOKEN
environment variable will give you access to private repositories.
If there is an error in the process, the filter will return LATEST_RELEASE_ERROR
.
NOTE: you can use this filter to get the latest release for a terraform provider. For example, to get the latest release of the aws
provider, you can use {{@ "hashicorp/terraform-provider-aws" | latest_release @}}
or datadog provider {{@ "DataDog/terraform-provider-datadog" | latest_release @}}
.
To get started with development, follow these steps:
- Clone the repository
- Create a virtual environment
python3 -m venv .venv
source .venv/bin/activate
- Install the dependencies
pip install -r requirements.txt
pip install -r requirements.dev.txt
This project is licensed under the MIT License - see the LICENSE file for details.
If you find this project helpful, please consider supporting it through donations: patreon/structproject
Contributions are welcome! Please open an issue or submit a pull request.
Special thanks to all the contributors who helped make this project possible.
- TBD