From 02065ace5db202517dd206a37c72e4eab9e82a02 Mon Sep 17 00:00:00 2001
From: Guanpeng Xu <herberteuler@gmail.com>
Date: Fri, 1 Jul 2022 11:47:48 +0800
Subject: [PATCH 1/3] nixos/modules/flake/source-info: new module

---
 nixos/modules/flake/source-info.nix | 31 +++++++++++++++++++++++++++++
 nixos/modules/module-list.nix       |  1 +
 2 files changed, 32 insertions(+)
 create mode 100644 nixos/modules/flake/source-info.nix

diff --git a/nixos/modules/flake/source-info.nix b/nixos/modules/flake/source-info.nix
new file mode 100644
index 0000000000000..c963fc3627dee
--- /dev/null
+++ b/nixos/modules/flake/source-info.nix
@@ -0,0 +1,31 @@
+{ config, lib, ... }:
+
+with lib;
+
+let sourceInfo = config.system.nixos.configuration.sourceInfo;
+
+in
+{
+  options = {
+
+    system.nixos.configuration.sourceInfo = mkOption {
+      type = types.attrsOf types.anything;
+      default = {};
+      example = "self.sourceInfo";
+      description = ''
+        The source information of a flake-based NixOS configuration.
+        If set, the attribute <literal>configurationRevision</literal>
+        will appear properly in the output of
+        <literal>nixos-version --json</literal>.
+
+        Caution: Setting this option may result in unnecessary
+        re-deployments if the flake repository changes but the
+        specific system configuration does not change.
+      '';
+    };
+  };
+
+  config = {
+    system.configurationRevision = mkIf (sourceInfo ? rev) sourceInfo.rev;
+  };
+}
diff --git a/nixos/modules/module-list.nix b/nixos/modules/module-list.nix
index b2ae30aa9ff28..f5e01c2dc7beb 100644
--- a/nixos/modules/module-list.nix
+++ b/nixos/modules/module-list.nix
@@ -38,6 +38,7 @@
   ./config/users-groups.nix
   ./config/vte.nix
   ./config/zram.nix
+  ./flake/source-info.nix
   ./hardware/acpilight.nix
   ./hardware/all-firmware.nix
   ./hardware/bladeRF.nix

From a2ec1c5fca5f131a26411dd0c18a59fcda3bc974 Mon Sep 17 00:00:00 2001
From: Guanpeng Xu <herberteuler@gmail.com>
Date: Fri, 15 Jul 2022 10:03:43 +0800
Subject: [PATCH 2/3] nixos/modules/flake/source-info: improve example and
 description

---
 nixos/modules/flake/source-info.nix | 24 ++++++++++++++++++------
 1 file changed, 18 insertions(+), 6 deletions(-)

diff --git a/nixos/modules/flake/source-info.nix b/nixos/modules/flake/source-info.nix
index c963fc3627dee..3f0e0f4f90742 100644
--- a/nixos/modules/flake/source-info.nix
+++ b/nixos/modules/flake/source-info.nix
@@ -11,14 +11,26 @@ in
     system.nixos.configuration.sourceInfo = mkOption {
       type = types.attrsOf types.anything;
       default = {};
-      example = "self.sourceInfo";
-      description = ''
+      example = lib.literalExpression ''
+      {
+        inputs.nixpkgs.url = ...;
+        outputs = { self, nixpkgs }: {
+          nixosConfigurations = {
+            host = nixpkgs.lib.nixosSystem {
+              modules = [
+                { system.nixos.configuration.sourceInfo = self.sourceInfo; }
+              ] ++ ...;
+            };
+          };
+        };
+      }
+      '';
+      description = lib.mdDoc ''
         The source information of a flake-based NixOS configuration.
-        If set, the attribute <literal>configurationRevision</literal>
-        will appear properly in the output of
-        <literal>nixos-version --json</literal>.
+        If set, the attribute `configurationRevision` will appear
+        properly in the output of `nixos-version --json`.
 
-        Caution: Setting this option may result in unnecessary
+        **Caution:** Setting this option may result in unnecessary
         re-deployments if the flake repository changes but the
         specific system configuration does not change.
       '';

From 60cfde6f2a4467bf57bf8bb29b7616b310baa0af Mon Sep 17 00:00:00 2001
From: Guanpeng Xu <herberteuler@gmail.com>
Date: Sat, 16 Jul 2022 18:35:05 +0800
Subject: [PATCH 3/3] nixos/modules/flake/source-info: add a section to the
 nixos manual

---
 .../flake-source-info.section.md              | 38 +++++++++++++++++++
 1 file changed, 38 insertions(+)
 create mode 100644 nixos/doc/manual/configuration/flake-source-info.section.md

diff --git a/nixos/doc/manual/configuration/flake-source-info.section.md b/nixos/doc/manual/configuration/flake-source-info.section.md
new file mode 100644
index 0000000000000..801a3068ae62a
--- /dev/null
+++ b/nixos/doc/manual/configuration/flake-source-info.section.md
@@ -0,0 +1,38 @@
+# Flake Configuration Source Information {#sec-flake-source-info}
+
+Perhaps the most significant advantage of a flake-based configuration
+over a legacy configuration is the ability to record the revision of
+the repository from which a NixOS system is built, as shown in the
+following example:
+
+```
+$ nixos-version --json
+{"configurationRevision":"f25d2e456a5a7b2798620e41e183739fdaf057ed"
+,"nixosVersion":"22.11.20220715.a2ec1c5"
+,"nixpkgsRevision":"a2ec1c5fca5f131a26411dd0c18a59fcda3bc974"}
+```
+
+To enable this feature, set
+[](#opt-system.nixos.configuration.sourceInfo) to the source
+information of the flake:
+
+```nix
+{
+  inputs.nixpkgs.url = ...;
+  outputs = { self, nixpkgs }: {
+    nixosConfigurations = {
+      host = nixpkgs.lib.nixosSystem {
+        modules = [
+          { system.nixos.configuration.sourceInfo = self.sourceInfo; }
+        ] ++ ...;
+      };
+    };
+  };
+}
+```
+
+Note that this feature is not enabled by default.  That is because in
+such a case that the repository changes but a specific system's
+configuration, `host` in the above snippet for example, does not
+change, there could be extra unnecessary generations.  Keep this in
+mind while using it.