From eecd78fbfbd919655c924672640dd3af2ae7c561 Mon Sep 17 00:00:00 2001
From: Eino Rauhala <60004820+EinoHR@users.noreply.github.com>
Date: Wed, 26 Apr 2023 20:28:22 +0300
Subject: [PATCH] docs: add sections in README for scripts and a small
 explanation of /usr/etc/ (#50)

* docs: add section about scripts

* docs: add note about /usr/etc/
---
 README.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/README.md b/README.md
index daca9128b0..50748ad7c8 100644
--- a/README.md
+++ b/README.md
@@ -23,6 +23,13 @@ For the base-image field, you can use any other native container image. You will
 
 If you want to add custom configuration files, you can just add them in the `etc` directory. If you need to add other directories, you can look at the Containerfile to see how it's done. Writing to any directories under `/var` in Fedora Silverblue are not supported and will not work, as those are user-managed.
 
+> **Note**
+> The configuration files you put in the `etc` directory are actually added to `/usr/etc/` where they get applied to your local `/etc/` when rebasing to or updating the image. If a config file in `/etc/` has been changed, the changes won't be overridden, but the new version will be available in `/usr/etc/`. Run `sudo ostree admin config-diff` to see the difference between `/etc/` and `/usr/etc/` (`man ostree-admin-config-diff` for further documentation).
+
+### Custom build scripts
+
+If you want to execute custom shell script or commands in the image build, you shouldn't edit `build.sh` or the `Containerfile` directly. Instead, you can create a shell script in the `scripts/` directory (look at the `example.sh`). After creating your script, enable it in the `scripts:` section of your `recipe.yml`.
+
 ### Building multiple images
 
 You can build multiple images using multiple `recipe.yml` files. They will share the Containerfile and everything else, but things like packages declared in the recipe will be different between the images. For a more robust multibuild setup, you could consider forking from the [ublue-os/main](https://github.com/ublue-os/main/) repo, which was built from the purpose.