From 1b0b0c5985d0b365d808b66346e17053e87cfb93 Mon Sep 17 00:00:00 2001
From: Zebedee Nicholls <zebedee.nicholls@climate-resource.com>
Date: Fri, 22 Aug 2025 10:13:54 +0200
Subject: [PATCH 1/3] Update docs with example

---
 docs/index.rst | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/docs/index.rst b/docs/index.rst
index 57c6bd89..184e6ef6 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -111,6 +111,31 @@ The lock objects are recursive locks, which means that once acquired, they will
         cite2()
     # And released here.
 
+It should also be noted that the lock is released during garbage collection.
+Put another way, if you do not assign an acquired lock to a variable,
+the lock will eventually be released (implicitly, not explicitly).
+This is explained with code below:
+
+.. code-block:: python
+
+    import tempfile
+    from pathlib import Path
+
+    import filelock
+
+    # If you create a lock and acquire it but don't assign it, 
+    # you will not actually hold the lock forever.
+    # Instead, the lock is released 
+    # when the created variable is garbage collected.
+    FileLock(lock_path).acquire()
+    # At some point after the creation above,
+    # the lock is released again even though there is no explicit call to `release`.
+
+    # If you instead assign to a dummy variable,
+    # the lock will be hold
+    _ = FileLock(lock_path).acquire()
+    # Now the lock is being held
+    # (at least until `_` is reassigned and the lock is garbage collected)
 
 Timeouts and non-blocking locks
 -------------------------------

From 64d7bb32315ff02db11260e1fdf3cb04e23d3c37 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Fri, 22 Aug 2025 08:14:23 +0000
Subject: [PATCH 2/3] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 docs/index.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/index.rst b/docs/index.rst
index 184e6ef6..47361bc2 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -123,9 +123,9 @@ This is explained with code below:
 
     import filelock
 
-    # If you create a lock and acquire it but don't assign it, 
+    # If you create a lock and acquire it but don't assign it,
     # you will not actually hold the lock forever.
-    # Instead, the lock is released 
+    # Instead, the lock is released
     # when the created variable is garbage collected.
     FileLock(lock_path).acquire()
     # At some point after the creation above,

From 8eb73f9dfd3578dad387ad91adb7c3336dc3aee2 Mon Sep 17 00:00:00 2001
From: Zebedee Nicholls <zebedee.nicholls@climate-resource.com>
Date: Fri, 22 Aug 2025 23:36:10 +0200
Subject: [PATCH 3/3] Add disclaimer

---
 docs/index.rst | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/docs/index.rst b/docs/index.rst
index 47361bc2..fb55b871 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -114,7 +114,10 @@ The lock objects are recursive locks, which means that once acquired, they will
 It should also be noted that the lock is released during garbage collection.
 Put another way, if you do not assign an acquired lock to a variable,
 the lock will eventually be released (implicitly, not explicitly).
-This is explained with code below:
+For this reason, using the lock in the way shown below is not something you should ever do,
+always use the context manager (`with` form) instead.
+
+This issue is illustrated with code below:
 
 .. code-block:: python