Can't follow non-constant source

Problem

When you write `source "$CONFIG_DIR/env.sh"`, ShellCheck doesn't know what file you mean and skips it — losing the ability to flag bugs in the sourced file. SC1090 reminds you that part of your script is being analyzed in isolation.

Bad

source "$CONFIG_DIR/env.sh"
echo "$DB_HOST"   # ShellCheck doesn't see DB_HOST defined → SC2154

Good

# shellcheck source=config/env.sh
source "$CONFIG_DIR/env.sh"
echo "$DB_HOST"

# Or, if the file truly is dynamic:
# shellcheck source=/dev/null
source "$plugin"

Explanation

The `# shellcheck source=PATH` directive tells ShellCheck which file to load for analysis (the path is relative to the script). Use `source=/dev/null` only when the file genuinely cannot be known at lint time.

Related

SC2154

When It Matters

ShellCheck analyses files statically, so a source line whose path is built from a variable cannot be followed. Every function and variable defined in that file is then unknown, which suppresses real findings in the rest of your script and produces a cascade of spurious "unassigned variable" warnings. The warning is not about a bug in your script; it is ShellCheck telling you its analysis of the file is incomplete.

Second Example

Exceptions

source=/dev/null is the right answer when the sourced file genuinely is not available at check time — a runtime-generated environment file, or a system file outside the repository. Prefer a real path when one exists, because that is where the extra analysis comes from.

Faq