Safe terminal and Git field guide

This is an inspection-first field guide for the Phase 1 practice repository. It contains no cleanup or history-rewriting recipes. When a command would discard work, stop, preserve context, and ask for review.

Prove context first

Runtime: Local Windows PowerShell 7 · read-only · 3 min.

Get-Location
Get-ChildItem -LiteralPath .
Get-Command python
python -c "import sys; print(sys.executable)"

Runtime: Local bash or zsh · read-only · 3 min.

pwd
ls -la
command -v python
python -c 'import sys; print(sys.executable)'

If the path or interpreter is unexpected, do not continue. PowerShell and POSIX syntax are different: use -LiteralPath and quoted strings in PowerShell; use quoted paths and -- for supported POSIX commands when a filename could resemble an option.

Create and enter only a named practice folder

Runtime: Local Windows PowerShell 7 · creates a directory only when absent · 3 min.

$practice = Join-Path (Get-Location) 'media qc practice'
if (-not (Test-Path -LiteralPath $practice)) {
    New-Item -ItemType Directory -Path $practice
}
Set-Location -LiteralPath $practice

Runtime: Local bash or zsh · creates a named directory if needed · 3 min.

mkdir -p -- "media qc practice"
cd -- "media qc practice"

Environment proof

Runtime: Local PowerShell, bash, or zsh with uv · observes the locked environment · 3 min.

uv run python --version
uv run python -c "import sys; print(sys.executable)"
uv lock --check

Commit pyproject.toml and uv.lock; keep .venv out of Git. With standard venv, record the Python version and direct dependency declaration, then recreate rather than copy the environment. See the official Python venv reference.

Git observation loop

Runtime: Local PowerShell, bash, or zsh inside the practice repository · read-only · 5 min.

git status --short --branch
git branch --show-current
git diff --
git diff --cached
git log -3 --oneline

• status classifies tracked, modified, staged, and untracked paths.
• diff shows unstaged content changes.
• diff --cached shows what the next commit would contain.
• branch --show-current proves the work line.
• log shows saved checkpoints.

Lookups: official git status and official git diff.

Reviewable change loop

Create a branch before the experiment, stage explicit paths, inspect the staged diff, then commit one coherent change.

Runtime: Local PowerShell, bash, or zsh inside the dedicated practice repository · creates a branch and commit · 8 min.

git switch -c phase1/short-description
git status --short
git diff -- path/to/source.py path/to/test_source.py
git add -- path/to/source.py path/to/test_source.py
git diff --cached
git commit -m "fix: describe verified behavior"
git status --short

Lookups: official git branch and official git commit. These selected command references replace a full external Git course.

Recovery-safe stop conditions

Stop before acting when:

• the resolved directory is not the practice repository;
• git status shows unrelated or unfamiliar changes;
• a path expansion targets more files than intended;
• a proposed command discards working-tree content or rewrites history;
• generated output would replace existing evidence;
• a diff contains a token, private media path, or machine-specific configuration.

Preserve evidence by making a focused commit on a branch after review. If work is already mixed, inspect and coordinate rather than improvising cleanup. Git is a recovery aid only for content it has recorded.

Compact handoff

Report the current branch, status, exact verification command, test count, output artifact, and remaining limitation. Never say “fixed” from a diff alone.