Add tag handling to scratch checkout

Author: tpoliaw

src/blueapi/cli/scratch.py

@@ -48,12 +48,15 @@ def setup_scratch(
             )
     for repo in config.repositories:
         local_directory = config.root / repo.name
-        ensure_repo(repo.remote_url, local_directory, repo.branch)
+        ensure_repo(repo.remote_url, local_directory, repo.branch, repo.tag)
         scratch_install(local_directory, timeout=install_timeout)
 
 
 def ensure_repo(
-    remote_url: str, local_directory: Path, branch: str | None = None
+    remote_url: str,
+    local_directory: Path,
+    branch: str | None = None,
+    tag: str | None = None,
 ) -> None:
     """
     Ensure that a repository is checked out for use in the scratch area.
@@ -64,34 +67,43 @@ def ensure_repo(
         local_directory: Output path for cloning
     """
 
+    if tag and branch:
+        raise ValueError(f"Can't use both branch ({branch!r}) and tag ({tag!r})")
+
     # Set umask to DLS standard
     os.umask(stat.S_IWOTH)
 
     if not local_directory.exists():
         LOGGER.info(f"Cloning {remote_url}")
         repo = Repo.clone_from(remote_url, local_directory)
         LOGGER.info(f"Cloned {remote_url} -> {local_directory}")
+        if branch:
+            if not (local := getattr(repo.heads, branch, None)):
+                origin = repo.remotes[0]
+                origin.fetch()
+                LOGGER.info(
+                    "Creating branch '%s' to track remote '%s'",
+                    branch,
+                    origin.refs[branch],
+                )
+                local = repo.create_head(branch, origin.refs[branch])
+                local.set_tracking_branch(origin.refs[branch])
+
+            LOGGER.info("Checking out branch %r", branch)
+            local.checkout()
+        elif tag:
+            if tag_obj := getattr(repo.tags, tag, None):
+                LOGGER.info("Checking out tag %r", tag)
+                tag_obj.checkout()
+            else:
+                raise ValueError("Could not find tag: " + repr(tag))
     elif local_directory.is_dir():
-        repo = Repo(local_directory)
         LOGGER.info(f"Found {local_directory}")
     else:
         raise KeyError(
             f"Unable to open {local_directory} as a git repository because it is a file"
         )
 
-    if branch:
-        if not (local := getattr(repo.heads, branch, None)):
-            origin = repo.remotes[0]
-            origin.fetch()
-            LOGGER.info(
-                "Creating branch '%s' to track remote '%s'", branch, origin.refs[branch]
-            )
-            local = repo.create_head(branch, origin.refs[branch])
-            local.set_tracking_branch(origin.refs[branch])
-
-        LOGGER.info("Checking out branch '%s'", branch)
-        local.checkout()
-
 
 def scratch_install(path: Path, timeout: float = _DEFAULT_INSTALL_TIMEOUT) -> None:
     """

src/blueapi/config.py

@@ -6,7 +6,7 @@
 from functools import cached_property
 from pathlib import Path
 from string import Template
-from typing import Annotated, Any, ClassVar, Generic, Literal, TypeVar, cast
+from typing import Annotated, Any, ClassVar, Generic, Literal, Self, TypeVar, cast
 
 import requests
 import yaml
@@ -21,6 +21,7 @@
     UrlConstraints,
     ValidationError,
     field_validator,
+    model_validator,
 )
 from pydantic.json_schema import SkipJsonSchema
 
@@ -192,10 +193,14 @@ class ScratchRepository(BlueapiBaseModel):
         default="https://github.com/example/example.git",
     )
     branch: str | SkipJsonSchema[None] = Field(
-        description=(
-            "Branch of repo to check out - defaults to remote's default when "
-            "cloning and the existing branch when the repo already exists"
-        ),
+        description="Branch of repo to check out - defaults to remote's default",
+        exclude_if=lambda f: f is None,
+        # using default_factory instead of default means the schema doesn't
+        # include an invalid value
+        default_factory=lambda: None,
+    )
+    tag: str | SkipJsonSchema[None] = Field(
+        description="Tag of repo to check out.",
         exclude_if=lambda f: f is None,
         # using default_factory instead of default means the schema doesn't
         # include an invalid value
@@ -209,6 +214,14 @@ def check_remote_url(cls, value: str) -> str:
             raise ValueError(f"remote_url '{value}' is not allowed.")
         return value
 
+    @model_validator(mode="after")
+    def check_clone_options(self) -> Self:
+        if self.branch is not None and self.tag is not None:
+            raise ValueError(
+                f"Cannot set both branch ({self.branch}) and tag ({self.tag})"
+            )
+        return self
+
 
 class ScratchConfig(BlueapiBaseModel):
     root: Path = Field(