ha-template-migration/README.md

# Home Assistant Legacy Template Migration

**✨ v2 UPDATE**: Fixed script now properly handles templates in included files (`sensors.yaml`, `binary_sensors.yaml`)!

Automatically migrates legacy `platform: template` syntax to modern `template:` syntax in Home Assistant.

## What's New in v2

The original script looked only at `configuration.yaml`, but many Home Assistant configurations use `!include` directives to split sensors into separate files like:
- `binary_sensors.yaml`
- `sensors.yaml`  
- `packages/*.yaml`

**v2 fixes:**
- ✅ Scans ALL .yaml files in `/config/` and `/config/packages/`
- ✅ Handles `- platform: template` (list item format with dash)
- ✅ Properly extracts sensors from `sensors:` blocks  
- ✅ Handles multiline templates with `>` operator
- ✅ Correct indentation for modern `template:` format
- ✅ Counts sensors correctly from included files

## Why Migrate?

Home Assistant is deprecating the legacy `platform: template` syntax in favor of modern `template:` syntax. Starting in **version 2026.6**, the old syntax will stop working.

This script safely migrates all your legacy template definitions:
- **Binary sensors** (`binary_sensor: !include binary_sensors.yaml`)
- **Sensors** (`sensor: !include sensors.yaml`)
- **Packages** (if you use `/config/packages/`)

## Features

✅ **Safe Migration**: Creates timestamped backups before making changes  
✅ **Automatic Conversion**: Converts all legacy fields to modern syntax  
✅ **Field Mapping**:
  - `friendly_name` → `name`
  - `value_template` → `state`
  - `icon_template` → `icon`
  - `entity_picture_template` → `picture`
  - `availability_template` → `availability`
  - `attribute_templates` → `attributes`

✅ **Rollback Support**: Includes restore script in backup directory  
✅ **Clean Removal**: Removes legacy definitions from original files  
✅ **Modern Addition**: Adds new `template:` section to configuration.yaml

## Installation

### SSH Add-on or Terminal

```bash
cd /config
wget https://gitea.hideawaygaming.com.au/jessikitty/ha-template-migration/raw/branch/main/migrate_templates.sh
chmod +x migrate_templates.sh
bash migrate_templates.sh
```

### What It Does

1. **Scans** all YAML files in `/config/` and `/config/packages/`
2. **Extracts** legacy template definitions
3. **Converts** to modern syntax
4. **Backs up** original files to `/config/backups/template_migration_TIMESTAMP/`
5. **Removes** legacy `- platform: template` blocks
6. **Adds** modern `template:` section to configuration.yaml

## Example Migration

### Before (binary_sensors.yaml)
```yaml
- platform: template
  sensors:
    router_authenticated:
      friendly_name: "Router Authenticated"
      value_template: >
        {{ states('input_text.router_token') not in ['unknown', '', 'unavailable', ''] }}
      icon_template: >
        {% if states('input_text.router_token') not in ['unknown', '', 'unavailable', ''] %}
          mdi:check-circle
        {% else %}
          mdi:close-circle
        {% endif %}
```

### After (configuration.yaml)
```yaml
template:
  - binary_sensor:
    - unique_id: router_authenticated
      name: "Router Authenticated"
      state: >
        {{ states('input_text.router_token') not in ['unknown', '', 'unavailable', ''] }}
      icon: >
        {% if states('input_text.router_token') not in ['unknown', '', 'unavailable', ''] %}
          mdi:check-circle
        {% else %}
          mdi:close-circle
        {% endif %}
```

## After Running

1. **Review** the new `template:` section at end of configuration.yaml
2. **Check config**: `ha core check`
3. **Restart HA**: `ha core restart`
4. **Verify** all template entities still work

## If Something Goes Wrong

```bash
# Restore from backup
cd /config/backups/template_migration_TIMESTAMP
bash restore.sh
ha core restart
```

## Requirements

- Home Assistant OS or Supervised (with SSH add-on)
- Core or Docker installations (adjust paths as needed)
- Bash shell

## What Gets Migrated

✅ Template binary sensors  
✅ Template sensors  
✅ All template fields (value, icon, availability, attributes, etc.)  
✅ Multiline templates with `>` operator  
✅ Templates in `!include` files

## Technical Details

- Uses pure bash + awk (no Python dependencies)
- Handles complex YAML indentation
- Preserves template logic exactly
- Safe for large configurations (handles 67+ sensors)

## Version History

- **v2** (2025-12-23): Fixed to handle `!include` files and list-item format
- **v1** (2025-12-23): Initial release (only scanned configuration.yaml)

## License

MIT License - feel free to use and modify!

## Support

Issues? Check the [Gitea repository](https://gitea.hideawaygaming.com.au/jessikitty/ha-template-migration) or file a bug report.