File Handling¶
STRUCT provides flexible options for handling files and managing permissions.
File Properties¶
Basic Properties¶
- skip: Skip file/folder creation entirely
- skip_if_exists: Skip only if the file already exists
- permissions: Set custom file permissions
- content: Define file content inline
- file: Reference external file content
Skip Behavior¶
files:
- README.md:
skip: true # Never create this file
content: "This won't be created"
- config.yml:
skip_if_exists: true # Only create if it doesn't exist
content: "default: value"
File Permissions¶
Set custom permissions using octal notation:
files:
- scripts/deploy.sh:
permissions: '0755' # Executable script
content: |
#!/bin/bash
echo "Deploying..."
- secrets/api.key:
permissions: '0600' # Read-only for owner
content: "{{@ api_key @}}"
Content Sources¶
Inline Content¶
Define content directly in the YAML:
External Files¶
Reference local or remote files:
Remote File Protocols¶
STRUCT supports multiple protocols for fetching remote content:
HTTP/HTTPS¶
files:
- requirements.txt:
file: https://raw.githubusercontent.com/example/repo/main/requirements.txt
GitHub Protocols¶
Standard GitHub¶
GitHub HTTPS¶
GitHub SSH¶
Cloud Storage¶
Amazon S3¶
Google Cloud Storage¶
File Handling Strategies¶
Control how STRUCT handles existing files with the --file-strategy
option:
Available Strategies¶
- overwrite: Replace existing files (default)
- skip: Skip files that already exist
- append: Add content to existing files
- rename: Rename existing files with a suffix
- backup: Move existing files to backup directory
Usage Examples¶
# Skip existing files
struct generate --file-strategy=skip my-config.yaml ./output
# Backup existing files
struct generate --file-strategy=backup --backup=/tmp/backup my-config.yaml ./output
# Rename existing files
struct generate --file-strategy=rename my-config.yaml ./output
Note: The
file://
protocol is automatically added for.yaml
files, so these examples work with or without the explicit protocol.
Advanced Examples¶
Conditional File Creation¶
files:
- docker-compose.yml:
skip: "{{@ not use_docker @}}"
content: |
version: '3.8'
services:
app:
build: .
- Dockerfile:
skip_if_exists: true
permissions: '0644'
file: https://raw.githubusercontent.com/example/dockerfiles/main/python.Dockerfile
Dynamic Permissions¶
files:
- "scripts/{{@ script_name @}}.sh":
permissions: '0755'
content: |
#!/bin/bash
# {{@ script_description @}}
echo "Running {{@ script_name @}}"
Multiple Content Sources¶
files:
- README.md:
content: |
# {{@ project_name @}}
## Installation
```bash
pip install -r requirements.txt
```
- requirements.txt:
file: https://raw.githubusercontent.com/example/templates/main/python-requirements.txt
- .env.example:
file: file://./templates/env-template
Best Practices¶
- Use
skip_if_exists
for configuration files that shouldn't be overwritten - Set appropriate permissions for scripts and sensitive files
- Use remote files for standardized content like licenses and gitignores
- Combine strategies with command-line options for different deployment scenarios
- Test with
--dry-run
before applying changes to important directories