Selectively Clearing Cache Folders (#1268)

This pull request enhances the `clear-cache` command in the HoloHub CLI
by introducing new flags to allow users to selectively clear specific
types of cache folders. The changes improve usability and maintain
backward compatibility with previous behavior.

**CLI Feature Enhancements:**

* Added `--build`, `--data`, and `--install` flags to the `clear-cache`
command, allowing users to clear only build, data, or install folders,
respectively.
[[1]](diffhunk://#diff-9c212b6b2b7ad0d4afe9fc076b7d9988417d1b6f1c99de4bbb4e445798e55e4dR436-R440)
[[2]](diffhunk://#diff-1ef9cb2fbb55a15400848086c55046b4c552ea60d34e315fd638a0ca0c5396bbR124-R126)

**Implementation Details:**

* Updated the `handle_clear_cache` method in `holohub.py` to process the
new flags, collecting only the relevant directories based on user input.
If no flags are provided, all cache folders are cleared to maintain
backward compatibility.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **New Features**
* The clear-cache command now supports selective cache clearing with
three new options: `--build`, `--data`, and `--install`. Each option
restricts cache clearing to the corresponding folder type. When no
option is specified, all cache categories are cleared, maintaining
backward compatibility with existing workflows.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Signed-off-by: B Hashemian <[email protected]>

Author: bhashemian

README.md

@@ -207,23 +207,36 @@ Make sure you build the application (if applicable) before running it.
 
 ## Cleanup
 
-You can run the command below to reset cache directories:
+> [!IMPORTANT]
+> Many applications use custom container environments with specific build and runtime dependencies. If you encounter issues with missing or broken build tools between different applications, clearing the build cache should be your first troubleshooting step.
 
-  ```sh
-  ./holohub clear-cache
-  ```
+Clear cache directories using the `clear-cache` command:
 
-This removes the `build`, `data`, and `install` directories. You can use `--dryrun` to preview what would be removed.
+```sh
+# Clear all cache folders (build, data, install)
+./holohub clear-cache
 
-In some cases you may want to clear out only the datasets downloaded by applications to the `data` folder:
+# Clear specific cache types
+./holohub clear-cache --build      # Build folders only
+./holohub clear-cache --data       # Data folders only
+./holohub clear-cache --install    # Install folders only
 
-  ```sh
-  rm -rf ./data
-  ```
+# Combine flags to clear multiple types
+./holohub clear-cache --build --data
+
+# Preview what would be removed without actually deleting
+./holohub clear-cache --dryrun
+./holohub clear-cache --build --dryrun
+```
 
-Note that many applications supply custom container environments with build and runtime dependencies.
-Failing to clean the build cache between different applications may result in unexpected behavior where build
-tools or libraries appear to be broken or missing. Clearing the build cache is a good first check to address those issues.
+> [!TIP]
+> If you encounter permission issues when clearing cache, run the command inside a container with root privileges:
+>
+> ```sh
+> ./holohub run-container --as-root -- ./holohub clear-cache
+> ```
+>
+> This is safer than using `sudo` directly, as it maintains proper container isolation and avoids changing file ownership.
 
 ## Contributing
 

utilities/cli/holohub.py

@@ -436,6 +436,11 @@ def _create_parser(self) -> argparse.ArgumentParser:
         clear_cache.add_argument(
             "--dryrun", action="store_true", help="Print commands without executing them"
         )
+        clear_cache.add_argument("--build", action="store_true", help="Clear build folders only")
+        clear_cache.add_argument("--data", action="store_true", help="Clear data folders only")
+        clear_cache.add_argument(
+            "--install", action="store_true", help="Clear install folders only"
+        )
         clear_cache.set_defaults(func=self.handle_clear_cache)
 
         # Add vscode command
@@ -2038,21 +2043,48 @@ def handle_install(self, args: argparse.Namespace) -> None:
                 extra_args=extra_args,
             )
 
+    def _collect_cache_dirs(self, patterns: list[str], default_dir=None) -> list:
+        """Helper to collect cache directories matching patterns."""
+        dirs = []
+        if default_dir is not None:
+            dirs.append(default_dir)
+        for pattern in patterns:
+            for path in HoloHubCLI.HOLOHUB_ROOT.glob(pattern):
+                if path.is_dir() and path not in dirs:
+                    dirs.append(path)
+        return dirs
+
     def handle_clear_cache(self, args: argparse.Namespace) -> None:
         """Handle clear-cache command"""
+        # Determine which folders to clear
+        clear_build = getattr(args, "build", False)
+        clear_data = getattr(args, "data", False)
+        clear_install = getattr(args, "install", False)
+
+        # If no flags are provided, clear all (backward compatibility)
+        clear_all = not (clear_build or clear_data or clear_install)
+
         if args.dryrun:
             print(Color.blue("Would clear cache folders:"))
         else:
             print(Color.blue("Clearing cache..."))
 
-        cache_dirs = [
-            self.DEFAULT_BUILD_PARENT_DIR,
-            self.DEFAULT_DATA_DIR,
-        ]
-        for pattern in ["build", "build-*", "data", "data-*", "install"]:
-            for path in HoloHubCLI.HOLOHUB_ROOT.glob(pattern):
-                if path.is_dir() and path not in cache_dirs:
-                    cache_dirs.append(path)
+        cache_dirs = []
+
+        # Collect build folders if needed
+        if clear_all or clear_build:
+            cache_dirs.extend(
+                self._collect_cache_dirs(["build", "build-*"], self.DEFAULT_BUILD_PARENT_DIR)
+            )
+
+        # Collect data folders if needed
+        if clear_all or clear_data:
+            cache_dirs.extend(self._collect_cache_dirs(["data", "data-*"], self.DEFAULT_DATA_DIR))
+
+        # Collect install folders if needed
+        if clear_all or clear_install:
+            cache_dirs.extend(self._collect_cache_dirs(["install", "install-*"]))
+
         for path in set(cache_dirs):
             if path.exists() and path.is_dir():
                 if args.dryrun: