computing-setup/02-git-basics/README.md

# 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