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.

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. 

# 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. 
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. 
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. 
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. 

# 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. 
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).
Master Bash with Deep Grasping Methodology!Learn More