feat: Add Git LFS integration for efficient multi-platform binary management

- Add 'generate_lfs_scripts' config option to enable LFS helper script generation
- Generate configure-lfs-skip-smudge.sh script to configure selective LFS downloads
- Generate .gitattributes file for proper LFS tracking of binary files
- Add comprehensive documentation for LFS integration workflow

This feature allows users to:
- Skip downloading binaries for non-current platforms automatically
- Save significant bandwidth and storage (e.g., 170MB vs 560MB for 3 platforms)
- Use simple 'git lfs pull' to get only current platform files
- Override with --include flag when other platforms are needed

The scripts are generated during 'dotbins sync' or 'dotbins init' when
generate_lfs_scripts: true is set in the configuration.

Author: basnijholt

dotbins/cli.py

@@ -90,6 +90,13 @@ def _initialize(config: Config) -> None:
     config.generate_shell_scripts()
     config.generate_readme()
 
+    # Generate LFS scripts if configured
+    if config.generate_lfs_scripts:
+        from .utils import write_gitattributes_for_lfs, write_lfs_skip_smudge_script
+
+        write_lfs_skip_smudge_script(config.tools_dir, config.platforms)
+        write_gitattributes_for_lfs(config.tools_dir)
+
 
 def _get_tool(source: str, dest_dir: str | Path, name: str | None = None) -> None:
     """Get a specific tool and install it directly to a location.

dotbins/config.py

@@ -27,6 +27,8 @@
     humanize_time_ago,
     log,
     replace_home_in_path,
+    write_gitattributes_for_lfs,
+    write_lfs_skip_smudge_script,
     write_shell_scripts,
 )
 from .versions import VersionStore
@@ -61,6 +63,7 @@ class Config:
     - The tools directory where binaries will be stored
     - Supported platforms and architectures
     - Tool definitions and their settings
+    - Git LFS configuration options
 
     The configuration is typically loaded from a YAML file, with tools
     organized by platform and architecture.
@@ -70,6 +73,7 @@ class Config:
     platforms: dict[str, list[str]] = field(default_factory=_default_platforms)
     tools: dict[str, ToolConfig] = field(default_factory=dict)
     defaults: DefaultsDict = field(default_factory=lambda: DEFAULTS.copy())
+    generate_lfs_scripts: bool = field(default=False)
     config_path: Path | None = field(default=None, init=False)
     _bin_dir: Path | None = field(default=None, init=False)
     _update_summary: UpdateSummary = field(default_factory=UpdateSummary, init=False)
@@ -244,6 +248,12 @@ def sync_tools(
             self.generate_readme(verbose=verbose)
         if generate_shell_scripts:
             self.generate_shell_scripts(print_shell_setup=False)
+
+        # Generate LFS scripts if configured
+        if self.generate_lfs_scripts:
+            write_lfs_skip_smudge_script(self.tools_dir, self.platforms)
+            write_gitattributes_for_lfs(self.tools_dir)
+
         _maybe_copy_config_file(copy_config_file, self.config_path, self.tools_dir)
 
     def generate_shell_scripts(self: Config, print_shell_setup: bool = True) -> None:
@@ -514,6 +524,7 @@ def _config_from_dict(data: RawConfigDict) -> Config:
     platforms = data.get("platforms", _default_platforms())
     raw_tools = data.get("tools", {})
     raw_defaults = data.get("defaults", {})
+    generate_lfs_scripts = bool(data.get("generate_lfs_scripts", False))
 
     defaults: DefaultsDict = DEFAULTS.copy()
     defaults.update(raw_defaults)  # type: ignore[typeddict-item]
@@ -536,6 +547,7 @@ def _config_from_dict(data: RawConfigDict) -> Config:
         platforms=platforms,
         tools=tool_configs,
         defaults=defaults,
+        generate_lfs_scripts=generate_lfs_scripts,
     )
     config.validate()
     return config

dotbins/utils.py

@@ -296,6 +296,149 @@ def write_shell_scripts(
         log(f"  [b]PowerShell:[/] [yellow]. {tools_dir2}/shell/powershell.ps1[/]", "info", "👉")
 
 
+def write_lfs_skip_smudge_script(
+    tools_dir: Path,
+    platforms: dict[str, list[str]],
+) -> None:
+    """Generate a Git LFS skip-smudge script for non-current architectures.
+
+    This script configures Git LFS to skip downloading (smudging) binary files
+    for architectures that are not the current system's architecture, saving
+    bandwidth and storage space.
+
+    Args:
+        tools_dir: The base directory where tools are installed
+        platforms: Dictionary mapping platform names to list of architectures
+
+    """
+    script_path = tools_dir / "configure-lfs-skip-smudge.sh"
+
+    script_content = textwrap.dedent("""\
+        #!/usr/bin/env bash
+        # Configure Git LFS to skip downloading files for non-current architectures
+        # Generated by dotbins
+
+        set -e
+
+        # Detect current OS and architecture
+        OS=$(uname -s | tr '[:upper:]' '[:lower:]')
+        [[ "$OS" == "darwin" ]] && OS="macos"
+
+        ARCH=$(uname -m)
+        [[ "$ARCH" == "x86_64" ]] && ARCH="amd64"
+        [[ "$ARCH" == "aarch64" || "$ARCH" == "arm64" ]] && ARCH="arm64"
+
+        CURRENT_PLATFORM="$OS/$ARCH"
+
+        echo "Detected platform: $CURRENT_PLATFORM"
+        echo ""
+        echo "This script will configure Git LFS to skip downloading files for other platforms."
+        echo "You only need to run this once after cloning the repository."
+        echo ""
+
+        # Create include patterns for current platform
+        include_patterns="$CURRENT_PLATFORM/bin/**"
+
+        # Create exclude patterns for all other platforms
+        exclude_patterns=""
+        """)
+
+    # Add exclude patterns for each platform/arch combination
+    for platform, architectures in platforms.items():
+        for arch in architectures:
+            script_content += f"""
+if [[ "$OS" != "{platform}" ]] || [[ "$ARCH" != "{arch}" ]]; then
+    exclude_patterns="${{exclude_patterns}} {platform}/{arch}/bin/**"
+fi"""
+
+    script_content += """
+
+echo "Setting up Git LFS skip-smudge for non-current platforms..."
+
+# Configure Git to skip smudge for specific paths
+# This prevents automatic downloading of LFS files during checkout
+for pattern in $exclude_patterns; do
+    echo "  Configuring skip for: $pattern"
+    # Set skip-smudge for specific paths
+    git config --local --add lfs.fetchexclude "$pattern"
+done
+
+echo ""
+echo "✅ LFS skip-smudge configuration complete!"
+echo ""
+echo "Files for your current platform ($CURRENT_PLATFORM) will be downloaded automatically."
+echo "Other platforms will be skipped to save bandwidth and disk space."
+echo ""
+echo "Useful commands:"
+echo "  Download current platform files: git lfs pull"
+echo "  Download a specific platform:    git lfs pull --include=\\"linux/amd64/bin/**\\""
+echo "  Download ALL platforms:          git lfs pull --include=\\"*\\""
+echo "  Check LFS file status:          git lfs ls-files"
+echo ""
+echo "To reset this configuration and download all platforms by default:"
+echo "  git config --local --unset-all lfs.fetchexclude"
+"""
+
+    with open(script_path, "w", encoding="utf-8") as f:
+        f.write(script_content)
+
+    # Make the script executable on Unix-like systems
+    if os.name != "nt":
+        script_path.chmod(script_path.stat().st_mode | 0o755)
+
+    tools_dir_str = replace_home_in_path(tools_dir, "~")
+    log(
+        f"Generated LFS skip-smudge script: {tools_dir_str}/configure-lfs-skip-smudge.sh",
+        "success",
+        "📝",
+    )
+
+
+def write_gitattributes_for_lfs(tools_dir: Path) -> None:
+    """Generate a .gitattributes file for Git LFS tracking of binary files.
+
+    Args:
+        tools_dir: The base directory where tools are installed
+
+    """
+    gitattributes_path = tools_dir / ".gitattributes"
+
+    # Common binary file extensions that should be tracked by LFS
+    gitattributes_content = textwrap.dedent("""\
+        # Git LFS tracking for binary files
+        # Generated by dotbins
+
+        # Track all files in platform directories as LFS
+        linux/*/bin/* filter=lfs diff=lfs merge=lfs -text
+        macos/*/bin/* filter=lfs diff=lfs merge=lfs -text
+        windows/*/bin/* filter=lfs diff=lfs merge=lfs -text
+
+        # Track common binary extensions
+        *.exe filter=lfs diff=lfs merge=lfs -text
+        *.dll filter=lfs diff=lfs merge=lfs -text
+        *.so filter=lfs diff=lfs merge=lfs -text
+        *.dylib filter=lfs diff=lfs merge=lfs -text
+        *.appimage filter=lfs diff=lfs merge=lfs -text
+        *.AppImage filter=lfs diff=lfs merge=lfs -text
+
+        # Track archives (in case any are stored)
+        *.zip filter=lfs diff=lfs merge=lfs -text
+        *.tar filter=lfs diff=lfs merge=lfs -text
+        *.tar.gz filter=lfs diff=lfs merge=lfs -text
+        *.tgz filter=lfs diff=lfs merge=lfs -text
+        *.tar.bz2 filter=lfs diff=lfs merge=lfs -text
+        *.tar.xz filter=lfs diff=lfs merge=lfs -text
+        *.7z filter=lfs diff=lfs merge=lfs -text
+        *.rar filter=lfs diff=lfs merge=lfs -text
+        """)
+
+    with open(gitattributes_path, "w", encoding="utf-8") as f:
+        f.write(gitattributes_content)
+
+    tools_dir_str = replace_home_in_path(tools_dir, "~")
+    log(f"Generated .gitattributes for LFS: {tools_dir_str}/.gitattributes", "success", "📝")
+
+
 STYLE_EMOJI_MAP = {
     "success": "✅",
     "error": "❌",