Initial commit: computing-setup

A two-module standalone guide for setting up a new machine for
scientific computing work:

- 01-know-your-machine: hardware and OS inspection. Reads the
  physical machine first via macOS/Linux terminals or Windows
  PowerShell; a separate section walks through the WSL VM and
  how its allocations differ from the host hardware.
- 02-git-basics: pull-focused git workflow. Install, configure
  identity, clone a public repo, pull updates. Authentication
  and pushing are deferred to a future collaboration module.

Includes top-level WSL.md (copied from cli-walkthrough) for
Windows users who need the Linux environment.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

02-git-basics/README.md

@@ -0,0 +1,235 @@
+# Git Basics
+
+## Key idea
+
+Install git, configure your identity, and use it to download and stay current with materials published in a public repository.
+
+## Key goals
+
+- Install git on macOS, Linux, or WSL
+- Set your git identity (`user.name`, `user.email`)
+- Clone a public repository
+- Check repository state with `git status`
+- Pull updates with `git pull`
+- Know which commands to avoid until you understand them
+
+This module is **pull-focused**. Authentication, pushing your own commits, branching, and merging belong in a later module on git collaboration. For now, the goal is to *receive* updates reliably.
+
+> **Windows users:** install WSL before starting this module — see [../WSL.md](../WSL.md). All commands below assume a Unix-style terminal (macOS, Linux, or WSL).
+
+---
+
+## What is git?
+
+Git is a **version control** system. It tracks changes to files over time, lets you go back to earlier states, and lets many people work on the same files without overwriting each other.
+
+A **repository** (often "repo") is a folder that git is tracking. Public repositories on hosting services like [Gitea](https://about.gitea.com/), GitHub, or GitLab can be downloaded ("cloned") by anyone — no account needed.
+
+For now we will use git only to *download* materials and *keep them up to date*. You will not need to push anything back, and you do not need an account on any hosting service.
+
+
+## 1. Install git
+
+### macOS
+
+The easiest path is [Homebrew](https://brew.sh/):
+
+```bash
+brew install git
+```
+
+If you don't have Homebrew, install the Xcode Command Line Tools (which include git):
+
+```bash
+xcode-select --install
+```
+
+### Linux / WSL (Ubuntu/Debian)
+
+```bash
+sudo apt update
+sudo apt install -y git
+```
+
+For other Linux distributions, use the appropriate package manager (`dnf install git`, `pacman -S git`, etc.).
+
+### Verify
+
+```bash
+git --version
+```
+
+You should see something like `git version 2.40.1`. If the command is not found, the install did not finish — try again.
+
+> **Tip (WSL users):** Run all git commands from inside your Linux home directory (e.g., `~/repos`), not from `/mnt/c/...`. Mixing Windows-side and WSL-side git on the same folder leads to permission and line-ending headaches.
+
+
+## 2. Configure your identity
+
+Git stamps every commit with a name and email. Set yours once — these are labels on your local commits and do not need to match any account on a hosting service.
+
+```bash
+git config --global user.name "Your Name"
+git config --global user.email "you@example.com"
+```
+
+Use your real name and a real email so future-you (and any collaborators) can identify your work.
+
+Verify:
+
+```bash
+git config --global --list
+```
+
+You should see `user.name` and `user.email` in the output.
+
+
+## 3. Clone a public repository
+
+To download a repository, copy its clone URL from the hosting service (usually a button labeled "Clone" or shown prominently on the project page) and run:
+
+```bash
+git clone <url>
+```
+
+For example:
+
+```bash
+git clone https://lem.che.udel.edu/git/furst/cli-walkthrough.git
+```
+
+This creates a folder named `cli-walkthrough` in your current directory. Move into it:
+
+```bash
+cd cli-walkthrough
+```
+
+> **Tip:** Be intentional about *where* you clone. Many people keep all their repos under one directory, e.g., `~/repos` or `~/code`. Avoid cloning into folders synced by Dropbox, iCloud, or OneDrive — sync conflicts and git history do not mix well.
+
+
+## 4. Check the state of a repository
+
+Inside any cloned repo, you can always ask git what is going on:
+
+```bash
+git status
+```
+
+If you have not edited anything, you will see "nothing to commit, working tree clean." If you have edited files, git lists them.
+
+`git status` is non-destructive. Run it whenever you are unsure what state things are in. It is the single most useful git command.
+
+
+## 5. Pull updates
+
+When the maintainer of the repository publishes changes, get them with:
+
+```bash
+git pull
+```
+
+Run this from inside the repo (the folder you `cd`'d into after cloning).
+
+**`git pull` does not silently overwrite your work.**
+
+- If you have made no local changes → files update normally.
+- If you have local changes that don't conflict with incoming changes → git merges them automatically.
+- If there is a conflict → git **stops** and tells you exactly which files need attention. Your work is preserved.
+
+Get in the habit of running `git pull` before you start working in a shared repo, so you start from the latest version.
+
+
+## 6. Saving your work locally
+
+Even when you are not pushing anywhere, committing locally is a good habit. A commit is a labeled snapshot you can return to later.
+
+```bash
+git add .
+git commit -m "short description of what you changed"
+```
+
+`git add .` stages every changed file in the current folder; `git commit` saves the snapshot with your message.
+
+This is also useful right before pulling updates — see section 7.
+
+
+## 7. If `git pull` refuses to run
+
+Sometimes git declines to pull because you have uncommitted changes that overlap with incoming updates. Two safe ways out:
+
+### Option A — Commit your work first
+
+```bash
+git add .
+git commit -m "save before pull"
+git pull
+```
+
+### Option B — Temporarily set work aside
+
+```bash
+git stash
+git pull
+git stash pop
+```
+
+`git stash` puts your uncommitted changes on a shelf; `git stash pop` restores them after the pull. Useful when you want to grab updates without committing half-finished work.
+
+
+## 8. Commands you should NOT use (yet)
+
+These commands can permanently delete uncommitted work:
+
+```bash
+git reset --hard
+git clean -fd
+git checkout -- .
+```
+
+Do not run them unless you understand exactly what they do and have intentionally chosen the consequences. When in doubt, ask first.
+
+
+## 9. If something looks wrong
+
+First, do not panic. Git is conservative — it does not overwrite committed work without a clear instruction. Most "something is wrong" situations are recoverable.
+
+Run:
+
+```bash
+git status
+```
+
+and read what it says. Git is unusually good at explaining the current state and suggesting next steps in its output. If you are still stuck, ask for help **before** running any of the destructive commands from section 8.
+
+
+## 10. When you eventually need authentication
+
+Anonymous cloning and pulling work for **public** repositories. You will need authentication when you want to:
+
+- Push your own commits back to a remote repo
+- Clone or pull from a **private** repository
+- Use collaboration features (branches, pull requests, etc.)
+
+Those topics — personal access tokens, SSH keys, branching, merging, pushing — are the subject of a follow-on module on git collaboration. For now, pull is enough.
+
+
+## Exercises
+
+> **Exercise 1:** Install git on your machine and run `git --version`. Record the version in your machine log.
+
+> **Exercise 2:** Set your `user.name` and `user.email` with `git config --global`. Verify with `git config --global --list`.
+
+> **Exercise 3:** Clone a public repository of your choosing (the cli-walkthrough URL above works as a default). Where did you clone it to?
+
+> **Exercise 4:** Run `git status` inside the cloned repo. What does it report?
+
+> **Exercise 5:** Run `git pull` inside the same repo. What does it report? (If nothing has changed upstream, that is fine — record what you see.)
+
+
+## Key takeaway
+
+- Git is a tool for tracking changes and synchronizing work
+- Public repositories can be cloned and pulled without an account
+- `git pull` is safe — it will not silently destroy your work
+- `git status` is your friend; run it whenever you are unsure
+- Authentication, pushing, and branching come later