feat(updating): add VCS ref sentinel :current: for referring to the current template ref

Author: ytausch

copier/__init__.py

@@ -8,6 +8,7 @@
 
 from . import _main
 from ._deprecation import deprecate_member_as_internal
+from ._types import VcsRef as VcsRef
 
 if TYPE_CHECKING:
     from ._main import *  # noqa: F403

copier/_cli.py

@@ -59,8 +59,8 @@
 from plumbum import cli, colors
 
 from ._main import Worker
-from ._tools import copier_version
-from ._types import AnyByStrDict
+from ._tools import copier_version, try_enum
+from ._types import AnyByStrDict, VcsRef
 from .errors import UnsafeTemplateError, UserMessageError
 
 
@@ -134,7 +134,9 @@ def __init__(self, executable: PathLike[str]) -> None:
             "Git reference to checkout in `template_src`. "
             "If you do not specify it, it will try to checkout the latest git tag, "
             "as sorted using the PEP 440 algorithm. If you want to checkout always "
-            "the latest version, use `--vcs-ref=HEAD`."
+            "the latest version, use `--vcs-ref=HEAD`. "
+            "Use the special value `:current:` to refer to the current reference "
+            "of the template if it already exists."
         ),
     )
     pretend = cli.Flag(["-n", "--pretend"], help="Run but do not make any changes")
@@ -220,7 +222,7 @@ def _worker(
             skip_if_exists=self.skip,
             quiet=self.quiet,
             src_path=src_path,
-            vcs_ref=self.vcs_ref,
+            vcs_ref=try_enum(VcsRef, self.vcs_ref),
             use_prereleases=self.prereleases,
             unsafe=self.unsafe,
             skip_tasks=self.skip_tasks,

copier/_main.py

@@ -60,6 +60,7 @@
     Phase,
     RelativePath,
     StrOrPath,
+    VcsRef,
 )
 from ._user_data import AnswersMap, Question, load_answersfile_data
 from ._vcs import get_git
@@ -219,7 +220,7 @@ class Worker:
     src_path: str | None = None
     dst_path: Path = Path()
     answers_file: RelativePath | None = None
-    vcs_ref: str | None = None
+    vcs_ref: str | VcsRef | None = None
     data: AnyByStrDict = field(default_factory=dict)
     settings: Settings = field(default_factory=Settings.from_file)
     exclude: Sequence[str] = ()
@@ -398,7 +399,7 @@ def _render_context(self) -> AnyByStrMutableMapping:
                 "src_path": lambda: self.template.local_abspath,
                 "dst_path": lambda: self.dst_path,
                 "answers_file": lambda: self.answers_relpath,
-                "vcs_ref": lambda: self.vcs_ref,
+                "vcs_ref": lambda: self.resolved_vcs_ref,
                 "vcs_ref_hash": lambda: self.template.commit_hash,
                 "data": lambda: self.data,
                 "settings": lambda: self.settings,
@@ -953,6 +954,19 @@ def _render_value(
         except TypeError:
             return value
 
+    @cached_property
+    def resolved_vcs_ref(self) -> str | None:
+        """Get the resolved VCS reference to use.
+
+        This is either `vcs_ref` or the subproject template ref
+        if `vcs_ref` is `VcsRef.CURRENT`.
+        """
+        if self.vcs_ref is VcsRef.CURRENT:
+            if self.subproject.template is None:
+                raise TypeError("Template not found")
+            return self.subproject.template.ref
+        return self.vcs_ref
+
     @cached_property
     def subproject(self) -> Subproject:
         """Get related subproject."""
@@ -965,15 +979,13 @@ def subproject(self) -> Subproject:
 
     @cached_property
     def template(self) -> Template:
-        """Get related template."""
         url = self.src_path
         if not url:
             if self.subproject.template is None:
                 raise TypeError("Template not found")
             url = str(self.subproject.template.url)
-        result = Template(
-            url=url, ref=self.vcs_ref, use_prereleases=self.use_prereleases
-        )
+        ref = self.resolved_vcs_ref
+        result = Template(url=url, ref=ref, use_prereleases=self.use_prereleases)
         self._cleanup_hooks.append(result._cleanup)
         return result
 
@@ -1043,6 +1055,15 @@ def run_recopy(self) -> None:
         with replace(self, src_path=self.subproject.template.url) as new_worker:
             new_worker.run_copy()
 
+    def _print_template_update_info(self, subproject_template: Template) -> None:
+        # TODO Unify printing tools
+        if not self.quiet:
+            if subproject_template.version == self.template.version:
+                message = f"Keeping template version {self.template.version}"
+            else:
+                message = f"Updating to template version {self.template.version}"
+            print(message, file=sys.stderr)
+
     @as_operation("update")
     def run_update(self) -> None:
         """Update a subproject that was already generated.
@@ -1086,11 +1107,7 @@ def run_update(self) -> None:
             # asking for confirmation
             raise UserMessageError("Enable overwrite to update a subproject.")
         self._print_message(self.template.message_before_update)
-        if not self.quiet:
-            # TODO Unify printing tools
-            print(
-                f"Updating to template version {self.template.version}", file=sys.stderr
-            )
+        self._print_template_update_info(self.subproject.template)
         with suppress(AttributeError):
             # We might have switched operation context, ensure the cached property
             # is regenerated to re-render templates.
@@ -1202,6 +1219,7 @@ def _apply_update(self) -> None:  # noqa: C901
                 quiet=True,
                 src_path=self.subproject.template.url,  # type: ignore[union-attr]
                 exclude=exclude_plus_removed,
+                vcs_ref=self.resolved_vcs_ref,
             ) as new_worker:
                 new_worker.run_copy()
             with local.cwd(new_copy):

copier/_tools.py

@@ -15,7 +15,7 @@
 from importlib.metadata import version
 from pathlib import Path
 from types import TracebackType
-from typing import Any, Callable, Literal, TextIO, cast
+from typing import Any, Callable, Literal, TextIO, TypeVar, cast
 
 import colorama
 from packaging.version import Version
@@ -265,3 +265,18 @@ def scantree(path: str, follow_symlinks: bool) -> Iterator[os.DirEntry[str]]:
         yield entry
         if entry.is_dir(follow_symlinks=follow_symlinks):
             yield from scantree(entry.path, follow_symlinks)
+
+
+_T = TypeVar("_T")
+_E = TypeVar("_E", bound=Enum)
+
+
+def try_enum(enum_type: type[_E], value: _T) -> _E | _T:
+    """Try to convert a value into an enum.
+
+    If the value is not a valid enum member, return the original value.
+    """
+    try:
+        return enum_type(value)
+    except ValueError:
+        return value

copier/_types.py

@@ -125,3 +125,10 @@ def current(cls) -> Phase:
 
 
 _phase: ContextVar[Phase] = ContextVar("phase", default=Phase.UNDEFINED)
+
+
+class VcsRef(Enum):
+    CURRENT = ":current:"
+    """A special value to indicate that the current ref of the existing
+    template should be used.
+    """

docs/configuring.md

@@ -1721,7 +1721,7 @@ the `v2.0.0a1` tag unless this flag is enabled.
 
 ### `vcs_ref`
 
--   Format: `str`
+-   Format: `str | VcsRef`
 -   CLI flags: `-r`, `--vcs-ref`
 -   Default value: N/A (use latest release)
 
@@ -1738,8 +1738,10 @@ _commit: v1.0.0
 
     Not supported in `copier.yml`.
 
-By default, Copier will copy from the last release found in template Git tags, sorted as
-[PEP 440][].
+The special value `VcsRef.CURRENT` is set to indicate that the template version should
+be identical to the version already present. It is set when using `--vcs-ref=:current:`
+in the CLI. By default, Copier will copy from the last release found in template Git
+tags, sorted as [PEP 440][].
 
 ## Patterns syntax
 

docs/updating.md

@@ -142,6 +142,12 @@ copier update --defaults --data-file /tmp/data-file.yaml
     it is not yet possible to update a multiselect choice using ˋ--dataˋ.
     Use ˋ--data-fileˋ instead for now.
 
+If you want to update the answers to all questions, but not the template:
+
+```shell
+copier update --vcs-ref=:current:
+```
+
 ## How the update works
 
 To understand how the updating process works, take a look at this diagram:

tests/test_updatediff.py

@@ -13,6 +13,7 @@
 from copier._cli import CopierApp
 from copier._main import Worker, run_copy, run_update
 from copier._tools import normalize_git_path
+from copier._types import VcsRef
 from copier._user_data import load_answersfile_data
 from copier.errors import UserMessageError
 
@@ -25,6 +26,7 @@
     build_file_tree,
     git,
     git_init,
+    git_save,
 )
 
 
@@ -1603,6 +1605,65 @@ def test_update_with_skip_answered_and_new_answer(
     assert answers["boolean"] is True
 
 
+@pytest.mark.parametrize("cli", [True, False])
+def test_update_vcs_ref_current(
+    tmp_path_factory: pytest.TempPathFactory,
+    cli: bool,
+) -> None:
+    src, dst = map(tmp_path_factory.mktemp, ("src", "dst"))
+
+    with local.cwd(src):
+        build_file_tree(
+            {
+                "copier.yml": "boolean: false",
+                "{{ _copier_conf.answers_file }}.jinja": "{{ _copier_answers|to_nice_yaml }}",
+            }
+        )
+        git_init("v1")
+        git("tag", "v1")
+
+    if cli:
+        CopierApp.run(
+            ["copier", "copy", str(src), str(dst), "--defaults", "--overwrite"],
+            exit=False,
+        )
+    else:
+        run_copy(str(src), dst, defaults=True, overwrite=True)
+    answers = load_answersfile_data(dst)
+    assert answers["_commit"] == "v1"
+    assert answers["boolean"] is False
+
+    with local.cwd(dst):
+        git_init("v1")
+
+    with local.cwd(src):
+        build_file_tree({"README.md": "# Template Update"})
+        git_save(message="update template", tag="v2")
+
+    if cli:
+        with local.cwd(dst):
+            CopierApp.run(
+                [
+                    "copier",
+                    "update",
+                    "--data",
+                    "boolean=true",
+                    "--vcs-ref=:current:",
+                ],
+                exit=False,
+            )
+    else:
+        run_update(
+            dst, data={"boolean": "true"}, vcs_ref=VcsRef.CURRENT, overwrite=True
+        )
+    answers = load_answersfile_data(dst)
+    assert answers["_commit"] == "v1"
+    assert answers["boolean"] is True
+
+    # assert that the README.md file was not created
+    assert not (dst / "README.md").exists()
+
+
 def test_update_dont_validate_computed_value(
     tmp_path_factory: pytest.TempPathFactory,
 ) -> None: