feat: exclude well-known global cache directories (#3)

* docs(readme): clarify that asimov only affects Time Machine, not Spotlight

Add a note explaining that asimov does not hide directories from
Spotlight indexing, with guidance on how to configure Spotlight privacy
settings separately.

Addresses stevegrunwell#90.

* feat(sentinels): add .NET project build directory exclusions

Exclude bin/ and obj/ directories when *.csproj (C#) or *.fsproj (F#)
project files are present, using glob sentinel patterns.

Inspired by stevegrunwell#87, props @guigomesa.

* feat: skip already-excluded directories for faster subsequent runs

Use Spotlight metadata (mdfind) to identify directories already excluded
from Time Machine and skip them during the find traversal. Also fixes a
comment typo and removes duplicate Gradle sentinel entries.

Inspired by stevegrunwell#97, props @VladRassokhin.

* feat: exclude well-known global cache directories

Add fixed directory exclusions for common tool caches (~/.cache,
~/.gradle/caches, ~/.m2/repository, ~/.npm/_cacache, ~/.nuget/packages,
~/.kube/cache) that are always safe to exclude without sentinel files.

Inspired by stevegrunwell#69, props @pkuczynski.

Author: django23

CHANGELOG.md

@@ -10,6 +10,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 * Support glob patterns in sentinel definitions, enabling wildcards like `*.xcodeproj` ([stevegrunwell/asimov#64], props @mdab121)
 * Exclude Xcode DerivedData when `*.xcodeproj` is present ([stevegrunwell/asimov#64], props @mdab121)
+* Exclude well-known global cache directories (`~/.cache`, `~/.gradle/caches`, `~/.m2/repository`, `~/.npm/_cacache`, `~/.nuget/packages`, `~/.kube/cache`, etc.) without requiring sentinel files (inspired by [stevegrunwell/asimov#69], props @pkuczynski)
 * Exclude Next.js build cache (`.next`)
 * Exclude Nuxt build cache (`.nuxt`)
 * Exclude Angular CLI cache (`.angular`)
@@ -35,11 +36,17 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Changed
 
+* Skip directories already excluded from Time Machine backups for faster subsequent runs (inspired by [stevegrunwell/asimov#97], props @VladRassokhin)
 * Migrated test suite from PHP/PHPUnit to [Bats](https://github.com/bats-core/bats-core) (Bash Automated Testing System), removing the PHP dependency for contributors
 * Replaced Travis CI pipeline with GitHub Actions (macOS 14 + 15 matrix)
 * Replaced PHP `tmutil` mock with a pure bash implementation
 * Moved install script to `scripts/install.sh` with shared variables, now copies binary instead of symlinking ([#35], props @sylver)
 
+### Fixed
+
+* Fixed duplicate Gradle sentinel entries in the sentinels list
+* Fixed typo in comment ("decendents" → "descendants")
+
 ### Removed
 
 * Removed PHP test infrastructure (`composer.json`, `phpunit.xml.dist`, and PHP test files)
@@ -121,4 +128,6 @@ Initial public release.
 [#35]: https://github.com/stevegrunwell/asimov/pull/35
 [#56]: https://github.com/stevegrunwell/asimov/pull/56
 [stevegrunwell/asimov#64]: https://github.com/stevegrunwell/asimov/pull/64
+[stevegrunwell/asimov#69]: https://github.com/stevegrunwell/asimov/pull/69
 [stevegrunwell/asimov#87]: https://github.com/stevegrunwell/asimov/pull/87
+[stevegrunwell/asimov#97]: https://github.com/stevegrunwell/asimov/pull/97

Makefile

@@ -9,7 +9,7 @@ test: ## Run Bats tests
 	@bats tests/sentinels.bats tests/behavior.bats
 
 lint: ## Run Shellcheck on all shell scripts
-	@shellcheck asimov scripts/install.sh scripts/uninstall.sh tests/bin/run-tests.sh tests/bin/tmutil
+	@shellcheck asimov scripts/install.sh scripts/uninstall.sh tests/bin/run-tests.sh tests/bin/tmutil tests/bin/mdfind
 
 check: test lint ## Run tests and linting
 

README.md

@@ -49,6 +49,7 @@ Asimov recognizes dependency directories across **30+ patterns** in these ecosys
 | **R** | `renv` |
 | **DevOps / IaC** | `.terraform`, `.terragrunt-cache`, `.vagrant`, `.direnv`, `cdk.out` |
 | **Game dev** | `.godot` |
+| **Global caches** | `~/.cache`, `~/.gradle/caches`, `~/.m2/repository`, `~/.npm/_cacache`, `~/.nuget/packages`, `~/.kube/cache` |
 
 Each directory is only excluded when its corresponding config file (the "sentinel") exists — so `node_modules` is only excluded if `package.json` is present, `vendor` only if `composer.json`, `go.mod`, or `Gemfile` exists, etc.
 
@@ -94,7 +95,9 @@ brew uninstall asimov
 
 ## How it works
 
-Asimov is a thin wrapper around Apple's [`tmutil`](https://ss64.com/mac/tmutil.html). It builds a single `find` command from all known dependency patterns, walks your home directory (skipping `~/Library` and `~/.Trash`), and pipes matching paths through `tmutil addexclusion`. Directories already excluded are skipped automatically — safe to run as often as you like.
+Asimov is a thin wrapper around Apple's [`tmutil`](https://ss64.com/mac/tmutil.html). It builds a single `find` command from all known dependency patterns, walks your home directory (skipping `~/Library` and `~/.Trash`), and pipes matching paths through `tmutil addexclusion`. It also unconditionally excludes well-known global tool caches (like `~/.cache`, `~/.gradle/caches`, and `~/.npm/_cacache`) that can always be safely restored. Directories already excluded are skipped automatically — safe to run as often as you like.
+
+> **Note:** Asimov only excludes directories from Time Machine backups. It does not affect Spotlight indexing. To prevent Spotlight from indexing a directory, add it to the Privacy tab in System Settings > Spotlight (or Siri & Spotlight on newer macOS versions).
 
 > **Note:** Asimov only excludes directories from Time Machine backups. It does not affect Spotlight indexing. To prevent Spotlight from indexing a directory, add it to the Privacy tab in System Settings > Spotlight (or Siri & Spotlight on newer macOS versions).
 

asimov

@@ -20,7 +20,7 @@ set -Eeu -o pipefail
 readonly ASIMOV_ROOT=~
 
 # Paths to unconditionally skip over. This prevents Asimov from modifying the
-# Time Machine exclusions for these paths (and decendents). It has an important
+# Time Machine exclusions for these paths (and descendants). It has an important
 # side-effect of speeding up the search.
 readonly ASIMOV_SKIP_PATHS=(
     ~/.Trash
@@ -51,8 +51,6 @@ readonly ASIMOV_VENDOR_DIR_SENTINELS=(
     'Pods Podfile'                     # CocoaPods
     'DerivedData *.xcodeproj'          # Xcode DerivedData
     'bower_components bower.json'      # Bower (JavaScript)
-    'build build.gradle'               # Gradle
-    'build build.gradle.kts'           # Gradle Kotlin Script
     'build pubspec.yaml'               # Flutter (Dart)
     'build setup.py'                   # Python
     'dist setup.py'                    # PyPI Publishing (Python)
@@ -98,6 +96,22 @@ readonly ASIMOV_VENDOR_DIR_SENTINELS=(
     'renv renv.lock'                   # renv (R)
 )
 
+# A list of fixed directories to exclude from Time Machine backups.
+#
+# Unlike sentinel-based pairs above, these directories are always excluded
+# when they exist — they represent global tool caches and artifacts that
+# can be safely restored.
+readonly ASIMOV_FIXED_DIRS=(
+    ~/.cache                           # XDG cache directory
+    ~/.gradle/caches                   # Gradle download cache
+    ~/.gradle/wrapper                  # Gradle wrapper distributions
+    ~/.m2/repository                   # Maven local repository
+    ~/.npm/_cacache                    # npm content-addressable cache
+    ~/.nuget/packages                  # NuGet global packages
+    ~/.kube/cache                      # Kubernetes API cache
+    ~/.kube/http-cache                 # Kubernetes HTTP cache
+)
+
 # Exclude the given paths from Time Machine backups.
 # Reads the newline-separated list of paths from stdin.
 exclude_file() {
@@ -121,6 +135,13 @@ for d in "${ASIMOV_SKIP_PATHS[@]}"; do
     find_parameters_skip+=( -not \( -path "${d}" -prune \) )
 done
 
+# Skip directories already excluded from Time Machine backups.
+# Uses Spotlight metadata which may not report all exclusions — any missed
+# directories are still handled by the tmutil isexcluded check in exclude_file().
+while IFS= read -r line; do
+    [[ -n "$line" ]] && find_parameters_skip+=( -not \( -path "${line}" -prune \) )
+done < <(mdfind -onlyin "${ASIMOV_ROOT}" "com_apple_backup_excludeItem = 'com.apple.backupd'" 2>/dev/null | sort -u)
+
 # Iterate over the directory/sentinel pairs to construct the `find` expression.
 declare -a find_parameters_vendor=()
 for i in "${ASIMOV_VENDOR_DIR_SENTINELS[@]}"; do
@@ -159,3 +180,11 @@ printf '\n\033[0;36mFinding dependency directories with corresponding definition
 find "${ASIMOV_ROOT}" \( "${find_parameters_skip[@]}" \) \( -false "${find_parameters_vendor[@]}" \) \
     | exclude_file \
     ;
+
+# Exclude fixed directories (global tool caches) when they exist.
+printf '\n\033[0;36mExcluding known cache directories…\033[0m\n'
+for dir in "${ASIMOV_FIXED_DIRS[@]}"; do
+    if [[ -d "$dir" ]]; then
+        echo "$dir"
+    fi
+done | exclude_file

tests/behavior.bats

@@ -141,3 +141,69 @@ load test_helper
   refute_excluded "${HOME}/Code/My-Project/node_modules/dep/node_modules"
   [[ "$(count_exclusions)" -eq 1 ]]
 }
+
+# =============================================================================
+# Skip already-excluded directories (mdfind optimization)
+# =============================================================================
+
+@test "skips directories already excluded from Time Machine" {
+  create_project "Code/Already-Excluded" "package.json" "node_modules"
+  create_project "Code/New-Project" "package.json" "node_modules"
+
+  # Pre-exclude the first project manually
+  echo "${HOME}/Code/Already-Excluded/node_modules" > "$ASIMOV_TEST_EXCLUSIONS"
+
+  # Tell mock mdfind to report it as already excluded
+  ASIMOV_TEST_MDFIND_RESULTS="${TEST_TEMP_DIR}/.mdfind_results"
+  export ASIMOV_TEST_MDFIND_RESULTS
+  echo "${HOME}/Code/Already-Excluded" > "$ASIMOV_TEST_MDFIND_RESULTS"
+
+  run_asimov
+
+  # The new project should be excluded
+  assert_excluded "${HOME}/Code/New-Project/node_modules"
+  # The already-excluded one should still only have 1 entry (not duplicated)
+  [[ "$(count_exclusions)" -eq 2 ]]
+}
+
+# =============================================================================
+# Fixed directories (global caches)
+# =============================================================================
+
+@test "excludes fixed directory when it exists" {
+  mkdir -p "${HOME}/.cache"
+  run_asimov
+  assert_excluded "${HOME}/.cache"
+}
+
+@test "does not fail when fixed directory does not exist" {
+  # Don't create any fixed dirs — asimov should still succeed
+  run_asimov
+  [[ "$status" -eq 0 ]]
+  [[ "$(count_exclusions)" -eq 0 ]]
+}
+
+@test "excludes multiple fixed directories when they exist" {
+  mkdir -p "${HOME}/.cache"
+  mkdir -p "${HOME}/.gradle/caches"
+  mkdir -p "${HOME}/.npm/_cacache"
+  run_asimov
+  assert_excluded "${HOME}/.cache"
+  assert_excluded "${HOME}/.gradle/caches"
+  assert_excluded "${HOME}/.npm/_cacache"
+  [[ "$(count_exclusions)" -eq 3 ]]
+}
+
+@test "does not re-exclude already excluded fixed directory" {
+  mkdir -p "${HOME}/.cache"
+  run_asimov
+  assert_excluded "${HOME}/.cache"
+  local first_count
+  first_count="$(count_exclusions)"
+  [[ "$first_count" -eq 1 ]]
+
+  run_asimov
+  local second_count
+  second_count="$(count_exclusions)"
+  [[ "$second_count" -eq 1 ]]
+}

tests/bin/mdfind

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# Mock mdfind for testing — returns nothing by default.
+# Set ASIMOV_TEST_MDFIND_RESULTS to a file path to return its contents.
+set -euo pipefail
+
+if [[ -n "${ASIMOV_TEST_MDFIND_RESULTS:-}" && -f "${ASIMOV_TEST_MDFIND_RESULTS}" ]]; then
+    cat "${ASIMOV_TEST_MDFIND_RESULTS}"
+fi