Skip to content

Home

Jump to bottom
gaspode-wonder edited this page Dec 21, 2025 · 2 revisions

Welcome to the pi-log wiki!

pi-log — Shell Environment Troubleshooting Summary

(macOS → VS Code → pyenv → pre-commit)

Overview

This document summarizes the investigation and resolution of issues involving VS Code launching the wrong shell, pyenv not initializing, and pre-commit failing to locate Python 3.10 for the ansible-lint hook.

1. Initial Symptoms

  • VS Code terminals were launching bash instead of zsh.
  • pyenv initialization was not occurring inside VS Code.
  • python3.10 was not discoverable in VS Code, even though it worked in Terminal.app.
  • pre-commit failed to build the ansible-lint hook environment due to missing Python 3.10.

2. Root Causes Identified

2.1 VS Code Shell Mismatch

  • VS Code was ignoring the user-level setting: 
    "terminal.integrated.defaultProfile.osx": "zsh"
  • VS Code continued launching /bin/bash due to cached profile state.

2.2 pyenv Not Loading

  • Because VS Code was launching bash, .zshrc was never sourced.
  • pyenv shims were not added to $PATH.

2.3 pre-commit Interpreter Discovery Failure

  • pre-commit attempted to create a Python 3.10 environment for ansible-lint.
  • VS Code’s bash shell could not locate python3.10, causing hook installation failure.

3. Corrective Actions

3.1 Verified macOS Login Shell

Checked the system shell:

dscl . -read /Users/$USER UserShell

Output:

UserShell: /bin/zsh

3.2 Forced VS Code to Use zsh

  • Used Terminal: Select Default Profile to explicitly select zsh.
  • Cleared VS Code’s cached terminal state.
  • Fully restarted VS Code.

3.3 Ensured pyenv Initialization in .zshrc

Added:

export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

3.4 Verified pyenv in VS Code

Confirmed:

which python3.10

Output:

/Users/jebbaugh/.pyenv/shims/python3.10

4. pre-commit Resolution

4.1 Removed Conflicting ansible-lint Overrides

The previous configuration attempted to install:

  • ansible-lint==23.12.2 (manual pin)
  • ansible-lint 0.1.dev1 (from the hook repo)

This caused pip dependency resolution failure.

4.2 Updated .pre-commit-config.yaml

Replaced the hook with:

default_language_version:
  python: python3.10

repos:
  - repo: https://github.com/ansible/ansible-lint
    rev: v24.2.0
    hooks:
      - id: ansible-lint
        name: ansible-lint (pi-log)
        files: ^ansible/

4.3 Rebuilt Hook Environments

pre-commit clean
pre-commit install
pre-commit run --all-files

Result: all hooks passed successfully.

5. Final State

  • VS Code now launches zsh consistently.
  • pyenv initializes correctly inside VS Code.
  • python3.10 is available to pre-commit.
  • ansible-lint installs without version conflicts.
  • The development environment is stable and reproducible.

Appendix A — Lessons Learned

1. VS Code Shell Behavior Is Not Guaranteed

  • User-level settings do not always control the terminal profile.
  • VS Code may cache the previous shell and ignore updated settings.
  • Workspace settings can silently override user settings.

2. pyenv Initialization Depends Entirely on the Correct Shell

  • pyenv only initializes when the correct shell startup file is sourced.
  • If VS Code launches bash, .zshrc is never evaluated.
  • Interpreter discovery failures in pre-commit often trace back to pyenv not loading.

3. Python Version Pinning Must Be Consistent Across Tools

  • pre-commit hook environments use their own Python interpreter.
  • The project’s .venv Python version does not influence hook creation.
  • Python 3.10 must be discoverable globally for ansible-lint hooks.

4. ansible-lint Should Not Be Pinned via additional_dependencies

  • The ansible-lint hook repository already defines its own package version.
  • Adding a second version via additional_dependencies creates unavoidable conflicts.
  • The correct way to pin ansible-lint is through the rev: field only.

5. Environment Stability Requires Alignment Between:

  • macOS login shell
  • VS Code terminal profile
  • pyenv initialization
  • pre-commit interpreter selection
  • project virtual environment

Any mismatch in this chain produces cascading failures.

Appendix B — Troubleshooting Timeline

Phase 1 — Initial Failure

  • pre-commit failed to install ansible-lint due to missing Python 3.10.
  • VS Code terminal reported /bin/bash instead of /bin/zsh.
  • pyenv was not initializing inside VS Code.

Phase 2 — Shell Investigation

  • Verified macOS login shell was correctly set to zsh.
  • Identified VS Code was ignoring user settings.
  • Confirmed no workspace-level overrides existed.
  • Determined VS Code was using a cached terminal profile.

Phase 3 — Shell Correction

  • Forced VS Code to select zsh via profile selector.
  • Cleared VS Code terminal state.
  • Restarted VS Code and confirmed echo $SHELL returned /bin/zsh.

Phase 4 — pyenv Restoration

  • Added pyenv initialization to .zshrc.
  • Verified which python3.10 returned pyenv shim path.
  • Confirmed VS Code inherited the correct environment.

Phase 5 — pre-commit Resolution

  • Identified conflicting ansible-lint versions (0.1.dev1 vs 23.12.2).
  • Removed additional_dependencies from the hook config.
  • Updated .pre-commit-config.yaml to rely solely on rev:.
  • Rebuilt hook environments successfully.

Phase 6 — Final Validation

  • pre-commit ran cleanly.
  • ansible-lint installed without conflict.
  • Development environment stabilized.

Appendix C — Diagnostic Checklist

Shell Verification

  • Run echo $SHELL inside VS Code.
  • Confirm output is /bin/zsh.
  • If not, use Terminal: Select Default Profile to choose zsh.
  • Clear VS Code terminal state if profile changes do not apply.

macOS Login Shell

  • Run dscl . -read /Users/$USER UserShell.
  • Confirm output is /bin/zsh.
  • If not, run chsh -s /bin/zsh and log out/in.

pyenv Initialization

  • Ensure .zshrc contains: 
    export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
  • Run which python3.10 inside VS Code.
  • Confirm the path points to pyenv shims.

pre-commit Interpreter Discovery

  • Confirm .pre-commit-config.yaml sets: 
    default_language_version:
  python: python3.10
  • Ensure no Python version pins conflict with pyenv.

ansible-lint Hook Configuration

  • Remove all additional_dependencies from the ansible-lint hook.
  • Pin the version only via rev:: 
    rev: v24.2.0
  • Rebuild environments: 
    pre-commit clean
pre-commit install

Final Validation

  • Run pre-commit run --all-files.
  • Confirm all hooks pass.
  • Confirm VS Code and Terminal.app behave identically. # Appendix D — Shell/Environment Flowchart (Mermaid + ASCII)

Mermaid Version

flowchart TD

A[VS Code launches terminal] --> B{Which shell starts?}

B -->|/bin/zsh| C[pyenv initializes]
B -->|/bin/bash| D[pyenv does NOT initialize]

C --> E{python3.10 available?}
D --> E

E -->|Yes| F[pre-commit can build ansible-lint env]
E -->|No| G[pre-commit fails to find interpreter]

G --> H{ansible-lint pinned twice?}
H -->|Yes| I[Dependency conflict: 0.1.dev1 vs pinned version]
H -->|No| J[Interpreter discovery failure]

I --> K[Fix: remove additional_dependencies]
J --> L[Fix: ensure VS Code uses zsh + pyenv loads]

K --> M[Rebuild pre-commit envs]
L --> M

M --> N[System stable]
Loading

ASCII Version

+---------------------------+
| VS Code launches terminal |
+-------------+-------------+
              |
              v
      +-------+--------+
      | Which shell?   |
      +-------+--------+
              |
   +----------+-----------+
   |                      |
   v                      v
/bin/zsh             /bin/bash
(pyenv loads)       (pyenv does NOT load)
   |                      |
   +----------+-----------+
              |
              v
   +----------+-----------+
   | python3.10 available?|
   +----------+-----------+
              |
   +----------+-----------+
   |                      |
   v                      v
Yes                    No
(pre-commit OK)        (pre-commit fails)
                           |
                           v
               +-----------+-----------+
               | ansible-lint pinned? |
               +-----------+-----------+
                           |
               +-----------+-----------+
               |                       |
               v                       v
Yes (conflict)                 No (missing pyenv)
Remove additional_deps         Fix VS Code shell
                           |
                           v
                 Rebuild pre-commit envs
                           |
                           v
                     System stable

Appendix E — Root-Cause Analysis (RCA)

Summary

The failure originated from VS Code launching the wrong shell (bash), preventing pyenv initialization and causing pre-commit to fail when building the ansible-lint hook environment. A secondary issue involved conflicting ansible-lint versions due to manual pinning.

Problem Statement

pre-commit could not install ansible-lint because Python 3.10 was not discoverable inside VS Code, and pip encountered conflicting ansible-lint versions.

Impact

  • pre-commit hooks could not run
  • ansible-lint environment failed to build
  • inconsistent behavior between VS Code and Terminal.app
  • development workflow blocked

Root Causes

1. VS Code launching /bin/bash instead of /bin/zsh

  • Cached terminal profile ignored user settings.
  • .zshrc was never sourced.

2. pyenv not initializing inside VS Code

  • pyenv shims were not added to $PATH.
  • python3.10 was not discoverable.

3. Conflicting ansible-lint versions

  • Hook repo defined ansible-lint==0.1.dev1.
  • .pre-commit-config.yaml pinned ansible-lint==23.12.2.
  • pip refused to install both.

Contributing Factors

  • VS Code terminal profile caching
  • Lack of pyenv initialization in bash
  • Misuse of additional_dependencies in pre-commit

Corrective Actions

  • Forced VS Code to use zsh via profile selector.
  • Cleared VS Code terminal state.
  • Ensured pyenv initialization in .zshrc.
  • Removed ansible-lint version pinning from additional_dependencies.
  • Rebuilt pre-commit environments.

Preventative Measures

  • Avoid pinning ansible-lint via additional_dependencies.
  • Verify VS Code shell after updates.
  • Keep pyenv initialization in .zshrc only.
  • Use rev: to pin hook versions.

Appendix F — Future Maintainers Onboarding Section

Purpose

This section provides guidance for future maintainers working on pi-log to ensure consistent shell behavior, interpreter discovery, and pre-commit reliability.

Required Tools

  • macOS (development)
  • pyenv
  • Python 3.9 (project runtime)
  • Python 3.10 (pre-commit hooks)
  • VS Code

Environment Expectations

  • VS Code must launch zsh, not bash.
  • pyenv must initialize automatically.
  • python3.10 must be discoverable globally.
  • .venv uses Python 3.9 for runtime.
  • pre-commit uses Python 3.10 for ansible-lint.

Setup Checklist

  1. Install pyenv and Python versions: 
    pyenv install 3.9.6
pyenv install 3.10.x
  2. Ensure .zshrc contains: 
    export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
  3. Verify VS Code shell:
    • Command Palette → Terminal: Select Default Profile → zsh
  4. Create project virtual environment: 
    python3.9 -m venv .venv
  5. Install dependencies: 
    pip install -r requirements.txt
  6. Install pre-commit: 
    pre-commit install

Expected Behavior

  • which python3.10 returns a pyenv shim.
  • pre-commit run --all-files passes.
  • VS Code and Terminal.app behave identically.

Appendix G — Troubleshooting Playbook (Shell & Environment)

1. VS Code Launches Bash Instead of Zsh

Symptoms:

  • echo $SHELL → /bin/bash
  • pyenv not loading

Actions:

  • Command Palette → Terminal: Select Default Profile → zsh
  • Quit VS Code completely
  • Remove terminal state: 
    rm -rf ~/Library/Application\ Support/Code/User/globalStorage/state.vscdb*

2. pyenv Not Initializing

Symptoms:

  • which python3.10 returns nothing
  • pre-commit cannot find Python 3.10

Actions:
Add to .zshrc:

export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

Reload:

source ~/.zshrc

3. pre-commit Cannot Install ansible-lint

Symptoms:

  • pip conflict errors
  • mentions ansible-lint 0.1.dev1 vs ansible-lint==X.Y.Z

Actions:

  • Remove all additional_dependencies from ansible-lint hook
  • Pin only via rev:
  • Rebuild: 
    pre-commit clean
pre-commit install

4. Python Version Mismatch

Symptoms:

  • .venv uses wrong Python version
  • ansible-lint uses wrong interpreter

Actions:

  • Recreate venv with Python 3.9: 
    python3.9 -m venv .venv
  • Ensure pre-commit uses Python 3.10: 
    default_language_version:
  python: python3.10

5. VS Code and Terminal.app Behave Differently

Symptoms:

  • Commands work in Terminal.app but not VS Code

Actions:

  • Confirm VS Code is launching zsh
  • Confirm .zshrc loads pyenv
  • Compare: 
    env | sort

6. Final Validation Checklist

  • echo $SHELL → /bin/zsh
  • which python3.10 → pyenv shim
  • .venv uses Python 3.9
  • pre-commit installs cleanly
  • ansible-lint runs without conflict
  • VS Code and Terminal.app match

Clone this wiki locally