feat(backend): add filter_bins option to github/gitlab backends

docs/dev-tools/backends/github.md

@@ -170,6 +170,20 @@ bin_path = "{name}-{version}/bin" # expands to cli-1.0.0/bin
 3. If no `bin/` directory exists, search subdirectories for `bin/` directories
 4. If no `bin/` directories are found, use the root of the extracted directory
 
+### `filter_bins`
+
+Comma-separated list of binaries to symlink into a filtered `.mise-bins` directory. This is useful when the tool comes with extra binaries that you do not want to expose on PATH.
+
+```toml
+[tools]
+"github:jgm/pandoc" = { version = "latest", filter_bins = "pandoc" }
+```
+
+When enabled:
+
+- A `.mise-bins` subdirectory is created with symlinks only to the specified binaries
+- Other binaries (like `pandoc-lua` or `pandoc-server`) are not exposed on PATH
+
 ### `api_url`
 
 For GitHub Enterprise or self-hosted GitHub instances, specify the API URL:

docs/dev-tools/backends/gitlab.md

@@ -185,6 +185,20 @@ bin_path = "{name}-{version}/bin" # expands to gitlab-runner-1.0.0/bin
 3. If no `bin/` directory exists, search subdirectories for `bin/` directories
 4. If no `bin/` directories are found, use the root of the extracted directory
 
+### `filter_bins`
+
+Comma-separated list of binaries to symlink into a filtered `.mise-bins` directory. This is useful when the tool comes with extra binaries that you do not want to expose on PATH.
+
+```toml
+[tools]
+"gitlab:myorg/mytool" = { version = "1.0.0", filter_bins = "mybin" }
+```
+
+When enabled:
+
+- A `.mise-bins` subdirectory is created with symlinks only to the specified binaries
+- Other binaries are not exposed on PATH
+
 ### `api_url`
 
 For self-hosted GitLab instances, specify the API URL:

e2e/backend/test_github_filter_bins

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+
+# Test filter_bins option for github backend using pandoc.
+# We use pandoc because it is a compiled binary and comes with multiple binaries to filter.
+
+if [[ "$(uname -s)" != "Linux" ]]; then
+	echo "Skipping Linux-specific test on non-Linux OS"
+	exit 0
+fi
+
+export MISE_EXPERIMENTAL=1
+
+mise install "github:jgm/pandoc[filter_bins=pandoc]@3.8.2"
+
+bin_path="$(mise where github:jgm/[email protected])/.mise-bins"
+assert_directory_exists "$bin_path"
+
+bins=$(find "$bin_path" -maxdepth 1 \( -type l -o -type f \) -print0 | xargs -0 -n1 basename | sort | tr '\n' ' ')
+assert_contains "echo '$bins'" "pandoc"
+assert_not_contains "echo '$bins'" "pandoc-lua"
+assert_not_contains "echo '$bins'" "pandoc-server"

src/backend/github.rs

@@ -8,6 +8,7 @@ use crate::backend::static_helpers::{
 use crate::cli::args::BackendArg;
 use crate::config::Config;
 use crate::config::Settings;
+use crate::file;
 use crate::http::HTTP;
 use crate::install_context::InstallContext;
 use crate::toolset::ToolVersionOptions;
@@ -123,15 +124,11 @@ impl Backend for UnifiedGitBackend {
         _config: &Arc<Config>,
         tv: &ToolVersion,
     ) -> Result<Vec<std::path::PathBuf>> {
-        let opts = tv.request.options();
-        if let Some(bin_path_template) =
-            lookup_platform_key(&opts, "bin_path").or_else(|| opts.get("bin_path").cloned())
-        {
-            let bin_path = template_string(&bin_path_template, tv);
-            Ok(vec![tv.install_path().join(&bin_path)])
-        } else {
-            self.discover_bin_paths(tv)
+        if self.get_filter_bins(tv).is_some() {
+            return Ok(vec![tv.install_path().join(".mise-bins")]);
         }
+
+        self.discover_bin_paths(tv)
     }
 
     fn resolve_lockfile_options(
@@ -277,11 +274,23 @@ impl UnifiedGitBackend {
         install_artifact(tv, &file_path, opts, Some(ctx.pr.as_ref()))?;
         self.verify_checksum(ctx, tv, &file_path)?;
 
+        if let Some(bins) = self.get_filter_bins(tv) {
+            self.create_symlink_bin_dir(tv, bins)?;
+        }
+
         Ok(())
     }
 
     /// Discovers bin paths in the installation directory
     fn discover_bin_paths(&self, tv: &ToolVersion) -> Result<Vec<std::path::PathBuf>> {
+        let opts = tv.request.options();
+        if let Some(bin_path_template) =
+            lookup_platform_key(&opts, "bin_path").or_else(|| opts.get("bin_path").cloned())
+        {
+            let bin_path = template_string(&bin_path_template, tv);
+            return Ok(vec![tv.install_path().join(&bin_path)]);
+        }
+
         let bin_path = tv.install_path().join("bin");
         if bin_path.exists() {
             return Ok(vec![bin_path]);
@@ -533,6 +542,60 @@ impl UnifiedGitBackend {
             tag_name.to_string()
         }
     }
+
+    fn get_filter_bins(&self, tv: &ToolVersion) -> Option<Vec<String>> {
+        let opts = tv.request.options();
+        let filter_bins = lookup_platform_key(&opts, "filter_bins")
+            .or_else(|| opts.get("filter_bins").cloned())?;
+
+        Some(
+            filter_bins
+                .split(',')
+                .map(|s| s.trim().to_string())
+                .filter(|s| !s.is_empty())
+                .collect(),
+        )
+    }
+
+    /// Creates a `.mise-bins` directory with symlinks only to the binaries specified in filter_bins.
+    fn create_symlink_bin_dir(&self, tv: &ToolVersion, bins: Vec<String>) -> Result<()> {
+        let symlink_dir = tv.install_path().join(".mise-bins");
+        file::create_dir_all(&symlink_dir)?;
+
+        // Find where the actual binaries are
+        let install_path = tv.install_path();
+        let bin_paths = self.discover_bin_paths(tv)?;
+
+        // Collect all possible source directories (install root + discovered bin paths)
+        let mut src_dirs = bin_paths;
+        if !src_dirs.contains(&install_path) {
+            src_dirs.push(install_path);
+        }
+
+        for bin_name in bins {
+            // Find the binary in any of the source directories
+            let mut found = false;
+            for dir in &src_dirs {
+                let src = dir.join(&bin_name);
+                if src.exists() {
+                    let dst = symlink_dir.join(&bin_name);
+                    if !dst.exists() {
+                        file::make_symlink_or_copy(&src, &dst)?;
+                    }
+                    found = true;
+                    break;
+                }
+            }
+
+            if !found {
+                warn!(
+                    "Could not find binary '{}' in install directories. Available paths: {:?}",
+                    bin_name, src_dirs
+                );
+            }
+        }
+        Ok(())
+    }
 }
 
 #[cfg(test)]