feat(repo): detect stale clones and report a clear error

When templatron runs without --autoclean (the default), it leaves
clone directories under the clone root. On a re-run, the previous
templatron-* update branch is still present in the local clone, so
'git checkout -b <update_branch>' fails with sh.ErrorReturnCode_128
and the user sees a raw traceback with no hint that the fix is to
delete the clone or pass --autoclean.

- Add StaleCloneError to surface this case as a TemplatronException.
- Add BaseRepo.local_branch_exists() helper for cheap pre-checks.
- Guard switch_to_update_branch() to raise StaleCloneError up front,
  with a message naming the branch, the clone path, and the two
  remediation options.
- Broaden onboard()'s exception handler from
  UnrecognizableBaseBranchError to TemplatronException, matching how
  update() already handles repo-level failures, so StaleCloneError
  (and any future TemplatronException subclasses raised from a repo's
  onboard flow) exit cleanly via die() instead of escaping as a raw
  traceback.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 2 people

templatron/exceptions.py

@@ -22,6 +22,10 @@ class MissingRequiredConfigError(TemplatronException):
     pass
 
 
+class StaleCloneError(TemplatronException):
+    pass
+
+
 class TemplateConfigMissingError(TemplatronException):
     pass
 

templatron/repo/base_repo.py

@@ -103,6 +103,13 @@ def git_cmd(self, cmd, *args):
             return git(cmd, *args)
         return git(cmd, *args, _cwd=self.clone_path)
 
+    def local_branch_exists(self, branch):
+        try:
+            self.git_cmd("rev-parse", "--verify", f"refs/heads/{branch}")
+            return True
+        except ErrorReturnCode:
+            return False
+
     def maybe_switch_branch(self):
         if self.active_branch == self.base_branch:
             return

templatron/repo/repository.py

@@ -7,7 +7,7 @@
 from copier import run_copy, run_update
 
 from templatron.commit_template import commit_template
-from templatron.exceptions import HookFailure
+from templatron.exceptions import HookFailure, StaleCloneError
 from templatron.log_or_print import log_or_print
 from templatron.repo.base_repo import BaseRepo
 
@@ -316,6 +316,14 @@ def switch_to_update_branch(self):
             return
 
         self.logger.debug(f"switch to update branch {self.update_branch_name}")
+        if self.local_branch_exists(self.update_branch_name):
+            raise StaleCloneError(
+                f"branch '{self.update_branch_name}' already exists in "
+                f"{self.clone_path} — likely left behind by a previous "
+                "run that didn't clean up. Delete the clone directory "
+                "and retry, or pass --autoclean to remove clones "
+                "automatically."
+            )
         self.git_cmd("checkout", "-b", self.update_branch_name)
 
     def update(self, operation="updating"):

templatron/templatron.py

@@ -181,7 +181,7 @@ def onboard(self, onboarding_repo):
         try:
             repo = self.build_repo(onboarding_repo)
             repo.onboard()
-        except UnrecognizableBaseBranchError as error:
+        except TemplatronException as error:
             self.die(error)
         except KeyboardInterrupt:
             self.maybe_clean()

test/test_repo/test_base_repo.py

@@ -7,7 +7,7 @@
 from unittest import TestCase
 from unittest.mock import MagicMock, patch
 
-from sh import ErrorReturnCode
+from sh import ErrorReturnCode, ErrorReturnCode_1
 
 from templatron.exceptions import DirtyRepoError, UnrecognizableBaseBranchError
 from templatron.repo.base_repo import BaseRepo
@@ -222,6 +222,30 @@ def test_git_cmd_no_clone(self, mock_git):
         self.test_repo.git_cmd("commit", "some args")
         mock_git.assert_called_with("commit", "some args", _cwd="/fake/root/fake repo")
 
+    @patch("templatron.repo.base_repo.BaseRepo.git_cmd")
+    def test_local_branch_exists_true(self, mock_git):
+        """
+        Test BaseRepo.local_branch_exists() returns True when
+        git rev-parse --verify succeeds.
+        """
+
+        self.assertTrue(self.test_repo.local_branch_exists("fake_branch"))
+        mock_git.assert_called_with(
+            "rev-parse", "--verify", "refs/heads/fake_branch"
+        )
+
+    @patch("templatron.repo.base_repo.BaseRepo.git_cmd")
+    def test_local_branch_exists_false(self, mock_git):
+        """
+        Test BaseRepo.local_branch_exists() returns False when
+        git rev-parse --verify exits non-zero (branch missing).
+        """
+
+        mock_git.side_effect = ErrorReturnCode_1(
+            full_cmd="git", stdout=b"", stderr=b""
+        )
+        self.assertFalse(self.test_repo.local_branch_exists("fake_branch"))
+
     @patch.object(BaseRepo, "active_branch", "fake_branch")
     @patch.object(BaseRepo, "base_branch", "fake_branch")
     @patch("templatron.repo.base_repo.BaseRepo.git_cmd")

test/test_repo/test_repository.py

@@ -9,7 +9,7 @@
 from unittest import TestCase
 from unittest.mock import MagicMock, patch
 
-from templatron.exceptions import HookFailure
+from templatron.exceptions import HookFailure, StaleCloneError
 from templatron.repo.repository import Repository
 from templatron.repo.template import Template
 
@@ -572,16 +572,36 @@ def test_switch_to_update_branch_fixing(self, mock_git):
         mock_git.assert_not_called()
 
     @patch.object(Repository, "update_branch_name", "fake_branch")
+    @patch("templatron.repo.repository.Repository.local_branch_exists")
     @patch("templatron.repo.repository.Repository.git_cmd")
-    def test_switch_to_update_branch_not_fixing(self, mock_git):
+    def test_switch_to_update_branch_not_fixing(self, mock_git, mock_exists):
         """
         Docs
         """
 
+        mock_exists.return_value = False
         self.test_repo.operation = "not fixing"
         self.test_repo.switch_to_update_branch()
         mock_git.assert_called_with("checkout", "-b", "fake_branch")
 
+    @patch.object(Repository, "update_branch_name", "fake_branch")
+    @patch("templatron.repo.repository.Repository.local_branch_exists")
+    @patch("templatron.repo.repository.Repository.git_cmd")
+    def test_switch_to_update_branch_stale_branch(
+        self, mock_git, mock_exists
+    ):
+        """
+        Test switch_to_update_branch() raises StaleCloneError when the
+        target update branch already exists locally — typically from a
+        prior run that didn't clean up.
+        """
+
+        mock_exists.return_value = True
+        self.test_repo.operation = "not fixing"
+        with self.assertRaisesRegex(StaleCloneError, "fake_branch"):
+            self.test_repo.switch_to_update_branch()
+        mock_git.assert_not_called()
+
     @patch.object(Repository, "needs_update", True)
     @patch("templatron.repo.repository.Repository.clean_stale_branches")
     @patch("templatron.repo.repository.Repository.clone")

test/test_templatron.py

@@ -15,6 +15,7 @@
     TemplatronException,
     GitConfigError,
     MissingRequiredConfigError,
+    StaleCloneError,
     UnrecognizableBaseBranchError,
 )
 from templatron.templatron import Templatron
@@ -476,6 +477,26 @@ def test_onboard_unrecognizable_branch(
         mock_start.assert_called_with("onboarding")
         mock_stop.assert_not_called()
 
+    @patch("templatron.templatron.Templatron.die")
+    @patch("templatron.templatron.Templatron.start")
+    @patch("templatron.templatron.Templatron.build_repo")
+    @patch("templatron.templatron.Templatron.stop")
+    def test_onboard_stale_clone(
+        self, mock_stop, mock_build, mock_start, mock_die
+    ):
+        """
+        Test Templatron.onboard() exits cleanly via die() when the
+        repo's update branch already exists from a prior run, rather
+        than letting the exception propagate as a raw traceback.
+        """
+
+        mock_build().onboard.side_effect = StaleCloneError("stale")
+        mock_die.side_effect = SystemExit
+        with self.assertRaises(SystemExit):
+            self.templatron.onboard("repo")
+        mock_start.assert_called_with("onboarding")
+        mock_stop.assert_not_called()
+
     @patch("templatron.templatron.Templatron.maybe_clean")
     @patch("templatron.templatron.Templatron.start")
     @patch("templatron.templatron.Templatron.build_repo")