From 67990c1f956c60d501dfa1e1410ad8b3e6032eaf Mon Sep 17 00:00:00 2001
From: Sean Reifschneider <sean@realgo.com>
Date: Sun, 17 Dec 2023 11:26:28 -0700
Subject: [PATCH] Some more documentation work

---
 docs/tutorial.md | 26 ++++++++++++++++++++++++--
 uplaybook/fs.py  |  8 ++++++++
 2 files changed, 32 insertions(+), 2 deletions(-)

diff --git a/docs/tutorial.md b/docs/tutorial.md
index 04c7597..a9cdfe5 100644
--- a/docs/tutorial.md
+++ b/docs/tutorial.md
@@ -115,6 +115,30 @@ user_mode=False)
 *** RECAP:  total=5 changed=3 failure=0
 ```
 
+## fs.builder()
+
+[`fs.builder()`](tasks/fs/#uplaybook.fs.builder) is a powerful way to create a large
+set of filesystem objects.  It takes a list of operations to perform, and optionally a set
+of defaults.  So you can specify defaults for permissions, ownership, etc, and then
+optionally override them in the specific items.
+
+For example, to set up headscale:
+
+```python
+from uplaybook.core import Item
+
+def restart_headscale():
+    pyinfra.systemd.service(service="headscale", restarted=True)
+
+fs.builder(defaults=Item(owner="headscale", group="headscale", mode="a=-,ug+rwX"),
+           items=[
+               Item(path="/etc/headscale", state="directory"),
+               Item(path="/etc/headscale/config.yaml", notify=restart_headscale),
+               Item(path="/etc/headscale/acls.yaml", notify=restart_headscale),
+               Item(path="/etc/headscale/derp.yaml", notify=restart_headscale),
+               ])
+```
+
 ## Reading Docs
 
 How do you know what tasks and arguments are available?  uPlaybook includes an "--up-docs"
@@ -350,6 +374,4 @@ templating to set up the scaffolding.
 
 ## Playbook Documentation
 
-## fs.builder()
-
 ## Include Playbooks
diff --git a/uplaybook/fs.py b/uplaybook/fs.py
index 32ed70b..9679e44 100644
--- a/uplaybook/fs.py
+++ b/uplaybook/fs.py
@@ -816,6 +816,14 @@ def builder(
                    Item(path="/tmp/{{ modname }}/nobody-file", owner="nobody", group="nobody"),
                    Item(path="/tmp/{{ modname }}/site.conf", notify=restart_apache),
                ])
+
+    fs.builder(defaults=Item(owner="headscale", group="headscale", mode="a=-,ug+rwX"),
+               items=[
+                   Item(path="/etc/headscale", state="directory"),
+                   Item(path="/etc/headscale/config.yaml", notify=restart_headscale),
+                   Item(path="/etc/headscale/acls.yaml", notify=restart_headscale),
+                   Item(path="/etc/headscale/derp.yaml", notify=restart_headscale),
+                   ])
     ```
     """
     changed = False