From f64ca22db84ab884df68a09bab3d627572c37e5b Mon Sep 17 00:00:00 2001
From: Gabriele Modena <gmodena@pm.me>
Date: Sun, 18 Feb 2024 15:51:25 +0100
Subject: [PATCH] README: add doc (#46)

Add documentation for package overrides.
Add documentation for uninstallUnmanagedPackaged behaviour.
---
 README.md | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/README.md b/README.md
index 06253a6..b46eb78 100644
--- a/README.md
+++ b/README.md
@@ -108,6 +108,14 @@ You can pin a specific commit setting `commit=<hash>` attribute.
 
 Rebuild your system (or home-manager) for changes to take place.
 
+##### Unmanaged packages
+
+By default `nix-flatpak` will only managed (install/uninstall/update) packages declared in the
+`services.flatpak.packages`. Flatpak installed by the command line of app stores won't be affected.
+
+Set `services.flatpak.uninstallUnmanagedPackages = true` to alter this behaviour, and have `nix-flatpak` manage the
+lifecyle of all flatpaks installed on the system.
+
 ### Updates
 
 Set
@@ -146,6 +154,43 @@ YMMV.
 If you need generational builds, [declarative-flatpak](https://github.com/GermanBread/declarative-flatpak)
 might be a better fit.
 
+### Overrides
+
+Package overrides can be declared via `services.flatpak.overrides`. Following is a usage example:
+```
+{
+  services.flatpak.overrides = {
+    global = {
+      # Force Wayland by default
+      Context.sockets = ["wayland" "!x11" "!fallback-x11"];
+
+      Environment = {
+        # Fix un-themed cursor in some Wayland apps
+        XCURSOR_PATH = "/run/host/user-share/icons:/run/host/share/icons";
+
+        # Force correct theme for some GTK apps
+        GTK_THEME = "Adwaita:dark";
+      };
+    };
+
+    "com.visualstudio.code".Context = {
+      filesystems = [
+        "xdg-config/git:ro" # Expose user Git config
+        "/run/current-system/sw/bin:ro" # Expose NixOS managed software
+      ];
+      sockets = [
+        "gpg-agent" # Expose GPG agent
+        "pcsc" # Expose smart cards (i.e. YubiKey)
+      ];
+    };
+
+    "org.onlyoffice.desktopeditors".Context.sockets = ["x11"]; # No Wayland support
+  };
+}
+```
+
+Implementation details have been discussed in 
+
 # Known issues
 
 A couple of things to be aware of when working with `nix-flatpak`.