feat(update): keep developer-owned regions with {% ignore %} tag (#2184)

Replaced the literal comment-marker approach with a language-agnostic Jinja
`{% ignore %}` / `{% endignore %}` tag. The block renders on `copier copy`
but is omitted from the renders Copier produces internally during
`copier update`, so its content stays developer-owned while no Copier syntax
leaks into rendered files.

Because the region is absent from both the old and new template renders that
feed the 3-way merge, template changes inside it never reach the diff and the
developer's own version survives, degrading to a normal Copier conflict only
when the template edits lines directly adjacent to the block.

- Added `IgnoreExtension`, compiling the tag to the equivalent of
  `{% if _copier_operation != 'update' %}...{% endif %}`.
- Expose `_copier_operation` in the file render context and merge it with
  per-call extra context to avoid duplicate-keyword render errors.
- Removed `copier/_preserve.py` and its `_apply_update` wiring.
- Updated the `updating.md` docs and replaced the tests.

Author: DrKat0m

copier/_jinja_ext.py

@@ -122,4 +122,57 @@ def _yield_support(
         return res
 
 
+class IgnoreExtension(Extension):
+    r"""Jinja2 extension for the `ignore` tag.
+
+    Wraps a block of *developer-owned* template content that should be rendered
+    on initial generation (`copier copy`) but omitted from the renders Copier
+    produces internally during `copier update`. Because the block is absent from
+    both the old and new template renders that feed the 3-way merge, template
+    changes inside it never reach the diff, so the developer's own version of the
+    region in the generated project is left untouched on every update.
+
+    Unlike literal marker comments, nothing about this tag survives into the
+    rendered file, so it is language-agnostic and never leaks Copier syntax into
+    generated projects.
+
+    The tag compiles to the equivalent of::
+
+        {% if _copier_operation != 'update' %}...{% endif %}
+
+    so it relies solely on the `_copier_operation` render context variable and
+    needs no runtime support hook.
+
+    !!! example
+
+        ```pycon
+        >>> from jinja2.sandbox import SandboxedEnvironment
+        >>> from copier._jinja_ext import IgnoreExtension
+        >>> env = SandboxedEnvironment(extensions=[IgnoreExtension])
+        >>> template = env.from_string(
+        ...     "keep\n{% ignore %}scaffold{% endignore %}\nkeep"
+        ... )
+        >>> template.render({"_copier_operation": "copy"})
+        'keep\nscaffold\nkeep'
+        >>> template.render({"_copier_operation": "update"})
+        'keep\n\nkeep'
+        ```
+    """
+
+    tags = {"ignore"}
+
+    def parse(self, parser: Parser) -> nodes.Node:
+        """Parse the `ignore` tag into a conditional on the current operation."""
+        lineno = next(parser.stream).lineno
+        body = parser.parse_statements(("name:endignore",), drop_needle=True)
+        # Render the body for every operation except `update`; during an update
+        # Copier omits it so the region stays developer-owned.
+        test = nodes.Compare(
+            nodes.Name("_copier_operation", "load", lineno=lineno),
+            [nodes.Operand("ne", nodes.Const("update", lineno=lineno))],
+            lineno=lineno,
+        )
+        return nodes.If(test, body, [], [], lineno=lineno)
+
+
 class UnsetError(UndefinedError): ...

copier/_main.py

@@ -45,12 +45,7 @@
 from questionary import confirm, unsafe_prompt
 
 from ._deprecation import deprecate_answers_file_template_path
-from ._jinja_ext import YieldExtension, get_yield_context
-from ._preserve import (
-    capture_preserved_regions,
-    find_marker_files,
-    restore_preserved_regions,
-)
+from ._jinja_ext import IgnoreExtension, YieldExtension, get_yield_context
 from ._settings import Settings, SettingsModel, is_trusted_repository
 from ._subproject import Subproject
 from ._template import Task, Template
@@ -473,6 +468,7 @@ def _render_context(self) -> AnyByStrMutableMapping:
             _folder_name=self.subproject.local_abspath.name,
             _copier_python=sys.executable,
             _copier_phase=Phase.current(),
+            _copier_operation=_operation.get(),
         )
 
     def _path_matcher(self, patterns: Iterable[str]) -> Callable[[Path], bool]:
@@ -712,6 +708,7 @@ def jinja_env(self) -> SandboxedEnvironment:
         default_extensions = [
             "jinja2_ansible_filters.AnsibleCoreFiltersExtension",
             YieldExtension,
+            IgnoreExtension,
         ]
         extensions = default_extensions + list(self.template.jinja_extensions)
         envops = dict(self.template.envops)
@@ -857,7 +854,7 @@ def _render_file(  # noqa: C901
                 new_content = src_abspath.read_bytes()
             else:
                 new_content = tpl.render(
-                    **self._render_context(), **(extra_context or {})
+                    {**self._render_context(), **(extra_context or {})}
                 ).encode()
                 if get_yield_context(self.jinja_env).yield_name:
                     raise YieldTagInFileError(
@@ -1180,7 +1177,7 @@ def _render_string(
                 Additional variables to use for rendering the template.
         """
         tpl = self.jinja_env.from_string(string)
-        return tpl.render(**self._render_context(), **(extra_context or {}))
+        return tpl.render({**self._render_context(), **(extra_context or {})})
 
     def _render_value(
         self, value: _T, extra_context: AnyByStrDict | None = None
@@ -1400,20 +1397,6 @@ def _apply_update(self) -> None:  # noqa: C901
                 ask=(),
             ) as old_worker:
                 old_worker.run_copy()
-            # Capture developer-owned regions marked for preservation.
-            # The old render tells us which template-managed files can contain
-            # markers, so we read the developer's current content only from
-            # those files (not the whole project tree). The captured content is
-            # then injected into every intermediate render so the merge sees
-            # identical region content on all sides and keeps it.
-            old_copy_root = old_copy / subproject_subdir
-            preserved = capture_preserved_regions(
-                self.subproject.local_abspath, find_marker_files(old_copy_root)
-            )
-            # Inject preserved regions into the old render (the merge base) so
-            # it matches the current project there - this keeps template changes
-            # inside those regions out of the computed diff.
-            restore_preserved_regions(old_copy_root, preserved)
             # Run pre-migration tasks
             with Phase.use(Phase.MIGRATE):
                 self._execute_tasks(
@@ -1467,10 +1450,6 @@ def _apply_update(self) -> None:  # noqa: C901
                 current_worker.run_copy()
                 self.answers = current_worker.answers
                 self.answers.external = self._external_data()
-            # Inject preserved regions into the freshly rendered destination so
-            # the developer's content survives regardless of how the historical
-            # diff below applies.
-            restore_preserved_regions(self.subproject.local_abspath, preserved)
             # Render with the same answers in an empty dir to avoid pollution
             with replace(
                 self,
@@ -1491,10 +1470,6 @@ def _apply_update(self) -> None:  # noqa: C901
                 ask=(),
             ) as new_worker:
                 new_worker.run_copy()
-            # Inject preserved regions into the new render (the merge "other"
-            # side) so it agrees with the base and current sides, leaving the
-            # region conflict-free during the merge.
-            restore_preserved_regions(new_copy / subproject_subdir, preserved)
             with local.cwd(new_copy):
                 self._git_initialize_repo()
                 new_copy_head = git("rev-parse", "HEAD").strip()