Efficient Private Project Lookup

Traditional version managers frequently enumerate or scan entire directories of project configurations on every command execution. eselect-version-manager eliminates directory scanning through a deterministic, path-hashed lookup.

O(depth) Path-Based Lookup

When a user executes a shim or CLI command in directory $PWD:

  1. Path Canonicalization: The current working directory is resolved to its absolute canonical path, eliminating any symlink aliases: python canonical_path = os.path.realpath(os.path.abspath(path))

  2. Deterministic SHA-256 Digest: A stable SHA-256 digest of the canonical UTF-8 path string is computed: python project_id = hashlib.sha256(canonical_path.encode('utf-8')).hexdigest()

  3. Direct File Check: The dispatcher directly checks for the existence of: ${XDG_CONFIG_HOME:-$HOME/.config}/eselect/version-manager/projects/<project-id>.conf and ${canonical_path}/.eselect.conf

  4. Ancestor Traversal: If neither exists in the current directory, the dispatcher repeats this check for the parent directory, ascending to the filesystem root /.

Complexity Comparison

Method Number of Disk Operations Scales With
Full Directory Scan $O(N)$ directory entries read & parsed Number of registered projects ($N$)
eselect-version-manager $O(D)$ direct stat/open calls Directory depth ($D \approx 4-8$)

Benchmarks demonstrate an average lookup time of 0.05 to 0.12 milliseconds, completely independent of whether 5 or 5,000 projects are registered on the system.

Integrity Validation and Stale Record Diagnostics

Inside each private project configuration file, the canonical path is recorded:

# Private user project configuration for: /home/user/work/myproject
PROJECT_ROOT="/home/user/work/myproject"
VM_GO="1.26"

When reading a private project configuration: - The recorded PROJECT_ROOT is validated against the queried path. - If the directory has moved or the record does not match, a diagnostic StaleProjectRecordError (exit code 17) is emitted, offering the exact rebind command.

Project Rebind Operation

When a project directory is relocated, the private configuration can be migrated without manually editing files:

eselect version-manager rebind /home/user/old-path /home/user/new-path

Or from inside the new project directory:

eselect version-manager rebind /home/user/old-path