A bash script does `source "$LIB_DIR/common.sh"` and ShellCheck reports SC1090, "can't follow non-constant source"; a second script that sources `lib/common.sh` by a literal path gets SC1091 instead, followed by a pile of "referenced but not assigned" warnings. What is the difference between those two codes, and how do you get ShellCheck to actually read the library?

## Why ShellCheck stops at a source line ShellCheck analyses a script as text. When it reaches `source lib/common.sh` (or the POSIX `.` form) it would like to read that file too, because everything the library defines — functions, variables, `set` options — changes what the rest of the script means. Two things can stop it, and each has its own code. **SC1090 — non-constant source.** The path contains an expansion: ```bash source "$LIB_DIR/common.sh" source "$(dirname "$0")/lib/common.sh" ``` The value of `LIB_DIR` or `$0` exists only when the script runs. No amount of configuration lets a static tool resolve it, so ShellCheck reports that it cannot follow and moves on. **SC1091 — not following a file it could name.** The path is literal, so ShellCheck knows *which* file, but it still did not read it: external sources were not enabled, the file is not present relative to the directory ShellCheck was invoked from, or it is genuinely missing. ## The knock-on damage The codes themselves are informational. The real cost is what follows. Because ShellCheck never read the library, it believes: - variables the library assigns are never assigned — `SC2154`, "var is referenced but not assigned", on every use; - variables the library *reads* but your script assigns are unused — `SC2034`, "appears unused"; - functions the library defines are unknown commands. A script that is entirely correct can therefore produce dozens of findings, and the usual reaction — suppressing `SC2154` file-wide — throws away a genuinely useful check. Fixing the source resolution makes the noise disappear at its cause. ## Making it follow the file Two pieces are needed: telling ShellCheck *which* file, and allowing it to read files you did not pass on the command line. **The directive.** On the line above the `source` command: ```bash # shellcheck source=lib/common.sh source "$LIB_DIR/common.sh" ``` The directive names the file for analysis purposes; the runtime path is untouched. Use the path as it exists in the repository. There is also `# shellcheck source=/dev/null` for the case where you deliberately want ShellCheck to treat the source as empty — for example a host-specific config that does not exist in the repo at all. That is an honest suppression: it says "nothing analysable here", and it stops SC1090 without pretending a file exists. **The flag.** `-x`, long form `--external-sources`, permits ShellCheck to open files other than the ones given as arguments. Without it, a directive pointing at a real file still will not be followed. ```bash shellcheck -x scripts/deploy.sh ``` **Resolution root.** Relative paths resolve from ShellCheck's working directory by default, which breaks the moment CI invokes it from the repo root while the script lives three directories down. The `source-path` setting fixes that; the special value `SCRIPTDIR` means "resolve relative to the directory of the script being checked", which is what most repositories actually want: ``` # .shellcheckrc external-sources=true source-path=SCRIPTDIR ``` `source-path` can also be given as a directive (`# shellcheck source-path=SCRIPTDIR`) or repeated for several search directories. With this in `.shellcheckrc`, most `source` lines with literal paths resolve with no per-file annotation at all. One more flag worth knowing: `-a` (`--check-sourced`) additionally reports findings *inside* the sourced files, rather than only using them for context. That is useful for a one-shot audit and usually redundant in CI, where the library files are checked in their own right anyway. ## The library file itself A sourced library normally has no shebang, because it is not executed. That triggers `SC2148`. Give it a first line of `# shellcheck shell=bash` so ShellCheck knows the dialect. Some teams add a shebang anyway as documentation; either is fine as long as it names the shell that will actually run the code. ## Judgment The senior-level point is that these codes are a *configuration* problem masquerading as a code problem. The wrong response is a repo-wide `disable=SC1090,SC2154`, which silences a check that catches real typos in variable names. The right response is one `.shellcheckrc`, `-x` in the lint command, and a directive at the handful of call sites whose path is genuinely dynamic — after which the remaining `SC2154` findings are all real.