feat: Add _copier_conf.operation variable

copier/main.py

@@ -59,7 +59,9 @@
     MISSING,
     AnyByStrDict,
     JSONSerializable,
+    Operation,
     RelativePath,
+    Self,
     StrOrPath,
 )
 from .user_data import DEFAULT_DATA, AnswersMap, Question
@@ -205,6 +207,7 @@ class Worker:
     skip_tasks: bool = False
 
     answers: AnswersMap = field(default_factory=AnswersMap, init=False)
+    operation: Operation = field(init=False, default="copy")
     _cleanup_hooks: list[Callable[[], None]] = field(default_factory=list, init=False)
 
     def __enter__(self) -> Worker:
@@ -242,7 +245,7 @@ def _cleanup(self) -> None:
         for method in self._cleanup_hooks:
             method()
 
-    def _check_unsafe(self, mode: Literal["copy", "update"]) -> None:
+    def _check_unsafe(self, mode: Operation) -> None:
         """Check whether a template uses unsafe features."""
         if self.unsafe:
             return
@@ -587,7 +590,7 @@ def _pathjoin(
     @cached_property
     def match_exclude(self) -> Callable[[Path], bool]:
         """Get a callable to match paths against all exclusions."""
-        return self._path_matcher(self.all_exclusions)
+        return self._path_matcher(map(self._render_string, self.all_exclusions))
 
     @cached_property
     def match_skip(self) -> Callable[[Path], bool]:
@@ -809,6 +812,14 @@ def template_copy_root(self) -> Path:
         subdir = self._render_string(self.template.subdirectory) or ""
         return self.template.local_abspath / subdir
 
+    def replace(self, **kwargs: Any) -> Self:
+        """Wraps dataclasses.replace to support replacing the init=False operation field."""
+        operation = kwargs.pop("operation", self.operation)
+        new = replace(self, **kwargs)
+        if operation in ("copy", "update"):
+            new.operation = operation
+        return new
+
     # Main operations
     def run_copy(self) -> None:
         """Generate a subproject from zero, ignoring what was in the folder.
@@ -854,7 +865,7 @@ def run_recopy(self) -> None:
                 "Cannot recopy because cannot obtain old template references "
                 f"from `{self.subproject.answers_relpath}`."
             )
-        with replace(self, src_path=self.subproject.template.url) as new_worker:
+        with self.replace(src_path=self.subproject.template.url) as new_worker:
             new_worker.run_copy()
 
     def run_update(self) -> None:
@@ -904,8 +915,10 @@ def run_update(self) -> None:
             print(
                 f"Updating to template version {self.template.version}", file=sys.stderr
             )
-        self._apply_update()
-        self._print_message(self.template.message_after_update)
+        with self.replace(operation="update") as worker:
+            worker._apply_update()
+            worker._print_message(worker.template.message_after_update)
+            self.answers = worker.answers
 
     def _apply_update(self) -> None:  # noqa: C901
         git = get_git()
@@ -927,8 +940,7 @@ def _apply_update(self) -> None:  # noqa: C901
             prefix=f"{__name__}.dst_copy.",
         ) as dst_copy:
             # Copy old template into a temporary destination
-            with replace(
-                self,
+            with self.replace(
                 dst_path=old_copy / subproject_subdir,
                 data=self.subproject.last_answers,
                 defaults=True,
@@ -990,8 +1002,7 @@ def _apply_update(self) -> None:  # noqa: C901
                 with suppress(AttributeError):
                     del self.subproject.last_answers
             # Do a normal update in final destination
-            with replace(
-                self,
+            with self.replace(
                 # Don't regenerate intentionally deleted paths
                 exclude=exclude_plus_removed,
                 # Files can change due to the historical diff, and those
@@ -1003,10 +1014,9 @@ def _apply_update(self) -> None:  # noqa: C901
                 current_worker.run_copy()
                 self.answers = current_worker.answers
             # Render with the same answers in an empty dir to avoid pollution
-            with replace(
-                self,
+            with self.replace(
                 dst_path=new_copy / subproject_subdir,
-                data=self.answers.combined,  # type: ignore[arg-type]
+                data=self.answers.combined,
                 defaults=True,
                 quiet=True,
                 src_path=self.subproject.template.url,  # type: ignore[union-attr]

copier/types.py

@@ -21,6 +21,11 @@
 else:
     from typing_extensions import Annotated
 
+if sys.version_info >= (3, 11):
+    from typing import Self as Self
+else:
+    from typing_extensions import Self as Self
+
 # simple types
 StrOrPath = Union[str, Path]
 AnyByStrDict = Dict[str, Any]
@@ -40,6 +45,7 @@
 Env = Mapping[str, str]
 MissingType = NewType("MissingType", object)
 MISSING = MissingType(object())
+Operation = Literal["copy", "update"]
 
 
 # Validators

docs/configuring.md

@@ -858,6 +858,18 @@ to know available options.
 
 The CLI option can be passed several times to add several patterns.
 
+Each pattern can be templated using Jinja.
+
+!!! example
+
+    Templating `exclude` patterns using `_copier_conf.operation` allows to have files
+    that are rendered once during `copy`, but are never updated:
+
+    ```yaml
+    _exclude:
+        - '{%- if _copier_conf.operation == "update" -%}src/*_example.py{%- endif %}'
+    ```
+
 !!! info
 
     When you define this parameter in `copier.yml`, it will **replace** the default
@@ -1316,6 +1328,8 @@ configuring `secret: true` in the [advanced prompt format][advanced-prompt-forma
 exist, but always be present. If they do not exist in a project during an `update`
 operation, they will be recreated.
 
+Each pattern can be templated using Jinja.
+
 !!! example
 
     For example, it can be used if your project generates a password the 1st time and

docs/creating.md

@@ -99,3 +99,6 @@ Copier includes:
     -   It contains the current commit hash from the template in
         `{{ _copier_conf.vcs_ref_hash }}`.
     -   Contains Operating System-specific directory separator under `sep` key.
+    -   It also contains the current `operation` (`copy` | `update`). This value is
+        intended to be used for templating Copier configuration. It cannot be used in
+        templated project paths and files.

pyproject.toml

@@ -40,7 +40,7 @@ pydantic = ">=2.4.2"
 pygments = ">=2.7.1"
 pyyaml = ">=5.3.1"
 questionary = ">=1.8.1"
-typing-extensions = { version = ">=3.7.4,<5.0.0", python = "<3.9" }
+typing-extensions = { version = ">=4.0.0,<5.0.0", python = "<3.11" }
 eval-type-backport = { version = ">=0.1.3,<0.3.0", python = "<3.10" }
 
 [tool.poetry.group.dev]

tests/test_context.py

@@ -0,0 +1,77 @@
+import pytest
+from plumbum import local
+
+import copier
+
+from .helpers import build_file_tree, git_save
+
+
+@pytest.mark.parametrize("operation", ("recopy", "update"))
+def test_operation_in_context_matches(
+    operation: str, tmp_path_factory: pytest.TempPathFactory
+) -> None:
+    """
+    Ensure that the _copier_conf.operation context variable is set
+    as expected during template rendering.
+    """
+    src, dst = map(tmp_path_factory.mktemp, ("src", "dst"))
+    with local.cwd(src):
+        build_file_tree(
+            {
+                # Ensure the file is regenerated on update.
+                "copier.yml": "_skip_if_exists: [foo]",
+                "{{ _copier_conf.answers_file }}.jinja": "{{ _copier_answers|to_yaml }}",
+                "foo.jinja": "{{ _copier_conf.operation }}",
+            }
+        )
+        git_save(tag="1.0.0")
+
+    copier.run_copy(str(src), dst, defaults=True, overwrite=True)
+    ctx_file = dst / "foo"
+    assert ctx_file.read_text() == "copy"
+    # Ensure the file is regenerated on update.
+    # If we left it, an update would detect custom changes
+    # that would be reapplied, i.e. an update would leave us with `copy`.
+    ctx_file.unlink()
+    with local.cwd(dst):
+        git_save()
+    getattr(copier, f"run_{operation}")(str(dst), overwrite=True)
+    expected = "copy" if operation == "recopy" else operation
+    assert ctx_file.read_text() == expected
+
+
+def test_exclude_templating_with_operation(tmp_path_factory: pytest.TempPathFactory) -> None:
+    """
+    Ensure it's possible to create one-off boilerplate files
+    that are not managed during updates.
+    """
+    src, dst = map(tmp_path_factory.mktemp, ("src", "dst"))
+    exclude = r"{%- if _copier_conf.operation == 'update' %}dumb_boilerplate{%- endif %}"
+    with local.cwd(src):
+        build_file_tree(
+            {
+                "copier.yml": f"_exclude:\n - \"{exclude}\"",
+                "{{ _copier_conf.answers_file }}.jinja": "{{ _copier_answers|to_yaml }}",
+                "dumb_boilerplate": "foo",
+                "other_file": "foo",
+            }
+        )
+        git_save(tag="1.0.0")
+        build_file_tree(
+            {
+                "dumb_boilerplate": "bar",
+                "other_file": "bar",
+            }
+        )
+        git_save(tag="2.0.0")
+    copier.run_copy(str(src), dst, defaults=True, overwrite=True, vcs_ref="1.0.0")
+    boilerplate = dst / "dumb_boilerplate"
+    other_file = dst / "other_file"
+    for file in (boilerplate, other_file):
+        assert file.exists()
+        assert file.read_text() == "foo"
+    with local.cwd(dst):
+        git_save()
+    copier.run_update(str(dst), overwrite=True)
+    assert boilerplate.read_text() == "foo"
+    assert other_file.read_text() == "bar"