Update README for v2 with !include file support

Explains the critical v2 fix for handling templates in included files: - Why v1 didn't work (only scanned configuration.yaml) - What v2 fixes (scans all .yaml files, handles list format) - Updated example showing binary_sensors.yaml format - Clearer installation and troubleshooting instructions
2025-12-23 12:53:40 +11:00
parent ec2062872c
commit 8a0ca75de1
1 changed files with 114 additions and 64 deletions
--- a/README.md
+++ b/README.md
@@ -1,10 +1,52 @@
 # Home Assistant Legacy Template Migration

-**Pure Bash script** to fix all **67 template deprecation warnings** by migrating from legacy `platform: template` syntax to modern `template:` syntax.
+**✨ v2 UPDATE**: Fixed script now properly handles templates in included files (`sensors.yaml`, `binary_sensors.yaml`)!

-✅ **No Python required** - Works directly in SSH add-on!
+Automatically migrates legacy `platform: template` syntax to modern `template:` syntax in Home Assistant.

-## 🚀 Quick Start
+## 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
@@ -13,87 +55,95 @@ chmod +x migrate_templates.sh
 bash migrate_templates.sh
 ```

-Then:
-```bash
-ha core check    # Verify configuration
-ha core restart  # Apply changes
-```
+### What It Does

-## ⚠️ What This Fixes
+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

-Home Assistant 2026.6 will remove support for legacy template syntax.
+## Example Migration

-**Before (deprecated):**
+### Before (binary_sensors.yaml)
 ```yaml
-binary_sensor:
-  - platform: template
-    sensors:
-      router_authenticated:
-        friendly_name: "Router Authenticated"
-        value_template: "{{ states('input_text.router_token') != '' }}"
+- 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 (modern):**
+### After (configuration.yaml)
 ```yaml
 template:
  - binary_sensor:
-      - name: "Router Authenticated"
-        state: "{{ states('input_text.router_token') != '' }}"
-        unique_id: router_authenticated
+    - 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 %}
 ```

-## 📊 What It Does
+## After Running

-✅ Pure Bash - no Python dependencies  
-✅ Scans all YAML files  
-✅ Creates timestamped backups  
-✅ Converts to modern syntax  
-✅ Updates configuration.yaml  
-✅ Generates restore script  
+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

-## 🛡️ Safety Features
-
- **No Dependencies** - Works in SSH add-on without Python
- **Automatic Backups** - All files backed up before changes
- **Exit on Error** - Stops if any step fails
- **Easy Restore** - One command rollback
- **No Data Loss** - Preserves all configurations
-
-## 📝 Expected Output
-
-```
-======================================================================
-Home Assistant Legacy Template Migration (Bash)
-======================================================================
-
-✓ Created backup: /config/backups/template_migration_20251223_123456
-
-ℹ Found 67 legacy template entities:
-  - 15 sensor(s)
-  - 52 binary_sensor(s)
-
-✓ MIGRATION COMPLETE
-Migrated: 67 template entities
-```
-
-## 🔄 Restore if Needed
+## If Something Goes Wrong

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

-## 🎯 Result
+## Requirements

-After running, all **67 repair warnings will be cleared!** ✅
+- Home Assistant OS or Supervised (with SSH add-on)
+- Core or Docker installations (adjust paths as needed)
+- Bash shell

-## 💡 Why Bash?
+## What Gets Migrated

-✅ Works in SSH add-on without installing packages  
-✅ Faster execution  
-✅ No dependency issues  
-✅ Native YAML parsing with awk  
+✅ Template binary sensors  
+✅ Template sensors  
+✅ All template fields (value, icon, availability, attributes, etc.)  
+✅ Multiline templates with `>` operator  
+✅ Templates in `!include` files

---
+## Technical Details

-**Repository:** https://gitea.hideawaygaming.com.au/jessikitty/ha-template-migration
+- 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.