Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt

Use this file to discover all available pages before exploring further.

The source command (and its POSIX-compliant equivalent, the dot operator .) is a shell built-in that reads and evaluates commands from a specified file directly within the current shell execution context. Unlike standard script execution, sourcing a file does not spawn a child process (subshell).

​
Syntax

source filename [arguments]
. filename [arguments]

​
Execution Context and State Mutation

Because the file is evaluated in the current shell environment, any state changes invoked by the file persist in the calling shell after execution completes.
  • Environment Variables: Variable assignments and export declarations become immediately available in the parent shell.
  • Functions and Aliases: Any functions or aliases defined in the sourced file are registered in the current shell’s memory space.
  • Working Directory: Commands that modify the environment, such as cd, will change the working directory of the active shell session.
  • Permissions: The target file requires read (r) permissions, but strictly does not require execute (x) permissions, as the file is read as a stream of commands rather than invoked as an executable binary or script.

​
Control Flow

The return built-in can be used inside a sourced file to halt its execution early. When return is encountered, Bash stops reading the sourced file and returns control to the calling shell, passing back the specified exit status. This behaves exactly as it does when terminating a shell function.

​
Path Resolution

When a file is sourced, Bash uses specific rules to locate the file:
  1. If the filename contains a directory path (e.g., ./script.sh or /etc/script.sh), Bash reads that exact file.
  2. If the filename does not contain a slash (/), Bash checks the sourcepath shell option (shopt -s sourcepath), which is enabled by default. If sourcepath is enabled, Bash searches the directories defined in the $PATH environment variable.
  3. If the file is not found in $PATH, default Bash falls back to searching the current working directory. However, if Bash is operating in POSIX mode (set -o posix or invoked as sh), this fallback is disabled, and the current directory is not searched unless it is explicitly included in $PATH.

​
Positional Parameters

The source command handles positional parameters ($1, $2, $@, etc.) dynamically based on how it is invoked:
  • With Arguments: If arguments are appended to the source command, they temporarily replace the calling shell’s positional parameters for the duration of the sourced file’s execution. Once the file finishes evaluating, the calling shell’s original positional parameters are restored.
  • Without Arguments: If no arguments are provided, the sourced file inherits the current positional parameters of the calling shell.

​
Exit Status and Error Handling

The return value ($?) of the source command is the exit status of the last command executed within the sourced file. If the file is empty or no commands are executed, the exit status is 0. If execution is halted via the return built-in, the exit status is the argument passed to return. If the specified file cannot be found or read, source returns a non-zero exit status (typically 1). In default Bash, this will cause a non-interactive shell to exit only if the errexit (set -e) option is enabled. However, in POSIX mode, failing to find the sourced file is a fatal error that immediately aborts a non-interactive shell, regardless of whether the errexit option is enabled.
Master Bash with Deep Grasping Methodology!Learn More