Add comprehensive README documentation
- Usage instructions for 3 different methods - Complete safety features explanation - Expected output examples - Troubleshooting guide - Backup and restore procedures
This commit is contained in:
279
README.md
Normal file
279
README.md
Normal file
@@ -0,0 +1,279 @@
|
||||
# Home Assistant Chore Cleanup Script
|
||||
|
||||
Automatically removes unused chore-related entities from your Home Assistant YAML configuration files.
|
||||
|
||||
## 🎯 What It Does
|
||||
|
||||
This script identifies and removes **46 unused entities** from your Home Assistant configuration:
|
||||
|
||||
- **19 Input Booleans**: Unused task tracking booleans (personal desk/room cleaning, generic tasks)
|
||||
- **7 Duplicate Scripts**: Old naming convention (`complete_task_*` versions)
|
||||
- **3 Generic Scripts**: Unused completion scripts
|
||||
|
||||
## ✅ Safety Features
|
||||
|
||||
- **Automatic Backups**: Creates timestamped backups before making ANY changes
|
||||
- **Restore Script**: Generates a one-click restore script in case you need to undo
|
||||
- **Dry-run Capable**: Review what will be removed before committing
|
||||
- **Error Handling**: Continues even if some files fail, reports all errors at end
|
||||
|
||||
## 📋 What Gets Removed
|
||||
|
||||
### Input Booleans (19 items)
|
||||
```
|
||||
task_lou_clean_desk_pending
|
||||
task_jess_clean_desk_pending
|
||||
task_william_clean_desk_pending
|
||||
task_xander_clean_desk_pending
|
||||
task_bella_clean_desk_pending
|
||||
task_lou_clean_room_pending
|
||||
task_jess_clean_room_pending
|
||||
task_william_clean_room_pending
|
||||
task_xander_clean_room_pending
|
||||
task_bella_clean_room_pending
|
||||
task_tidy_lounge_pending
|
||||
task_vacuum_room_pending
|
||||
task_get_school_ready_pending
|
||||
task_clean_desks_done_this_week
|
||||
task_clean_rooms_done_this_week
|
||||
task_tidy_lounge_done_this_week
|
||||
task_tidy_kitchen_done_today
|
||||
task_clean_dining_table_done_today
|
||||
task_vacuum_room_done_today
|
||||
```
|
||||
|
||||
### Scripts (10 items)
|
||||
```
|
||||
complete_task_dishwasher_unload (duplicate)
|
||||
complete_task_washing_machine_unload (duplicate)
|
||||
complete_task_dryer_unload (duplicate)
|
||||
complete_task_bins_out (duplicate)
|
||||
complete_task_bins_in (duplicate)
|
||||
complete_task_kitty_litter_clean (duplicate)
|
||||
complete_task_kitty_litter_change (duplicate)
|
||||
complete_tidy_lounge (unused)
|
||||
complete_vacuum_room (unused)
|
||||
complete_get_school_ready (unused)
|
||||
```
|
||||
|
||||
## 🚀 Usage
|
||||
|
||||
### Method 1: Run Directly on Home Assistant
|
||||
|
||||
```bash
|
||||
# SSH into your Home Assistant instance
|
||||
ssh root@homeassistant.local
|
||||
|
||||
# Copy the script to your config directory
|
||||
# (You can upload via File Editor add-on or SCP)
|
||||
|
||||
# Make it executable
|
||||
chmod +x /config/ha_chore_cleanup.py
|
||||
|
||||
# Run the script
|
||||
python3 /config/ha_chore_cleanup.py
|
||||
```
|
||||
|
||||
### Method 2: Run from Any Machine (with path)
|
||||
|
||||
```bash
|
||||
# If your Home Assistant config is mounted elsewhere
|
||||
python3 ha_chore_cleanup.py /path/to/your/config
|
||||
```
|
||||
|
||||
### Method 3: Via Home Assistant Terminal Add-on
|
||||
|
||||
1. Install "Terminal & SSH" add-on
|
||||
2. Upload script via File Editor
|
||||
3. Run in terminal:
|
||||
```bash
|
||||
cd /config
|
||||
python3 ha_chore_cleanup.py
|
||||
```
|
||||
|
||||
## 📂 What Files Get Modified
|
||||
|
||||
The script will search and modify these files if they exist:
|
||||
|
||||
- `configuration.yaml` (if entities are defined inline)
|
||||
- `input_boolean.yaml` or `input_booleans.yaml`
|
||||
- `scripts.yaml` or `script.yaml`
|
||||
- `helpers.yaml` (if it exists)
|
||||
- Any files in `packages/` directory containing the target entities
|
||||
|
||||
## 🔄 Backup Location
|
||||
|
||||
Backups are saved to:
|
||||
```
|
||||
/config/backups/cleanup_YYYYMMDD_HHMMSS/
|
||||
```
|
||||
|
||||
Each backup directory contains:
|
||||
- Original YAML files before modification
|
||||
- `restore.sh` - One-click restoration script
|
||||
|
||||
## ⚠️ Important Notes
|
||||
|
||||
### What's KEPT (Safe to Keep)
|
||||
The script **does NOT remove** these items because they're actively used:
|
||||
|
||||
**Tracking Booleans** (used in automation conditions):
|
||||
- `task_bella_clothes_done_today`
|
||||
- `task_xander_clothes_done_today`
|
||||
- `task_william_clothes_done_today`
|
||||
- `task_handwash_dishes_done_today`
|
||||
- `task_feed_chips_done_today`
|
||||
- `task_feed_harper_done_today`
|
||||
- `task_water_chips_done_today`
|
||||
- `task_water_harper_done_today`
|
||||
- `task_kitty_litter_clean_done_today`
|
||||
- `task_kitty_litter_change_done_fortnight`
|
||||
|
||||
These prevent duplicate task creation and are referenced in your automations.
|
||||
|
||||
### Files with !include Directives
|
||||
If the script encounters YAML files with `!include` or `!secret` directives, it will:
|
||||
- Create a backup
|
||||
- Skip automatic modification
|
||||
- Report the file for manual review
|
||||
|
||||
## 📊 Expected Output
|
||||
|
||||
```
|
||||
======================================================================
|
||||
Home Assistant Chore Cleanup Script
|
||||
======================================================================
|
||||
✓ Created backup directory: /config/backups/cleanup_20241223_150000
|
||||
|
||||
Processing configuration.yaml...
|
||||
✓ Backed up: configuration.yaml
|
||||
Removed 5 input_boolean entries
|
||||
Removed 3 script entries
|
||||
✓ Saved: configuration.yaml
|
||||
|
||||
Processing input_boolean.yaml...
|
||||
✓ Backed up: input_boolean.yaml
|
||||
✓ Removed 14 input_boolean entries
|
||||
✓ Saved: input_boolean.yaml
|
||||
|
||||
Processing scripts.yaml...
|
||||
✓ Backed up: scripts.yaml
|
||||
✓ Removed 7 script entries
|
||||
✓ Saved: scripts.yaml
|
||||
|
||||
======================================================================
|
||||
CLEANUP SUMMARY
|
||||
======================================================================
|
||||
|
||||
✓ Backups saved to: /config/backups/cleanup_20241223_150000
|
||||
|
||||
📋 Input Booleans Removed: 19
|
||||
- task_bella_clean_desk_pending
|
||||
- task_clean_desks_done_this_week
|
||||
[... full list ...]
|
||||
|
||||
📜 Scripts Removed: 10
|
||||
- complete_get_school_ready
|
||||
- complete_task_bins_in
|
||||
[... full list ...]
|
||||
|
||||
======================================================================
|
||||
NEXT STEPS:
|
||||
======================================================================
|
||||
1. Review the changes in your YAML files
|
||||
2. Run 'ha core check' to verify configuration
|
||||
3. If everything looks good, restart Home Assistant
|
||||
4. If issues occur, restore from backups
|
||||
======================================================================
|
||||
```
|
||||
|
||||
## 🔧 Post-Cleanup Steps
|
||||
|
||||
### 1. Verify Configuration
|
||||
```bash
|
||||
# Check configuration is valid
|
||||
ha core check
|
||||
```
|
||||
|
||||
### 2. Review Changes (Optional)
|
||||
```bash
|
||||
# Compare backup to current
|
||||
diff /config/backups/cleanup_YYYYMMDD_HHMMSS/scripts.yaml /config/scripts.yaml
|
||||
```
|
||||
|
||||
### 3. Restart Home Assistant
|
||||
```bash
|
||||
ha core restart
|
||||
```
|
||||
|
||||
### 4. Verify Everything Works
|
||||
- Check your Dailies dashboard (dashboard-chores)
|
||||
- Test a few task completions
|
||||
- Check for any errors in logs
|
||||
|
||||
## 🔙 How to Restore (If Needed)
|
||||
|
||||
### Option 1: Use the Restore Script
|
||||
```bash
|
||||
cd /config/backups/cleanup_YYYYMMDD_HHMMSS
|
||||
./restore.sh
|
||||
ha core restart
|
||||
```
|
||||
|
||||
### Option 2: Manual Restore
|
||||
```bash
|
||||
# Copy backup files back
|
||||
cp /config/backups/cleanup_YYYYMMDD_HHMMSS/*.yaml /config/
|
||||
ha core restart
|
||||
```
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### "Permission Denied"
|
||||
```bash
|
||||
chmod +x ha_chore_cleanup.py
|
||||
```
|
||||
|
||||
### "Module 'yaml' not found"
|
||||
```bash
|
||||
pip3 install pyyaml
|
||||
```
|
||||
|
||||
### Configuration Check Fails After Cleanup
|
||||
1. Don't panic - your backups are safe
|
||||
2. Run the restore script
|
||||
3. Review what was removed
|
||||
4. Report any issues
|
||||
|
||||
### Script Reports Errors
|
||||
- Check the error messages in the summary
|
||||
- Review those specific files manually
|
||||
- The script continues even if some files fail
|
||||
|
||||
## 📝 Logs & Debugging
|
||||
|
||||
The script outputs detailed information about:
|
||||
- Which files it's processing
|
||||
- How many items it removed from each file
|
||||
- Any errors encountered
|
||||
- Full list of removed items
|
||||
|
||||
All output is also printed to console for your review.
|
||||
|
||||
## 🤝 Support
|
||||
|
||||
If you encounter issues:
|
||||
1. Check the backup directory - your files are safe
|
||||
2. Review the error messages
|
||||
3. Restore from backup if needed
|
||||
4. Report the issue with the full output
|
||||
|
||||
## 📜 License
|
||||
|
||||
Created for Jess's Home Assistant setup
|
||||
Use freely, modify as needed
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: December 23, 2024
|
||||
**Version**: 1.0.0
|
||||
Reference in New Issue
Block a user