feat: use treeless sparse checkout for remote template cloning (#899)

Use --filter=tree:0 with sparse checkout when fetching remote templates
with a known template path. This dramatically reduces clone time and disk
usage for large monorepos like adk-samples by only downloading git objects
for the specific subdirectory needed.

When no template path is specified (e.g. discovery/listing), the existing
full shallow clone is preserved since the entire repo tree is needed.

Author: eliasecchig

agent_starter_pack/cli/utils/remote_template.py

@@ -270,19 +270,27 @@ def fetch_remote_template(
     # Attempt Git Clone
     try:
         clone_url = spec.repo_url
-
-        # Build clone command with --single-branch (optimized for branches)
-        clone_cmd = [
-            "git",
-            "clone",
-            "--depth",
-            "1",
-            "--single-branch",
-            "--branch",
-            spec.git_ref,
-            clone_url,
-            str(repo_path),
-        ]
+        git_env = {**os.environ, "GIT_TERMINAL_PROMPT": "0"}
+
+        # Use sparse checkout when a specific template path is known — significantly
+        # faster for large monorepos since only the needed subdirectory is downloaded.
+        use_sparse_checkout = bool(spec.template_path)
+
+        clone_cmd = ["git", "clone"]
+        if use_sparse_checkout:
+            clone_cmd.append("--no-checkout")
+        clone_cmd.extend(
+            [
+                "--depth",
+                "1",
+                "--single-branch",
+                "--branch",
+                spec.git_ref,
+            ]
+        )
+        if use_sparse_checkout:
+            clone_cmd.append("--filter=tree:0")
+        clone_cmd.extend([clone_url, str(repo_path)])
 
         logging.debug(
             f"Attempting to clone remote template with Git: {' '.join(clone_cmd)}"
@@ -293,7 +301,7 @@ def fetch_remote_template(
             capture_output=True,
             text=True,
             encoding="utf-8",
-            env={**os.environ, "GIT_TERMINAL_PROMPT": "0"},
+            env=git_env,
         )
 
         # If clone with --single-branch fails, retry without it (for tags)
@@ -303,23 +311,25 @@ def fetch_remote_template(
                 logging.debug(
                     f"Clone with --single-branch failed, retrying without it (git_ref '{spec.git_ref}' is likely a tag)"
                 )
-                clone_cmd_without_single_branch = [
+                clone_cmd_retry = [
                     "git",
                     "clone",
                     "--depth",
                     "1",
                     "--branch",
                     spec.git_ref,
-                    clone_url,
-                    str(repo_path),
                 ]
+                if use_sparse_checkout:
+                    clone_cmd_retry.extend(["--no-checkout", "--filter=tree:0"])
+                clone_cmd_retry.extend([clone_url, str(repo_path)])
+
                 subprocess.run(
-                    clone_cmd_without_single_branch,
+                    clone_cmd_retry,
                     capture_output=True,
                     text=True,
                     check=True,
                     encoding="utf-8",
-                    env={**os.environ, "GIT_TERMINAL_PROMPT": "0"},
+                    env=git_env,
                 )
                 logging.debug("Git clone successful (without --single-branch).")
             else:
@@ -329,6 +339,24 @@ def fetch_remote_template(
                 )
         else:
             logging.debug("Git clone successful.")
+
+        # Set up sparse checkout to materialize only the needed template path
+        if use_sparse_checkout:
+            sparse_cmds = [
+                ["git", "sparse-checkout", "set", spec.template_path + "/"],
+                ["git", "checkout", spec.git_ref],
+            ]
+            for cmd in sparse_cmds:
+                subprocess.run(
+                    cmd,
+                    capture_output=True,
+                    text=True,
+                    check=True,
+                    encoding="utf-8",
+                    cwd=str(repo_path),
+                    env=git_env,
+                )
+            logging.debug(f"Sparse checkout configured for path: {spec.template_path}")
     except subprocess.CalledProcessError as e:
         shutil.rmtree(temp_path, ignore_errors=True)
         raise RuntimeError(f"Git clone failed: {e.stderr.strip()}") from e

tests/cli/utils/test_remote_template.py

@@ -184,6 +184,92 @@ def test_fetch_remote_template_path_not_found(
 
         mock_rmtree.assert_called_once()
 
+    @patch("subprocess.run")
+    @patch("tempfile.mkdtemp")
+    @patch("shutil.rmtree")
+    def test_fetch_uses_sparse_checkout_when_template_path_set(
+        self,
+        mock_rmtree: MagicMock,
+        mock_mkdtemp: MagicMock,
+        mock_subprocess: MagicMock,
+    ) -> None:
+        """Test that fetch uses treeless clone + sparse checkout when template_path is set"""
+        mock_mkdtemp.return_value = "/tmp/test_dir"
+        mock_subprocess.return_value = MagicMock(returncode=0, stderr="")
+
+        spec = RemoteTemplateSpec(
+            repo_url="https://github.com/google/adk-samples",
+            template_path="python/agents/data-science",
+            git_ref="main",
+            is_adk_samples=True,
+        )
+
+        # Make template_dir.exists() return True to avoid FileNotFoundError
+        with (
+            patch("pathlib.Path.exists", return_value=True),
+            patch(
+                "agent_starter_pack.cli.utils.remote_template.check_and_execute_with_version_lock",
+                return_value=False,
+            ),
+        ):
+            fetch_remote_template(spec)
+
+        # Verify the clone command uses --filter=tree:0 and --no-checkout
+        clone_call = mock_subprocess.call_args_list[0]
+        clone_cmd = clone_call[0][0]
+        assert "--filter=tree:0" in clone_cmd
+        assert "--no-checkout" in clone_cmd
+
+        # Verify sparse checkout commands were called
+        sparse_set_call = mock_subprocess.call_args_list[1]
+        sparse_cmd = sparse_set_call[0][0]
+        assert sparse_cmd == [
+            "git",
+            "sparse-checkout",
+            "set",
+            "python/agents/data-science/",
+        ]
+
+        checkout_call = mock_subprocess.call_args_list[2]
+        checkout_cmd = checkout_call[0][0]
+        assert checkout_cmd == ["git", "checkout", "main"]
+
+    @patch("subprocess.run")
+    @patch("tempfile.mkdtemp")
+    @patch("shutil.rmtree")
+    def test_fetch_uses_full_clone_when_no_template_path(
+        self,
+        mock_rmtree: MagicMock,
+        mock_mkdtemp: MagicMock,
+        mock_subprocess: MagicMock,
+    ) -> None:
+        """Test that fetch uses full shallow clone when template_path is empty"""
+        mock_mkdtemp.return_value = "/tmp/test_dir"
+        mock_subprocess.return_value = MagicMock(returncode=0, stderr="")
+
+        spec = RemoteTemplateSpec(
+            repo_url="https://github.com/google/adk-samples",
+            template_path="",
+            git_ref="main",
+        )
+
+        with (
+            patch("pathlib.Path.exists", return_value=True),
+            patch(
+                "agent_starter_pack.cli.utils.remote_template.check_and_execute_with_version_lock",
+                return_value=False,
+            ),
+        ):
+            fetch_remote_template(spec)
+
+        # Verify the clone command does NOT use --filter=tree:0
+        clone_call = mock_subprocess.call_args_list[0]
+        clone_cmd = clone_call[0][0]
+        assert "--filter=tree:0" not in clone_cmd
+        assert "--no-checkout" not in clone_cmd
+        # Should only have the clone call, no sparse checkout commands
+        assert len(mock_subprocess.call_args_list) == 1
+
 
 class TestLoadRemoteTemplateConfig:
     def test_load_remote_template_config_primary_location(self) -> None: