From dc705d18e7b68f21f6c32c9ba89f5bf819a44f3f Mon Sep 17 00:00:00 2001
From: Victor Moene <victor.moene@northern.tech>
Date: Mon, 22 Sep 2025 12:18:50 +0200
Subject: [PATCH] Added documentation for getgroups policy function

Ticket: ENT-12722
Signed-off-by: Victor Moene <victor.moene@northern.tech>
---
 .../reference/functions/getgroups.markdown    | 47 +++++++++++++++++++
 1 file changed, 47 insertions(+)
 create mode 100644 content/reference/functions/getgroups.markdown

diff --git a/content/reference/functions/getgroups.markdown b/content/reference/functions/getgroups.markdown
new file mode 100644
index 000000000..4fc3153ba
--- /dev/null
+++ b/content/reference/functions/getgroups.markdown
@@ -0,0 +1,47 @@
+---
+layout: default
+title: getgroups
+---
+
+{{< CFEngine_function_prototype(exclude_names, exclude_ids) >}}
+
+**Description:** Returns a list of all groups defined, except those names in the comma separated string of `exclude_names` and the comma separated string of uids in `exclude_ids`
+
+{{< CFEngine_function_attributes(exclude_names, exclude_ids) >}}
+
+**Example:**
+
+```cf3
+bundle agent main
+{
+  vars:
+    "groups"
+      slist => getgroups("root", "");
+
+    "first_three_groups"
+      slist => sublist("@(groups)", head, 3);
+
+  reports:
+    "$(first_three_groups)";
+
+}
+```
+
+**Output:**
+
+```
+R: daemon
+R: bin
+R: sys
+```
+
+**Notes:**
+
+- This function is currently only available on Unix-like systems.
+- This function will return both local and remote (for example, groups defined in an external directory like LDAP) groups on a system.
+
+**History:**
+
+- Introduced in CFEngine 3.27.
+
+**See also:** [`getgroupinfo()`][getgroupinfo].