Estimated reading time: 11 minutes
Have you ever sat in front of your Home Assistant dashboard, made a small change to a YAML file and suddenly nothing worked? The screen remains white, automations stop working or - the worst case scenario - Home Assistant no longer restarts.
Everyone who loves and cares for their smart home knows this moment of horror. It's often when you wish you had a time machine to undo that one fateful line of code. Sure, you make backups. But do you really import a complete 5 GB system backup just because you're in the configuration.yaml made an indentation error? This takes forever and also overwrites data that you perhaps wanted to keep.
Normally you would now have two options:
- Looking for a needle in a haystack: Hours of debugging, commenting and hoping.
- The „nuclear“ backup: Import a complete system backup from last night. However, this will also remove all the data that has been collected since then (energy consumption, temperature curves, etc.).
But there is a third way. A way that professional software developers have been using for decades and which is now finally finding its way into our smart homes in a user-friendly way: Home Assistant Version Control.
For detailed instructions and explanations of all configuration options, I recommend watching the YouTube video linked below. This video goes into detail about each individual setting, providing you with comprehensive instructions on how to set everything up correctly. Any code from the video can be found in this article, so you can use it directly without having to type it out.
This blog post, including video, is part of a series in which we build and set up our own home server. We start with the basics, such as installing Ubuntu VM with Docker, and then move on to configuring our own domain, security measures, and, above all, lots of cool and useful self-hosted services. Whether it's media servers like Plex or Jellyfin or document management like Paperless-NGX, we'll work together to build the setup you want to see. We'll even tackle topics like single sign-on (SSO) together.
Why you need Version Control (and why backups are not enough)
In this article, I'll show you in detail how to install and use this ingenious tool and why it should be a must-have for every smart home from now on. We take a look at the add-on from DiggingForDinos which makes versioning so easy that you never have to worry about the „Save“ button again.
Before we jump into the installation, let's briefly clarify why „version control“ is not the same as a classic backup.
A Backup is like a photo of your entire house at a certain point in time. When you restore it, everything is reset to that point in time. Version Control on the other hand, is like a diary for each individual file. It remembers: „On Tuesday at 14:00, you entered the following in the file automations.yaml Line 15 changed.“
The advantages at a glance:
- Granularity: You can reset individual files without having to reset your entire system.
- Transparency: You see exactly, what has been changed (diff view).
- Speed: An „undo“ takes seconds, not hours of restoring.
- Security: It runs automatically in the background. You don't have to remember to start it.
The project we're looking at today can be found on Codeberg (DiggingForDinos/HomeAssistantVersionControl), among others, and it brings the power of Git (the standard for programmers) to your home assistant in an understandable interface.
With Home Assistant Version Control you can surgically precise exactly the Undo the change that caused the error without losing your database with the valuable energy data.
The tool in detail - Home Assistant Version Control
We use the project that is available on Codeberg at DiggingForDinos/HomeAssistantVersionControl is hosted. It is a wrapper tool that hides the complexity of „Git“ (the industry standard for versioning) behind a beautiful, understandable user interface.
The core philosophy
The tool follows this approach: Set it and forget it. It is designed to run in the background and protect you without the need for constant manual intervention. It is designed to detect local changes in your /config recognizes folders and stores them securely in a local Git database. Nothing leaves your hard disk and your instance.
Installation via Home Assistant add-on
This is the path for 95% of all users (Home Assistant OS or Supervised). We are taking an extremely detailed approach here so that nothing can go wrong.
Add repository
Since this add-on is not included in Home Assistant's official default store, we need to add a „Custom Repository“ (a custom source).
- Open your Home Assistant dashboard.
- In the left sidebar, click on Settings and then to Add-ons.
- Click on the blue button at the bottom right Add-on store.
- Now we need to open the menu: Click on the three small dots (the kebab menu) at the top right and select Repositories.
- A „Manage repositories“ window opens. Enter the following URL here:
https://codeberg.org/DiggingForDinos/ha-addons - Click on Add. Home Assistant now checks the source. After a successful check, the repo appears in the list. Close the window.
Find and install the add-on
- You are still in the add-on store. Sometimes you have to reload the page (F5 in the browser) for new content to become visible.
- Scroll all the way down to the new category (usually „DiggingForDinos Add-ons“) or use the search bar at the top and type „Version Control“.
- Click on the tile Home Assistant Version Control.
- You will now see the detail page. Click on Install. Patience: Since Git and some dependencies are installed here, this process can take a few minutes on a Raspberry Pi 3 or 4.
Important settings BEFORE starting
Before you blindly press „Start“, we configure the add-on for optimum operation.
- Watchdog (guard): Activate the „Watchdog“ switch. If the add-on crashes, Home Assistant restarts it automatically. As this tool is your „insurance“, it must always be running.
- Show in the sidebar: Be sure to activate this button! You want to have quick access to the version history without having to click through menus.
Start
Go back to the „Information“ tab and click on Start. Then immediately click on the tab Protocols (Logs) and press „Refresh“ at the bottom. You should see lines like: [Info] Starting Version Control... [Info] Git initialized. [Info] Watching /config for changes.
If you can see that: Congratulations! Your safety net is taut.
The features in detail - What can the tool do?
Now it gets exciting. What exactly does the interface offer you? If you click on „Version Control“ in the sidebar, the dashboard opens. Let's go through the functions one by one.
The timeline
This is your main view. Here you can see a chronological list of all events.
- Automatic recording: Each time you save a file, the system creates an entry.
- Depth of information: You will see the date, time and often the user (if Home Assistant passes this on to the file system, which is not always the case - it often says „System“ or „Root“).
- Grouping: If you change five files within 2 seconds (e.g. by a „Save all“ in VS Code), the tool often merges them intelligently.
The Visual Diff Viewer (The comparison)
This is the most powerful feature. Click on any entry in the timeline. This opens a view that programmers love:
- Left side (or top): The old state of the file.
- Right side (or bottom): The new state.
The color coding is intuitive:
- Red background: These lines have been removed.
- Green background: These lines have been added.
Practical example: You look at the change to the configuration.yaml on. You can see that one line is red, in which default_config: stood. Nothing is green on the right. Insight: „Oh dear, I've accidentally left the default_config: deleted! That's why my UI no longer loads!“ Without this tool, you would never have found this one missing line in a 500-line file.
One-Click Restore (The Time Machine)
You have found the error in the Diff Viewer. Now what? You don't have to type in the code. At the top right of the detailed view you will find the button Restore (Restore).
- Click on Restore.
- The tool asks for confirmation.
- The tool overwrites the current, corrupt file with the version from the past.
- Important: In order for Home Assistant to apply the change, you usually, but not always, have to reload the configuration (Developer tools -> Reload YAML configuration) or restart HA.
File exclusion and .gitignore (Performance & Security)
An often overlooked but critical feature. Not all files in your /config Folders should be versioned.
- The database:
home-assistant_v2.db. This file changes every second (new temperature values, logs). If we version it, your storage space will expand by gigabytes within hours. The tool has intelligent default rules to ignore this file. - Secrets:
secrets.yaml. This is where your passwords are stored. Locally this is okay, but if you plan to push your Git to GitHub at some point (more on this in a moment), this file never end up in Git.
The add-on respects a .gitignore file. You can save this file in your /config Create a folder and enter the files to be ignored there.
Standalone installation (Standalone / Docker)
Are you using Home Assistant Container (Docker) without a supervisor? No problem. The tool is essentially a Python/Git application that also runs as a Docker container.
The challenge here is „mounting“ the volumes. The Version Control container must have access to the same folder as your Home Assistant container.
The docker-compose.yaml
Here is a complete configuration for a standalone installation:
services:
home-assistant-version-control:
container_name: home-assistant-version-control
image: ghcr.io/diggingfordinos/homeassistantversioncontrolbeta:latest
user: "1000:1000" # IMPORTANT: The user ID must have write access to the config folder!
ports:
- 54001:54001
volumes:
- /path/to/your/config:/config
environment:
- TZ=Europe/Berlin
- SUPERVISOR_TOKEN=your_long_lived_access_token_here
- HA_URL=http://homeassistant.local:8123
restart: unless-stoppedImportant information for Docker users:
- Authorizations (Permissions): This is the most common error. The container often runs as root or as a special user. If your HA config belongs to your Linux user, conflicts may arise. Use the
user: "UID:GID"setting or PUID/PGID environment variables to ensure that the tool has write permissions in the/configfolder has. - Access: You can then access the tool at
http://:54001. It is not integrated in the HA sidebar (as it is not an add-on), but you can integrate it as a „website card“ in your dashboard or as an „iframe panel“ in theconfiguration.yamlto achieve the same effect.
YouTube video implementation
Conclusion: Is it worth the effort?
Absolutely. And „effort“ is the wrong word, because installation takes less than 10 minutes.
Home Assistant Version Control transforms your smart home from a shaky tinker's den into a stable system. It gives you the confidence to try things out because you know you have a safety net. You no longer have to be afraid of the „Save“ button.
To summarize:
- It saves you from your own mistakes.
- It helps you to understand, when and Why things have broken.
- It consumes hardly any resources.
- It is free and open source.
There is no rational reason not to install this add-on. Do it today. Your future self, standing in front of a broken smart home at 11pm at night, will be infinitely grateful.
Useful links & resources at a glance
Here you will find a compact summary of all the sources and further information mentioned in the article:
- Source code & documentation (Codeberg): https://codeberg.org/DiggingForDinos/HomeAssistantVersionControl Here you can find the source code, issues and technical details.
- Docker image (for standalone users):
ghcr.io/diggingfordinos/homeassistantversioncontrol - Official Git documentation: https://git-scm.com/doc If you want to understand how the „Git“ technology works under the hood.
- Home Assistant Community Forum: https://community.home-assistant.io/ The best place to ask questions if you get stuck during installation.
0 Comments