Add configuration option to skip search paths (#107)

* feat(config): add configuration option for skip search paths

* docs(readme): Update readme to describe the skip_paths configuration

* docs(readme): add optional directory argument to CLI summary.

update CLI usage summary to include optional directory argument mirroring actual CLI help text.

* feat(tests): add [skip_paths] config behavior test

* docs(changelog): add [skip_paths] config option to changelog

* feat(config): scan directories beyond home via [scan] extra

Add a [scan] section to ~/.config/asimov/config with one `extra =` line per
additional root; each is scanned on every run alongside the home directory.

- Resolve all roots into a single ASIMOV_SCAN_DIRS array; every consumer
  (Spotlight cache, path cache scoping, mdfind discovery, find traversal) loops
  over it instead of a lone ASIMOV_SCAN_DIR
- A positional CLI argument still overrides everything (scans only that path)
- Configured dirs that don't exist are warned about (honoring --quiet) and
  skipped, so an unmounted volume doesn't abort the run
- Nested/duplicate roots are pruned so no tree is traversed twice

Closes #108

* docs: prepare v0.9.0 stable release

- CHANGELOG: promote [scan] and Go-cache entries into [0.9.0], date 2026-07-26
- README: Install split into Homebrew (homebrew-core) + curl; document [scan];
  drop the retired django23 tap; note the pending homebrew-core 0.3.0→0.9.0 bump
- UPGRADING: point install commands at the stable curl one-liner
- CONTRIBUTING: Homebrew distribution is homebrew-core; mark tap targets legacy
- Makefile: verify-release falls back to `brew install asimov` (core), not the tap

* chore(release): bump version to 0.10.0

Stable release carrying the v0.9.0-beta fixes plus the new [scan] multi-scan
feature. A new feature is a minor bump under semver, so the beta line's 0.9.0
becomes 0.10.0 for stable (there was no 0.9.0 stable).

* docs(readme): correct homebrew-core version note (version-agnostic)

* docs,build: homebrew-core autobumps; drop retired tap tooling

- Makefile: remove bump-formula/ship-formula/TAP_DIR (tap archived); release
  target points at homebrew-core autobump; verify-release notes the ~3h lag
- README: homebrew note is now version-agnostic (formula auto-updates)
- CONTRIBUTING: release flow drops the tap steps; document that asimov is on
  Homebrew's autobump list (version PRs are automatic; only metadata needs a
  manual PR)

* docs(contributing): add concise release pipeline overview (PR → release → brew)

* chore: gitignore docs/triage (local maintainer notes)

* ci: test across both macOS bash versions in a parallel matrix

asimov starts with #!/usr/bin/env bash, so it runs under whichever bash comes
first on PATH. On macOS that is one of two very different things: /bin/bash,
still 3.2 because Apple froze it at the last GPLv2 release and what most users
get, or a 5.x build from Homebrew, which is what a development machine usually
has. They disagree on array and IFS semantics, so until now a change could pass
`make check` locally and CI and still be broken for users.

CI now runs os × bash (4 cells, all concurrent, fail-fast off so one failing
combination cannot hide the others). ShellCheck moves into its own job because it
is interpreter-independent and only needs to run once; it runs alongside the test
cells rather than four times over. A concurrency group cancels an in-flight run
when the same ref is pushed again.

Locally, `make test-system-bash` runs the suite under 3.2, and
`make test BASH_BIN=<path>` pins any interpreter. Both go through the new
scripts/test.sh, which sets ASIMOV_TEST_BASH; the Bats helper then launches
asimov with that interpreter explicitly, so Bats itself keeps running under its
own bash rather than being dragged down to 3.2 by a PATH shim.

`make test BATS_JOBS=N` runs tests concurrently (needs GNU parallel). Each test
already gets its own temp HOME in setup(), so there is no shared state.

* docs(readme): add a "What Asimov doesn't do" section

Covers the three most common misconceptions: Asimov sets Time Machine
exclusions only, it does not hide directories from Spotlight, and it does
not shrink backups that already exist. Adds a short verification recipe
for the "my node_modules is still in Time Machine" case.

Refs #90, #45

* feat(prune): add an asimov prune subcommand

Reports Time Machine exclusions whose directory no longer exists and
compacts Asimov's own path cache.

The premise of #38 turned out not to hold for Asimov's own work: every
version in git history calls `tmutil addexclusion PATH`, which stores the
exclusion as an extended attribute on the directory, so deleting the
directory deletes the exclusion with it. Nothing is left behind.

Staleness lives in the other mechanism — `tmutil addexclusion -p`, which
records the path in Time Machine's system preferences and survives the
directory forever. Asimov has never written that list, but other tools and
manual commands do, and nothing surfaces the leftovers.

So prune reports rather than removes: the entries are system-wide and not
ours to delete. It prints the `sudo tmutil removeexclusion -p` command
instead. The only file it writes is Asimov's own cache.

Closes #38

* fix(cache): survive an unreadable or unwritable cache

The cache under ~/.cache/asimov is an optimisation, but nothing treated it
as optional. A bare `cat` on an unreadable state file failed under
`set -Eeu -o pipefail` and aborted the run immediately, printing nothing
but "Permission denied" — no context, no fix, exit 1.

The cause was Asimov itself. ensure_cache_dir chowned the cache directory
to the console user when running as root, but the state files were created
*after* that chown, so every `sudo asimov` left root-owned files behind and
broke the next run as the user.

Guard every cache read and write behind cache_readable/cache_writable, warn
once naming the reset command, and carry on without the cache. Create the
state files before the chown so appends — which never change an existing
file's owner — keep them owned by the user who has to read them next.

Closes #122

* feat(doctor): add an asimov doctor subcommand

Checks the install rather than the projects: which asimov the shell
actually runs, whether a schedule is installed and loaded, whether the
cache is readable and writable, whether the config parses, and whether
tmutil can read exclusions at all. Exits 1 if it finds anything.

Two rules keep it safe to run part-way through a migration. It never
writes — fixes are printed, not applied. And it never executes another
asimov binary it finds: v0.3.0 parses no arguments at all, so running it
to ask its version would start a real scan, so versions are read out of
the file instead.

The test helper now strips any real asimov install from PATH, since doctor
inspects PATH and would otherwise report a different result per machine.

Refs #122

* docs: cover upgrading from v0.3.0 and document doctor

v0.3.0 is the version most people have, and it parses no arguments at all:
`asimov --version` and `asimov doctor` are both ignored and it goes
straight to scanning. So the upgrade notes lead with a version check that
reads the file instead of running it, and put `asimov doctor` last, after
the new binary is in place.

Also documents the three leftovers that outlive a v0.3.0 install — the
LaunchAgent, the old cellar, and a root-owned cache — and that Asimov is a
one-shot scan, not a daemon, so an empty `ps aux | grep asimov` after
`brew services start` is expected.

Refs #122

* chore(lint): shellcheck the launchctl test mock (#124)

Every other script under tests/bin/ is linted; the launchctl mock added
alongside `asimov doctor` was missed.

Co-authored-by: django23 <827397+django23@users.noreply.github.com>

* docs: release 0.11.0 (#125)

* test(doctor): derive the expected version from the script

The version assertion hardcoded 0.10.0, so it failed the moment the
release bump landed. Read it from `asimov --version` instead.

* docs: release 0.11.0

---------

Co-authored-by: django23 <827397+django23@users.noreply.github.com>

* feat(config): fold [skip_paths] into ASIMOV_SKIP_PATHS and teach doctor about it

Follow-up to the [skip_paths] work: append the configured paths to
ASIMOV_SKIP_PATHS at definition time instead of merging them into a local
array in each consumer, so the find expression and the Spotlight pass stay
in step, add the section to the doctor config validator (it reported
[skip_paths] as an unknown section), and cover both in tests.

The behaviour test passed an absolute path to create_project, which prefixes
$HOME - so the project was built outside the skipped directory and the test
passed for the wrong reason. Fixed, plus a control case that fails without
the config, a multi-entry case, and one proving [fixed_dirs] still wins
inside a skipped path.

---------

Co-authored-by: django23 <827397+django23@users.noreply.github.com>
Co-authored-by: Django E <djangoboy@gmail.com>

Author: lunaluxie

CHANGELOG.md

@@ -8,6 +8,8 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Added
 
+- `[skip_paths]` config section: name directories that Asimov should never search, alongside the built-in `~/.Trash` and `~/Library`. Thanks [@lunaluxie](https://github.com/lunaluxie)!
+
 - `asimov doctor` now checks the data files and reports how many sentinels and fixed directories are loaded, so an incomplete install is diagnosed rather than just failing.
 
 ### Changed

README.md

@@ -131,7 +131,7 @@ If `mdfind` doesn't list your projects, the run isn't reaching them. The two usu
 ## Usage
 
 ```
-asimov [--dry-run] [--verbose] [--quiet] [--stats] [--no-read-cache] [--no-write-cache] [--help] [--version]
+asimov [--dry-run] [--verbose] [--quiet] [--stats] [--no-read-cache] [--no-write-cache] [--help] [--version] [directory]
 asimov prune  [--quiet]
 asimov doctor [--quiet]
 ```
@@ -274,6 +274,20 @@ extra   = ~/my-build-cache       # plus any paths you name (always excluded when
 extra   = ~/golang/pkg/mod       # e.g. a Go module cache under a custom GOPATH
 ```
 
+### Skip parts of your home directory
+
+Asimov never descends into `~/.Trash` or `~/Library`. Add directories of your own under `[skip_paths]` and they're left alone too - not searched, never excluded:
+
+```ini
+[skip_paths]
+extra = ~/Music                  # one "extra =" line per directory
+extra = ~/Pictures
+```
+
+This only narrows the *search*. Global caches you opted into under `[fixed_dirs]` are still excluded, even inside a skipped path.
+
+If all your code lives in one folder, scanning just that folder (`asimov ~/Code`, see [usage](#usage)) is usually simpler than skipping everything else.
+
 ## Other install methods
 
 **From source:**

lib/asimov/config.sh

@@ -14,6 +14,7 @@ load_config() {
     ASIMOV_CONFIG_EXTRA_SENTINELS=()
     ASIMOV_CONFIG_DISABLED_SENTINELS=()
     ASIMOV_CONFIG_SCAN_DIRS=()
+    ASIMOV_CONFIG_EXTRA_SKIP_PATHS=()
 
     [[ -f "$ASIMOV_CONFIG_FILE" ]] || return 0
 
@@ -52,6 +53,10 @@ load_config() {
                 sentinels:disabled)
                     ASIMOV_CONFIG_DISABLED_SENTINELS+=("$value")
                     ;;
+                skip_paths:extra)
+                    value="${value/#\~/$HOME}"
+                    ASIMOV_CONFIG_EXTRA_SKIP_PATHS+=("$value")
+                    ;;
             esac
         fi
     done < "$ASIMOV_CONFIG_FILE"

lib/asimov/data.sh

@@ -64,7 +64,9 @@ load_fixed_dirs() {
     done < "$file"
 }
 
-# Load data/skip-paths.tsv into ASIMOV_SKIP_PATHS (absolute).
+# Load data/skip-paths.tsv into ASIMOV_SKIP_PATHS (absolute), then append the
+# paths named under [skip_paths] in the config. Both the find expression and the
+# Spotlight top-up read this one array, so they cannot drift apart.
 load_skip_paths() {
     local file="${ASIMOV_DATA}/skip-paths.tsv"
     require_data_file "$file"
@@ -74,6 +76,10 @@ load_skip_paths() {
         [[ -z "$path" || "$path" == '#'* ]] && continue
         ASIMOV_SKIP_PATHS+=("${ASIMOV_ROOT}/${path}")
     done < "$file"
+
+    for path in ${ASIMOV_CONFIG_EXTRA_SKIP_PATHS[@]+"${ASIMOV_CONFIG_EXTRA_SKIP_PATHS[@]}"}; do
+        ASIMOV_SKIP_PATHS+=("$path")
+    done
 }
 
 # Every sentinel record in effect for this run, one "dir sentinel" pair per line:

lib/asimov/doctor.sh

@@ -271,7 +271,7 @@ doctor_check_config() {
         if [[ "$line" =~ ^\[([a-z_]+)\]$ ]]; then
             section="${BASH_REMATCH[1]}"
             case "$section" in
-                fixed_dirs|scan|sentinels) ;;
+                fixed_dirs|scan|sentinels|skip_paths) ;;
                 *)
                     unknown=$((unknown + 1))
                     doctor_problem "unknown section [${section}] in ${ASIMOV_CONFIG_FILE}"
@@ -284,11 +284,11 @@ doctor_check_config() {
             key="${BASH_REMATCH[1]}"
             case "${section}:${key}" in
                 fixed_dirs:enabled|fixed_dirs:extra|scan:extra|\
-                sentinels:extra|sentinels:disabled) ;;
+                sentinels:extra|sentinels:disabled|skip_paths:extra) ;;
                 *)
                     # A key under an already-reported section is the same fault.
                     case "$section" in
-                        fixed_dirs|scan|sentinels)
+                        fixed_dirs|scan|sentinels|skip_paths)
                             unknown=$((unknown + 1))
                             doctor_problem "unknown key '${key}' under [${section}] in ${ASIMOV_CONFIG_FILE}"
                             ;;

tests/behavior.bats

@@ -120,6 +120,46 @@ load test_helper
   [[ "$(count_exclusions)" -eq 0 ]]
 }
 
+@test "skips directories given in [skip_paths] config" {
+  write_config "[skip_paths]
+extra = ~/Music"
+  create_project "Music/Code/First-Project" "composer.json" "vendor"
+  run_asimov
+  refute_excluded "${HOME}/Music/Code/First-Project/vendor"
+  [[ "$(count_exclusions)" -eq 0 ]]
+}
+
+@test "excludes the same project when [skip_paths] is absent" {
+  create_project "Music/Code/First-Project" "composer.json" "vendor"
+  run_asimov
+  assert_excluded "${HOME}/Music/Code/First-Project/vendor"
+}
+
+@test "[skip_paths] accepts several entries" {
+  write_config "[skip_paths]
+extra = ~/Music
+extra = ~/Pictures"
+  create_project "Music/First-Project" "composer.json" "vendor"
+  create_project "Pictures/Second-Project" "package.json" "node_modules"
+  create_project "Code/Third-Project" "package.json" "node_modules"
+  run_asimov
+  refute_excluded "${HOME}/Music/First-Project/vendor"
+  refute_excluded "${HOME}/Pictures/Second-Project/node_modules"
+  assert_excluded "${HOME}/Code/Third-Project/node_modules"
+}
+
+@test "[skip_paths] does not suppress fixed directories inside it" {
+  write_config "[fixed_dirs]
+enabled = true
+extra = ~/Music/build-cache
+
+[skip_paths]
+extra = ~/Music"
+  mkdir -p "${HOME}/Music/build-cache"
+  run_asimov
+  assert_excluded "${HOME}/Music/build-cache"
+}
+
 # =============================================================================
 # Nested project handling
 # =============================================================================

tests/doctor.bats

@@ -260,6 +260,26 @@ enabled = true"
   [[ "$output" == *".config/asimov/config"* ]]
 }
 
+@test "doctor accepts a [skip_paths] section" {
+  write_config "[skip_paths]
+extra = ~/Music"
+
+  run_asimov doctor
+
+  [[ "$status" -eq 0 ]]
+  [[ "$output" == *"looks valid"* ]]
+}
+
+@test "doctor flags an unknown key under [skip_paths]" {
+  write_config "[skip_paths]
+exrta = ~/Music"
+
+  run_asimov doctor
+
+  [[ "$status" -eq 1 ]]
+  [[ "$output" == *"exrta"* ]]
+}
+
 @test "doctor flags an unknown config key" {
   write_config "[fixed_dirs]
 enbaled = true"