Use the terminal with confidence, track your work with Git, and collaborate on GitHub with pull requests.

Git & the Command Line

## Why it matters

Without version control, projects end up with folders like `report-final.docx`, `report-final-v2.docx` and `report-final-REALLY-final.docx`, and nobody knows which one is current or what changed between them. With several people, it gets worse: two people edit the same file and one person's work is lost.

**Version control** records every saved change to a project, who made it and why, and lets you compare, undo and combine changes safely. **Git** is by far the most widely used version control system. Software teams, data science teams, infrastructure teams and many researchers and teachers use it every day, and nearly every technical job posting assumes you know it.

## The core ideas

### Repository

A **repository** (repo) is a project folder that Git tracks. Git keeps its records in a hidden `.git` folder inside it. Delete `.git` and the folder becomes an ordinary folder again, with no history.

### Commit

A **commit** is a saved snapshot of the whole project at one moment, plus:

- a **message** describing the change ("Add unit conversion for pressure"),
- the **author** and **date**,
- a link to the **parent** commit before it,
- a unique ID, a **hash** such as `3f9c2e1`, computed from the contents.

Commits are cheap, so you make many small ones. Each should be one logical change.

### History

Linked commits form the **history**. `git log --oneline` shows it, newest first:

```text
3f9c2e1 Add unit conversion for pressure
a17b4d0 Fix rounding in temperature report
9e02c55 Create README with setup steps
```

You can go back to any commit, see who changed a line and why (`git blame`), and find when a bug appeared.

### Diff

A **diff** shows exactly what changed between two versions, line by line:

```diff
-  rate = 0.08
+  rate = 0.0825
```

Lines starting with `-` were removed and lines with `+` were added. Reviewing diffs is how teams check each other's work before it is accepted.

### The three areas

Git separates your work into three places:

1. **Working directory:** the files as you are editing them now.
2. **Staging area** (index): the changes you have chosen to include in the next commit, added with `git add`.
3. **Repository:** the committed history, written with `git commit`.

Staging lets you commit some changes and keep others for later, so each commit stays focused.

### Branches

A **branch** is a separate line of development: a movable label pointing at a commit. You can start a branch to try an idea, commit on it freely, and **merge** it back into `main` when it works, or throw it away. Branches make it safe to experiment. You will use them in lesson 3 of this module.

## Git versus GitHub

- **Git** is the tool on your computer. It works completely offline.
- **GitHub** (and alternatives such as GitLab and Bitbucket) is a website that hosts Git repositories online so people can share them, review changes in **pull requests**, track issues and run automated checks.

Git is **distributed**: every clone of a repository has the full history, so there is no single point of failure and you can commit without a network connection.

## What version control is not

- It is not a backup by itself. Commits live on your machine until you push them to a remote such as GitHub.
- It is not great for large binary files (videos, big datasets). Text such as code, Markdown, CSV and configuration files works best, because Git can show line-by-line diffs.
- It does not keep secrets safe. Anything committed stays in history even if you delete it later, so passwords and API keys must never be committed.

## Worked example: a bug hunt

A colleague reports that the monthly report's totals are wrong since last week. With Git, you run `git log` to see the commits from that week, open the diff of the one that touched the totals code, and find that a rate was changed from `0.08` to `0.8`. You fix it in a new commit with the message "Fix tax rate typo introduced in a17b4d0". Without version control, you would be comparing files by eye.

## Quick recap

- A repository is a tracked folder; history is stored in `.git`.
- A commit is a snapshot plus message, author, date, parent and hash.
- Diffs show line-by-line changes; history lets you compare and undo.
- Working directory, staging area and repository are the three areas.
- Branches let you work safely in parallel; GitHub hosts repos and adds collaboration tools.

## Try it

Open the **Do** tab and take the quiz.


Understand what version control solves and what commits, history, diffs, repositories and branches are.

Why version control

A brief introduction to Git for beginners | GitHub

Git Explained in 100 Seconds

Check git --version (install Git if needed) and set user.name, user.email and init.defaultBranch main with git config --global.

Create and enter ~/cli-practice/field-notes, then run git init and git status.

Create README.md with a title and one sentence describing the project. Stage it with git add README.md and commit with a clear message.

Create notes.md with a few lines of notes on any topic. Run git status, git add notes.md, git diff --staged, then commit.

Edit notes.md again, run git diff to see the change, then use git restore notes.md to discard it and confirm with git status.

Make a real third change (for example add a checklist.md), stage it and commit it with an imperative message.

Run git log --oneline and check that you have three commits, each with a message that describes one change.

## Why it matters

Reading about Git only goes so far; the commands become natural once you have used them a few times on a real folder. In this lesson you create a repository, learn the everyday loop (**edit, status, add, commit**), and learn to write commit messages your future self and teammates will thank you for.

## Install and configure (once per computer)

Check whether Git is installed:

```bash
$ git --version
git version 2.47.0
```

If not: on **macOS**, running `git --version` offers to install the Command Line Developer Tools (or use Homebrew: `brew install git`); on **Linux**, use your package manager (`sudo apt install git` on Ubuntu or WSL); on **Windows**, Git for Windows (git-scm.com) includes Git Bash.

Tell Git who you are. This is recorded in every commit:

```bash
$ git config --global user.name "Your Name"
$ git config --global user.email "you@example.com"
$ git config --global init.defaultBranch main
$ git config --list
```

If you will push to GitHub and want to keep your email private, use the no-reply address GitHub shows in *Settings > Emails*.

## Create a repository

Always create repositories in a **project folder**, never in your home folder:

```bash
$ mkdir -p ~/cli-practice/field-notes
$ cd ~/cli-practice/field-notes
$ git init
Initialized empty Git repository in /Users/alex/cli-practice/field-notes/.git/
```

## The everyday loop

```bash
$ echo "# Field notes" > README.md
$ git status
On branch main
No commits yet
Untracked files:
  README.md
$ git add README.md
$ git status
Changes to be committed:
  new file:   README.md
$ git commit -m "Add README with project title"
[main (root-commit) 9e02c55] Add README with project title
 1 file changed, 1 insertion(+)
```

1. **Edit** files as usual.
2. `git status` shows what changed. Run it constantly; it also suggests next commands.
3. `git add <file>` stages a change (`git add .` stages everything in the current folder; check `git status` first).
4. `git commit -m "message"` records the staged snapshot.

## Seeing what changed

```bash
$ echo "Site visit: river gauge read 1.42 m" >> notes.md
$ git diff              # unstaged changes, line by line
$ git add notes.md
$ git diff --staged     # what will go into the next commit
$ git log --oneline     # history, newest first
```

Press `q` if output opens in a pager.

## Undoing before you commit

```bash
$ git restore notes.md            # discard unstaged edits to notes.md (cannot be undone)
$ git restore --staged notes.md   # unstage, but keep your edits
```

`git restore` on an edited file throws away those edits permanently, so check `git diff` first. (Older guides use `git checkout -- file` and `git reset HEAD file` for the same jobs; `git restore` needs Git 2.23 or newer.)

## Writing good commit messages

A commit message explains **what** changed and, when it is not obvious, **why**.

- Start with a short summary, ideally under about 50 characters, in the imperative: "Add", "Fix", "Remove", "Update" ("Fix rounding in totals", not "fixed stuff").
- One logical change per commit. "Add README" and "Fix typo in report" are two commits, not one.
- If you need more detail, leave a blank line after the summary and write a short paragraph (use `git commit` without `-m` to open an editor).

| Weak | Better |
|---|---|
| `update` | `Add gauge readings for 2 October` |
| `changes` | `Fix unit label: m, not cm` |
| `final version!!` | `Remove draft section on sampling` |

## Worked example: three meaningful commits

```bash
$ git log --oneline
c41d7a2 Add list of equipment to bring
5b8e310 Add notes from first site visit
9e02c55 Add README with project title
```

Each commit is small, has a clear message, and could be understood or undone on its own.

## Common mistakes

- Running `git init` in your home folder, which makes Git track everything you own. If it happens, delete only that `.git` folder (`rm -r ~/.git`) after double-checking the path.
- `git add .` without checking `git status`, committing junk or secret files.
- Huge commits mixing unrelated changes.
- Forgetting to configure `user.name` and `user.email`.

## Quick recap

- Configure Git once; create repos with `git init` in a project folder.
- Loop: edit, `git status`, `git add`, `git commit -m`.
- `git diff`, `git diff --staged` and `git log --oneline` show what changed.
- Small commits, imperative messages, one logical change each.

## Try it

Open the **Do** tab to create your first repository.


Install and configure Git, create a repository, and make three small, meaningful commits.

Your first repository

Beginner Git commands you need to know (WITH EXAMPLES)

Git & GitHub Tutorial for Beginners #6 - Making Commits

In ~/cli-practice/field-notes, run git status (it should be clean) and git branch.

Create a branch with git switch -c add-contacts, add a contacts.md file, and commit it.

Switch back to main (contacts.md disappears), then git merge add-contacts. Note that it is a fast-forward, and delete the branch with git branch -d add-contacts.

Set up a conflict: on main, add a line Meeting time: 10:00 to a new plan.md and commit it.

Create a branch change-time, change the line to Meeting time: 11:00 and commit.

Switch to main, change the same line to Meeting time: 09:30 and commit.

Run git merge change-time and read the CONFLICT message. Open plan.md and find the three marker lines.

Choose the final text, remove all markers, then git add plan.md and git commit to finish the merge.

Run git log --oneline --graph --all and find the merge commit with two parents.

## Why it matters

Real work rarely moves in a straight line. You start a feature, a bug report arrives, a teammate is changing the same file. **Branches** let several lines of work exist side by side without getting in each other's way, and **merging** brings them back together. Every team workflow on GitHub (next module) is built on branches.

## The core idea

A branch is just a **named pointer to a commit**. `main` points at the latest commit on the main line. When you create a branch and commit on it, only that branch's pointer moves. `HEAD` means "the branch you are on now".

```bash
$ git branch                   # list branches; * marks the current one
* main
$ git switch -c add-summary    # create a branch and switch to it
$ git branch
* add-summary
  main
```

(`git switch` needs Git 2.23+. Older guides use `git checkout -b add-summary`, which does the same.)

## Work on the branch, then merge

```bash
$ echo "## Summary" >> README.md
$ git commit -am "Add summary section to README"
$ git switch main               # README.md goes back to main's version
$ git merge add-summary
Updating 9e02c55..c41d7a2
Fast-forward
 README.md | 1 +
$ git branch -d add-summary     # delete the merged branch label
```

`commit -am` stages and commits every change to **already tracked** files in one step (new files still need `git add`).

**Fast-forward:** if `main` had no new commits since you branched, Git just moves `main`'s pointer forward. If both branches have new commits, Git creates a **merge commit** with two parents that combines them.

See the shape of history with:

```bash
$ git log --oneline --graph --all
```

## Merge conflicts

If both branches changed **the same lines** of the same file, Git cannot know which version is right, so it stops and asks you. That is a **merge conflict**. It is normal, not an error in your work.

### Worked example

On `main`, `plan.md` says `Meeting time: 10:00`. You create a branch `change-time` and change it to `11:00` and commit. Meanwhile, back on `main`, someone changes it to `09:30` and commits. Now:

```bash
$ git switch main
$ git merge change-time
Auto-merging plan.md
CONFLICT (content): Merge conflict in plan.md
Automatic merge failed; fix conflicts and then commit the result.
```

Open `plan.md`:

```text
<<<<<<< HEAD
Meeting time: 09:30
=======
Meeting time: 11:00
>>>>>>> change-time
```

- Between `<<<<<<< HEAD` and `=======` is **your current branch's** version (main).
- Between `=======` and `>>>>>>> change-time` is the **incoming** version.

Resolve it:

1. Decide what the line should say. Keep one side, the other, or write a combination. Talk to the other person if unsure.
2. **Delete all three marker lines**, leaving clean content: `Meeting time: 11:00`.
3. Mark it resolved and finish the merge:

```bash
$ git status          # lists "both modified: plan.md"
$ git add plan.md
$ git commit          # Git suggests a merge message; save and close the editor
```

Editors such as VS Code highlight conflicts with buttons like "Accept Current Change" and "Accept Incoming Change", which edit the markers for you.

If you get lost, `git merge --abort` puts everything back to how it was before the merge.

## Habits that prevent pain

- Keep branches short-lived and focused: one feature or fix each.
- Merge `main` into your branch (or pull often) so you find conflicts early, when they are small.
- Name branches clearly: `fix-total-rounding`, `add-login-page`.
- Commit before switching branches. Git refuses to switch if uncommitted changes would be overwritten, and tells you so.

## Common mistakes

- Committing to the wrong branch. Check `git branch` or `git status` first.
- Committing a file that still contains `<<<<<<<` markers. Search for them before `git add`.
- Panicking at a conflict and deleting the repository. Use `git merge --abort` instead.
- Deleting an unmerged branch with `git branch -D` and losing its work. Plain `-d` refuses if the branch is not merged.

## Quick recap

- A branch is a movable pointer; `git switch -c name` creates one.
- `git merge branch` brings changes into the current branch: fast-forward or a merge commit.
- Conflicts happen when both sides change the same lines: edit, remove markers, `git add`, `git commit`, or `git merge --abort`.

## Try it

Open the **Do** tab to branch, merge and resolve a conflict on purpose.


Create a branch, merge it back into main, and resolve a simple merge conflict calmly.

Branches and merging

Git & GitHub Tutorial for Beginners #9 - Merging Branches (& conflicts)

The EXTREMELY helpful guide to merge conflicts

What version control is for, your first repository and commits, and branching, merging and conflicts.