> ## 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.
# Bash Nameref Variable
A nameref (name reference) is a variable attribute in Bash (introduced in version 4.3) that establishes a direct, transparent pointer to another variable. When a variable is assigned the nameref attribute, all subsequent operations performed on it—including assignment, parameter expansion, attribute modification, and unsetting—are dynamically redirected to the target variable it references.
## Declaration Syntax
The nameref attribute is applied using the `-n` flag with either the `declare` or `local` builtins. The value assigned during declaration becomes the string name of the target variable.
```bash theme={"dark"}
# Global scope declaration
declare -n ref_name="target_variable_name"
# Function-local declaration
local -n local_ref="target_variable_name"
```
## Operational Mechanics
Once established, the nameref acts as an alias. The Bash parser intercepts interactions with the nameref and applies them to the target.
```bash theme={"dark"}
actual_var="initial_state"
declare -n ptr="actual_var"
# 1. Expansion (Dereferencing)
echo "$ptr" # Evaluates to "initial_state"
# 2. Assignment
ptr="mutated_state" # Writes directly to actual_var
echo "$actual_var" # Evaluates to "mutated_state"
# 3. Attribute Modification
declare -r ptr # Makes actual_var read-only, not the nameref itself
```
## Introspection
To retrieve the name of the target variable rather than its value, Bash overloads the indirect expansion operator (`${!var}`). When applied to a nameref, it yields the target's identifier.
```bash theme={"dark"}
target="data"
declare -n ref="target"
echo "${!ref}" # Outputs: target
```
## Unsetting Behavior
Because operations pass through to the target, standard unsetting destroys the referenced variable, not the nameref itself. To destroy the nameref, the `-n` flag must be passed to `unset`.
```bash theme={"dark"}
declare -n ptr="target_var"
# Destroys 'target_var' entirely. 'ptr' remains an active nameref pointing to an unset variable.
unset ptr
# Destroys the nameref variable 'ptr' itself.
unset -n ptr
```
*Note: Bash does not allow removing the nameref attribute to leave behind a standard variable (e.g., `declare +n ptr` is invalid). The nameref must be completely destroyed using `unset -n`.*
## Resolution and Scope Rules
Bash resolves namerefs dynamically at runtime using the call stack (dynamic scoping).
1. When a nameref is evaluated, Bash searches for the target variable name in the current scope.
2. If not found, it traverses up the call stack to the parent scopes.
3. If the target variable does not exist anywhere in the call stack, assigning a value to the nameref initializes the target variable in the **global** scope, acting exactly like a standard assignment to an undeclared variable.
## Restrictions and Pitfalls
### Circular References
Bash enforces strict checks against circular references to prevent infinite recursion during variable resolution. A nameref cannot point to itself, nor can it participate in a closed loop of references.
```bash theme={"dark"}
# Triggers: bash: warning: ref: circular name reference
declare -n ref="ref"
declare -n a="b"
declare -n b="a"
# Triggers circular reference warning upon evaluation
```
### Local Variable Name Collisions
Because Bash uses dynamic scoping, a critical limitation occurs if a local nameref shares the exact same name as the target variable it is attempting to reference. When the nameref is evaluated, Bash resolves it to the local variable itself rather than the target in the parent scope, immediately triggering a circular reference error.
```bash theme={"dark"}
mutate_var() {
# If $1 is "ref", this evaluates to: local -n ref="ref"
local -n ref=$1
ref="new_state"
}
target_var="data"
mutate_var target_var # Executes successfully
ref="data"
mutate_var ref # Triggers: bash: warning: ref: circular name reference
```
To avoid this collision, local nameref variables must be named using conventions that guarantee they will not overlap with any target variable names passed from calling scopes (e.g., prefixing the nameref identifier with `__` or specific namespace strings).
Tired of Poor Bash Skills? Fix That With Deep Grasping!
Learn More
