From 8e09e44b83bb141853d8ecdf017815a23e4b7acc Mon Sep 17 00:00:00 2001
From: Trenton H <797416+stumpylog@users.noreply.github.com>
Date: Wed, 4 Nov 2026 20:09:46 -0800
Subject: [PATCH] Fix: move documents when tags change through the reverse
 relation

---
 src/documents/signals/handlers.py      | 9 ++++++---
 src/documents/tests/test_file_moves.py | 7 ++++---
 2 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/src/documents/signals/handlers.py b/src/documents/signals/handlers.py
index ac90093f2e..e492ad0572 100644
--- a/src/documents/signals/handlers.py
+++ b/src/documents/signals/handlers.py
@@ -423,15 +423,18 @@ def update_filename_and_move_files(
     instance: Document | CustomFieldInstance,
     **kwargs,
 ) -> None:
-    if kwargs.get("reverse"):
-        # tag.documents.add(doc): instance is the Tag, not a Document.
-        return
     action = kwargs.get("action")
     if action is not None and action not in {"post_add", "post_remove", "post_clear"}:
         # m2m_changed fires pre_* and post_* actions; only post_* describe the
         # relation state the filename should follow.
         return
 
+    if kwargs.get("reverse"):
+        # tag.documents.add(doc): instance is the Tag, pk_set holds Document pks.
+        for document in Document.objects.filter(pk__in=kwargs.get("pk_set") or ()):
+            request_file_move(document)
+        return
+
     if isinstance(instance, CustomFieldInstance):
         if not _filename_template_uses_custom_fields(instance.document):
             return
diff --git a/src/documents/tests/test_file_moves.py b/src/documents/tests/test_file_moves.py
index 8a0c934e73..899ad4b879 100644
--- a/src/documents/tests/test_file_moves.py
+++ b/src/documents/tests/test_file_moves.py
@@ -256,7 +256,7 @@ class TestRequestFileMoveWithoutScope:
 
 @pytest.mark.django_db
 class TestReceiver:
-    def test_reverse_m2m_does_not_request_a_move(
+    def test_reverse_m2m_requests_a_move_per_document(
         self,
         document: Document,
         mocker: MockerFixture,
@@ -267,14 +267,15 @@ class TestReceiver:
         WHEN:
             - A document is added through the tag's reverse relation
         THEN:
-            - No move is requested with the tag as the instance
+            - A move is requested for the added document, never the tag
         """
         tag = TagFactory()
         request = mocker.patch("documents.signals.handlers.request_file_move")
 
         tag.documents.add(document)
 
-        request.assert_not_called()
+        request.assert_called_once()
+        assert request.call_args.args[0].pk == document.pk
 
 
 @pytest.mark.django_db