Loading...

VONDS ©

Lab 33: Environment Variables and Shell Configuration

Back to Lab Index

Diagnose why an environment variable is missing in new shells, then make it persist across interactive sessions. Validate the change with repeatable CLI checks and evidence in shell startup files.

core troubleshooting shell

Scenario

A developer reports that the PROJECT_ROOT environment variable disappears in new terminals. You need to reproduce the failure, identify which startup file is (or is not) being read, and implement a persistent export that loads in fresh interactive shells.

Operator context

“It works in my current terminal” is not a fix. Treat this as complete only when a brand new shell session shows the variable and the export line is present in the correct file.

Objective

  • Confirm whether PROJECT_ROOT is set in the current environment.
  • Prove the variable is not being loaded from ~/.bashrc.
  • Add a persistent export in the appropriate startup file.
  • Reload configuration and verify the environment.
  • Confirm the export line exists as evidence.

Concepts

  • Environment variables are process state; they do not persist unless a startup mechanism re-applies them.
  • Interactive shells commonly load ~/.bashrc; login shells may load ~/.profile or ~/.bash_profile depending on the system.
  • Evidence chain: inspect the current environment, audit the startup file, apply a change, then verify in a fresh shell.
  • source applies changes immediately to the current session, but does not prove persistence by itself.
  • Use targeted filtering (grep) to confirm what the shell will load.

Walkthrough

Step 1 : Check whether PROJECT_ROOT is set.
Commands 
printenv PROJECT_ROOT
# OR
env | grep PROJECT_ROOT

This establishes the baseline for the current shell. If the variable only exists in this session and disappears in a new terminal, the issue is persistence, not syntax. 

/home/dev/project
# OR
PROJECT_ROOT=/home/dev/project
Step 2 : Audit ~/.bashrc for the export.
Command 
grep PROJECT_ROOT ~/.bashrc

~/.bashrc is a common location for user-level exports intended to load in interactive shells. If there is no match, the variable will not persist by default. 

# No output means the variable is not defined in ~/.bashrc
Step 3 : Add a persistent export line.
Command 
echo 'export PROJECT_ROOT=/home/dev/project' >> ~/.bashrc

Appending an export line ensures that future interactive shells that read ~/.bashrc set the variable automatically.

Step 4 : Reload the startup file in the current session.
Command 
source ~/.bashrc

This applies the export immediately to the current shell so you can verify the value without restarting the terminal.

Step 5 : Verify the variable is present after the change.
Commands 
printenv PROJECT_ROOT
# OR
env | grep PROJECT_ROOT
/home/dev/project
# OR
PROJECT_ROOT=/home/dev/project

This confirms the export is live in the current environment. The persistence check is opening a new terminal and repeating the same command.

Step 6 : Confirm the export line exists as evidence.
Command 
grep PROJECT_ROOT ~/.bashrc
export PROJECT_ROOT=/home/dev/project

This is the durable proof that the fix is not accidental and will survive future sessions.

Common breakpoints

Variable is set now but still missing in new terminals

You proved the current environment, but you have not proved persistence. Confirm the new shell is reading ~/.bashrc and that the export line is present and not overridden later in the file.

Export exists but value is wrong

Hard-coded paths drift. Validate that the target path exists and matches the project location. If the project location is per-user or per-host, move the value to a more appropriate profile mechanism.

Multiple definitions conflict

If the variable is exported in multiple files, the last one read wins. Search your shell configs for additional exports and remove or consolidate to a single source of truth.

Non-Bash shell sessions

If the user runs a different shell, ~/.bashrc will not apply. Confirm the actual shell and place the export in the correct configuration file for that shell.

Cleanup checklist

Remove the export line you added so the environment returns to its pre-lab state.

Commands 
grep -n 'export PROJECT_ROOT=' ~/.bashrc
# Remove the matching line using your editor, then reload:
source ~/.bashrc
Success signal

A fresh terminal no longer shows PROJECT_ROOT, and grep finds no export line in ~/.bashrc.

Reference

  • printenv <var> : Prints the value of an environment variable if it is set.
  • env : Lists environment variables for the current process.
  • env | grep <pattern> : Filters environment output for matching lines.
    • | : Pipes output from the left command into the right command.
    • grep <pattern> : Prints lines matching the pattern.
  • grep <pattern> <file> : Searches for matching lines in a file.
    • ~/.bashrc : Common startup file for interactive Bash shells.
  • echo 'export VAR=value' >> ~/.bashrc : Appends an export line to the Bash startup file.
    • >> : Appends output to the end of a file.
  • source <file> : Loads a file into the current shell session.
    • source ~/.bashrc : Applies changes without starting a new terminal.