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:

files:
  - app.py:
      content: |
        #!/usr/bin/env python3
        print("Hello, {{@ project_name @}}!")

External Files¶

Reference local or remote files:

files:
  - LICENSE:
      file: https://raw.githubusercontent.com/nishanths/license/master/LICENSE

Remote File Protocols¶

STRUCT supports multiple protocols for fetching remote content (with caching and robust fallbacks):

HTTP/HTTPS¶

files:
  - requirements.txt:
      file: https://raw.githubusercontent.com/example/repo/main/requirements.txt

GitHub Protocols¶

STRUCT optimizes single-file fetches from GitHub by preferring raw.githubusercontent.com when possible and falling back to git clone/pull if necessary. You can control behavior with environment variables:

STRUCT_HTTP_TIMEOUT (seconds, default 10)
STRUCT_HTTP_RETRIES (default 2)
STRUCT_DENY_NETWORK=1 to skip HTTP attempts and use git fallback directly.

Standard GitHub¶

files:
  - .gitignore:
      file: github://github/gitignore/main/Python.gitignore

GitHub HTTPS¶

files:
  - workflow.yml:
      file: githubhttps://actions/starter-workflows/main/ci/python-app.yml

GitHub SSH¶

files:
  - private-config.yml:
      file: githubssh://company/private-repo/main/config/template.yml

Cloud Storage¶

Amazon S3¶

files:
  - data.csv:
      file: s3://my-bucket/data/template.csv

Google Cloud Storage¶

files:
  - config.json:
      file: gs://my-bucket/configs/default.json

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