Developers, data scientists, security and cloud engineers, and computer science teachers all work in a terminal and keep their work in Git. This beginner course starts from opening a terminal on macOS, Linux or Windows (Git Bash or WSL), then moves through navigating folders, creating and moving files safely, and chaining commands with pipes, grep and redirection. The Git module explains what version control is for, then has you create a repository, make meaningful commits, branch, merge and resolve a conflict. The final module puts your work on GitHub: remotes, push and pull, pull requests and code review, and a README and .gitignore that make a project easy to use. Every hands-on task happens in a practice folder, so nothing outside it can be harmed.

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

Git & the Command Line

Open a terminal: Terminal on macOS or Linux, Git Bash or a WSL Ubuntu terminal on Windows.

Run ls, then ls -a, and compare: which hidden entries (starting with a dot) appear?

Create the practice folder with mkdir ~/cli-practice and go into it with cd ~/cli-practice. Run pwd to confirm.

Go up with cd .., then back in using Tab completion: type cd cli and press Tab.

Try an absolute path: cd /tmp, then pwd, then cd - to jump back.

Press the Up arrow a few times to browse your history, then run clear.

Open the manual for ls (man ls, or ls --help in Git Bash) and find what the -t option does. Press q to quit.

## Why it matters

Graphical apps are great for everyday work, but much technical work happens in a **terminal**: running code, using Git, connecting to servers, installing tools, automating repetitive tasks. Servers in the cloud usually have no desktop at all. Being comfortable at the command line is one of the clearest signs of a working developer, data scientist, or security or cloud engineer.

## Terminal, shell, command

- The **terminal** is the window you type into.
- The **shell** is the program that reads your command and runs it. This course uses **bash** or **zsh**; the commands here work the same in both.
- A **command** is a program name, often followed by **options** (flags such as `-l`) and **arguments** (such as a folder name): `ls -l Documents`.

## Opening one

- **macOS:** open *Terminal* (Spotlight: Cmd+Space, type "Terminal"). The default shell is zsh.
- **Linux:** open *Terminal* from your apps menu (often Ctrl+Alt+T). The default shell is usually bash.
- **Windows:** install **Git for Windows** from git-scm.com, which includes **Git Bash**, a bash terminal. Or install **WSL** (Windows Subsystem for Linux: run `wsl --install` in an administrator PowerShell, then restart) to get a full Ubuntu terminal. Both work for this course. The built-in Command Prompt and PowerShell use different commands, so use Git Bash or WSL here.

You will see a **prompt**, something like `alex@laptop ~ %` or `alex@laptop:~$`. It is waiting for a command. Type one and press Enter.

## Where am I? `pwd`

The terminal is always "in" one folder (directory), the **working directory**. `pwd` (print working directory) shows it:

```bash
$ pwd
/Users/alex
```

On Linux and WSL it looks like `/home/alex`; in Git Bash, `/c/Users/alex`. The `$` here just stands for your prompt; do not type it.

## What is here? `ls`

```bash
$ ls
Desktop  Documents  Downloads  Pictures
$ ls -l          # long format: permissions, size, date
$ ls -a          # include hidden files (names starting with .)
$ ls -la Documents
```

Text after `#` is a comment and is ignored by the shell.

## Moving: `cd`

```bash
$ cd Documents        # go into Documents (relative path)
$ cd ..               # up one level
$ cd ~                # home folder (plain cd does the same)
$ cd /tmp             # absolute path, starts at the root /
$ cd -                # back to the previous folder
```

- An **absolute path** starts with `/` (or `~`, which means your home folder) and works from anywhere.
- A **relative path** starts from where you are now. `.` means "this folder" and `..` means "the parent folder".
- Folder names with spaces need quotes: `cd "My Projects"`.

In WSL, your Windows files are under `/mnt/c/Users/<name>`. In Git Bash they are under `/c/Users/<name>`.

## Worked example

```bash
$ pwd
/Users/alex
$ ls
Desktop  Documents  Downloads
$ cd Documents
$ pwd
/Users/alex/Documents
$ cd ..
$ pwd
/Users/alex
```

## Time-savers

- **Tab completion:** type `cd Doc` and press Tab; the shell fills in `Documents/`. Press Tab twice to see options. This saves time and prevents typos.
- **History:** the Up arrow brings back earlier commands.
- **Cancel:** Ctrl+C stops a running command or clears the line.
- **Clear the screen:** `clear` or Ctrl+L.
- **Help:** `man ls` shows the manual (press `q` to quit). In Git Bash, use `ls --help`.

## Common mistakes

- Typing the `$` from examples.
- Wrong capitals: `documents` is not `Documents` on Linux (macOS usually ignores case, but do not rely on it).
- Spaces in names without quotes: `cd My Projects` tries to go into `My`.
- Not knowing where you are. When in doubt, run `pwd`.

## Quick recap

- The terminal runs a shell (bash or zsh); use Git Bash or WSL on Windows.
- `pwd` shows where you are, `ls` lists what is there, `cd` moves.
- Absolute paths start at `/` or `~`; relative paths start where you are.
- Tab completion, Up arrow and Ctrl+C make the terminal fast and safe.

## Try it

Open the **Do** tab to set up your terminal and practice folder.


Open a terminal on macOS, Linux or Windows and move around your folders with pwd, ls and cd.

Opening a terminal

How to Navigate the Terminal with Bash [5 of 20] | Bash for Beginners

Command Line Crash Course For Beginners | Terminal Commands

cd ~/cli-practice and create a project structure in one command: mkdir -p lab-project/data/raw lab-project/data/clean lab-project/docs

Create files: touch lab-project/data/raw/run1.csv lab-project/data/raw/run2.csv lab-project/docs/notes.txt

Write a line into a file with echo "Project started" > lab-project/docs/log.txt and display it with cat.

Copy run1.csv into data/clean, then rename the copy to run1-clean.csv with mv.

Copy the whole lab-project folder to lab-project-backup with cp -r, and list both with ls -R.

Create three junk files (touch a.tmp b.tmp c.tmp), preview them with ls *.tmp, then delete them with rm -i *.tmp.

Delete the backup folder: run pwd, preview with ls lab-project-backup, then rm -r lab-project-backup.

Run ls -R lab-project and check the final structure matches what you intended.

## Why it matters

Setting up a project, organising data files, cleaning up build output, moving logs on a server: all of it is file management, and the terminal does it faster and more repeatably than clicking. It is also less forgiving. The terminal has **no recycle bin**: a deleted file is gone. This lesson covers the commands and the habits that keep you safe.

**Safety rule for this course:** practise only inside `~/cli-practice`. Never use `sudo` for these commands, and never aim `rm` at your home folder or `/`.

## Making folders and files

```bash
$ cd ~/cli-practice
$ mkdir project                  # one folder
$ mkdir -p project/data/raw      # -p creates the parent folders too
$ touch project/notes.txt        # empty file (or updates its timestamp)
$ echo "first line" > project/todo.txt   # file with content (more on > next lesson)
```

## Looking at files

```bash
$ cat project/todo.txt     # print the whole file
first line
$ less bigfile.txt         # page through: Space = next page, q = quit
$ head -n 5 data.csv       # first 5 lines
$ tail -n 5 app.log        # last 5 lines
```

`cat` is fine for short files; use `less` or `head` for long ones.

## Copying: `cp`

```bash
$ cp project/todo.txt project/todo-backup.txt    # copy a file
$ cp project/todo.txt project/data/              # copy into a folder (keeps the name)
$ cp -r project project-copy                     # -r copies a folder and everything in it
```

## Moving and renaming: `mv`

`mv` does both. Moving to a new name in the same folder **is** renaming:

```bash
$ mv project/notes.txt project/meeting-notes.txt   # rename
$ mv project/todo-backup.txt project/data/          # move into a folder
```

Careful: if the destination file already exists, `cp` and `mv` **overwrite it without asking**. Add `-i` (interactive) to be asked first: `mv -i a.txt b.txt`.

## Deleting: `rm` and `rmdir`

```bash
$ rm project/data/todo-backup.txt   # delete a file, permanently
$ rmdir project/data/raw            # delete an EMPTY folder
$ rm -r project-copy                # delete a folder and everything inside
$ rm -i *.tmp                       # ask before each deletion
```

`rm -r` is the most dangerous everyday command. Before running it:

1. Run `pwd` to confirm where you are.
2. Run `ls` with the **same path or pattern** first (`ls project-copy`) to see exactly what would go.
3. Prefer specific paths over wildcards; use `-i` when unsure.

You will see `rm -rf` (force, no questions) in tutorials. Avoid it while learning.

## Wildcards

The shell expands patterns before the command runs:

| Pattern | Matches |
|---|---|
| `*.csv` | every name ending in `.csv` |
| `report-*` | names starting with `report-` |
| `data?.txt` | `data1.txt`, `dataA.txt` (exactly one character) |

```bash
$ ls *.csv          # preview first
$ mv *.csv data/    # then act
```

## Worked example: organise a messy folder

```bash
$ cd ~/cli-practice
$ mkdir -p tidy && cd tidy
$ touch jan.csv feb.csv mar.csv notes.txt draft.tmp old.tmp
$ mkdir data
$ ls *.csv
feb.csv  jan.csv  mar.csv
$ mv *.csv data/
$ ls *.tmp
draft.tmp  old.tmp
$ rm -i *.tmp
remove draft.tmp? y
remove old.tmp? y
$ ls -R
.:
data  notes.txt

./data:
feb.csv  jan.csv  mar.csv
```

`&&` runs the second command only if the first succeeds, so `cd tidy` only happens if `mkdir` worked. `ls -R` lists folders recursively.

## Common mistakes

- `rm` in the wrong folder. Check `pwd` first.
- A space in a path: `rm my file.txt` tries to delete two files, `my` and `file.txt`. Quote it: `rm "my file.txt"`.
- Overwriting with `mv`/`cp` by accident. Use `-i`.
- Copying a folder without `-r` (you get "is a directory" or "omitting directory").

## Quick recap

- `mkdir -p`, `touch` and `echo ... >` create; `cat`, `less`, `head`, `tail` view.
- `cp` copies (`-r` for folders); `mv` moves and renames.
- `rm` deletes permanently; `rm -r` deletes folders. Preview with `ls`, check `pwd`, use `-i`.
- Wildcards (`*`, `?`) select many files: always preview them first.

## Try it

Open the **Do** tab to build and reorganise a small project folder.


Create, view, copy, move, rename and delete files and folders from the terminal without losing anything by accident.

Creating and moving files

Linux/Mac Terminal Tutorial: Create, Copy, Move, Rename and Delete Files and Directories

cd ~/cli-practice and create app.log with the here-document from the reading (copy the whole block from cat to EOF).

Check the file: wc -l app.log should report 8 lines.

Count the errors with grep -c ERROR app.log (expect 3) and find the line number of the auth failure with grep -n auth app.log (expect 6).

Show every line that is not INFO with grep -v INFO app.log (5 lines).

Build the ranking pipeline step by step: grep ERROR app.log, then add | cut -d' ' -f4-, then | sort | uniq -c | sort -rn. Look at the output after each step.

Save the ranking with > error-report.txt, then append a title line with echo "Report for 2026-10-01" >> error-report.txt, and cat the file.

Capture an error: ls missing-file 2> errors.txt, then cat errors.txt.

Write one pipeline of your own that answers a question about app.log (for example, how many WARN lines mention a request).

## Why it matters

The real power of the command line is combining small tools. One line can find every error in a log, count them by type and save a report, on a file far too big to open in an editor. Developers use this to debug, data scientists to peek at datasets, and security engineers to sift logs for attacks.

## Streams: input, output, errors

Every command has three streams:

- **standard input** (stdin): what it reads, by default the keyboard,
- **standard output** (stdout): normal results, by default the screen,
- **standard error** (stderr): error messages, also the screen by default.

Redirection and pipes reconnect these streams.

## Redirection: send output to a file

```bash
$ ls > files.txt          # stdout to a file (creates or OVERWRITES it)
$ echo "more" >> files.txt  # append to the end instead
$ ls nothere 2> errors.txt  # stderr to a file
$ sort < names.txt          # read stdin from a file
```

`>` silently replaces the file's contents. Use `>>` when you want to add. Never redirect into the file you are reading: `sort data.txt > data.txt` empties `data.txt` before `sort` reads it.

## A practice log

Create this file in `~/cli-practice` (the `<<'EOF'` part is a "here document": everything up to `EOF` becomes the file):

```bash
cat > app.log <<'EOF'
2026-10-01 09:00:01 INFO server started
2026-10-01 09:02:13 WARN disk 80% full
2026-10-01 09:05:44 ERROR db timeout
2026-10-01 09:06:02 INFO request /home 200
2026-10-01 09:07:30 ERROR db timeout
2026-10-01 09:09:12 ERROR auth failed
2026-10-01 09:10:00 INFO request /login 200
2026-10-01 09:11:45 WARN slow request /search
EOF
```

## grep: find lines that match

```bash
$ grep ERROR app.log         # lines containing ERROR
$ grep -i error app.log      # ignore case
$ grep -n auth app.log       # show line numbers
6:2026-10-01 09:09:12 ERROR auth failed
$ grep -c ERROR app.log      # count matching lines
3
$ grep -v INFO app.log       # lines that do NOT match (5 lines)
$ grep -r "TODO" project/    # search every file in a folder
```

Put patterns with spaces or special characters in quotes: `grep "db timeout" app.log`.

## Pipes: output of one command into the next

The `|` (pipe) sends one command's stdout into the next command's stdin:

```bash
$ grep ERROR app.log | wc -l     # count error lines: 3
$ ls -l | less                   # page through a long listing
$ history | grep git             # find earlier git commands
```

Useful pipeline tools:

| Command | Does |
|---|---|
| `wc -l` | count lines |
| `sort` | sort lines (`-n` numeric, `-r` reverse) |
| `uniq -c` | collapse **adjacent** duplicates and count them (sort first) |
| `head -n 3` / `tail -n 3` | first / last lines |
| `cut -d' ' -f3` | pick field 3 of each line, splitting on spaces |

## Worked example: which errors happen most?

Build the pipeline one step at a time and look at the output after each step:

```bash
$ grep ERROR app.log
2026-10-01 09:05:44 ERROR db timeout
2026-10-01 09:07:30 ERROR db timeout
2026-10-01 09:09:12 ERROR auth failed
$ grep ERROR app.log | cut -d' ' -f4-
db timeout
db timeout
auth failed
$ grep ERROR app.log | cut -d' ' -f4- | sort | uniq -c | sort -rn
      2 db timeout
      1 auth failed
$ grep ERROR app.log | cut -d' ' -f4- | sort | uniq -c | sort -rn > error-report.txt
```

`-f4-` means "field 4 to the end". The last line saves the report instead of printing it. The same pipeline works on a million-line log.

## Common mistakes

- `>` when you meant `>>`, overwriting a file you wanted to keep.
- `uniq` without `sort` first, so non-adjacent duplicates are not merged.
- Forgetting quotes around patterns with spaces: `grep db timeout app.log` searches for `db` in two files named `timeout` and `app.log`.
- Writing one giant pipeline at once. Build it step by step.

## Quick recap

- `>` writes (overwrites), `>>` appends, `2>` captures errors, `<` reads from a file.
- `grep` finds lines: `-i`, `-n`, `-c`, `-v`, `-r`.
- `|` chains commands; `sort | uniq -c | sort -rn` is the classic "count and rank" pattern.

## Try it

Open the **Do** tab to analyse the practice log with pipelines.


Search text with grep, save output to files with redirection, and chain small commands into useful pipelines.

Pipes, grep, and redirection

How to Use Redirection and Pipelines in Bash [11 of 20] | Bash for Beginners

Linux/Mac Terminal Tutorial: The Grep Command - Search Files and Directories for Patterns of Text

Open a terminal on any system, navigate folders, manage files safely, and chain commands with pipes and grep.

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.

Git Basics

Create a free GitHub account (or sign in) and enable two-factor authentication.

Create a new, empty repository named field-notes (no README, .gitignore or license).

Set up authentication: gh auth login with the GitHub CLI, the Git Credential Manager, or an SSH key added to your account.

In ~/cli-practice/field-notes run git remote add origin <your repo URL> and check it with git remote -v.

Run git branch -M main and git push -u origin main, then refresh GitHub and look at your files and commit history.

On GitHub, edit README.md in the browser and commit the change.

Locally, run git fetch and git status (it should say you are behind by 1 commit), then git pull and check the file.

Make a local change, commit it, and git push. Confirm it appears on GitHub.

Clone the repo into ~/cli-practice/field-notes-copy and run git log --oneline there to see the full history.

## Why it matters

So far your repository lives only on your computer. A **remote** is a copy of the repository hosted somewhere else, usually GitHub. Pushing to a remote backs up your work, lets you work from several machines, and is the starting point for collaborating: teammates pull your commits and you pull theirs. A public GitHub profile with real projects is also one of the best things to show an employer.

## Key terms

- **Remote:** a named link to another copy of the repo. By convention the main one is called `origin`.
- **Push:** send your new commits to the remote (`git push`).
- **Fetch:** download new commits from the remote without changing your files (`git fetch`).
- **Pull:** fetch and then merge them into your current branch (`git pull`).
- **Clone:** copy a remote repository to your computer, with full history (`git clone <url>`).

## Step 1: a GitHub account and an empty repository

1. Sign up at github.com (free). Turn on two-factor authentication in *Settings > Password and authentication*.
2. Click **New repository**. Name it `field-notes`. Choose **Private** if you are unsure; you can make it public later.
3. Leave "Add a README", ".gitignore" and "license" **unticked**, because your local repo already has history. GitHub then shows the commands to push an existing repository.

## Step 2: authenticate

GitHub no longer accepts your account password for Git over HTTPS. Use one of these:

- **GitHub CLI:** install `gh` from cli.github.com and run `gh auth login`; it sets up Git credentials for you.
- **Git Credential Manager:** included with Git for Windows; on first push a browser window asks you to sign in.
- **SSH keys:** generate a key with `ssh-keygen -t ed25519 -C "you@example.com"`, add the public key (the `.pub` file) in *Settings > SSH and GPG keys*, and use the SSH URL (`git@github.com:you/field-notes.git`).

Never share your private key or paste tokens into files in the repository.

## Step 3: connect and push

```bash
$ cd ~/cli-practice/field-notes
$ git remote add origin https://github.com/<your-username>/field-notes.git
$ git remote -v
origin  https://github.com/<your-username>/field-notes.git (fetch)
origin  https://github.com/<your-username>/field-notes.git (push)
$ git branch -M main               # make sure the branch is called main
$ git push -u origin main
```

`-u` sets `origin/main` as the **upstream** of your local `main`, so from now on plain `git push` and `git pull` know where to go. Refresh the GitHub page and your files and commit history are there.

## Step 4: pull a change made elsewhere

Edit a file directly on GitHub (open `README.md`, click the pencil icon, change a line, *Commit changes*). Your local copy does not know yet:

```bash
$ git status
Your branch is up to date with 'origin/main'.    # it has not checked the remote
$ git fetch
$ git status
Your branch is behind 'origin/main' by 1 commit, and can be fast-forwarded.
$ git pull
Fast-forward
 README.md | 2 +-
```

Habit: **pull before you start work** each day, and push when you finish a piece of work.

## When a push is rejected

```text
! [rejected]        main -> main (fetch first)
error: failed to push some refs
hint: Updates were rejected because the remote contains work that you do not have locally.
```

Someone (maybe you on GitHub) pushed commits you do not have. Run `git pull`, resolve any conflicts as in the last lesson, then `git push` again.

You will see advice to use `git push --force`. It **overwrites** the remote history and can destroy teammates' work. Do not use it on shared branches.

## Cloning

To get a repository onto a new machine, or to start from someone else's project:

```bash
$ cd ~/cli-practice
$ git clone https://github.com/<your-username>/field-notes.git field-notes-copy
```

The clone already has `origin` set up.

## Common mistakes

- Ticking "Add a README" when creating the GitHub repo, then getting "unrelated histories" on the first push. Create it empty.
- Typing your GitHub password when Git asks for one over HTTPS. Use `gh auth login`, the credential manager, or SSH.
- Pushing secrets or private data to a public repository. Check `git status` and `git diff --staged` before committing.
- Not pulling for days, then facing a huge conflict.

## Quick recap

- A remote (`origin`) is a hosted copy; `git remote -v` lists remotes.
- `git push -u origin main` the first time; then `git push` and `git pull`.
- `fetch` downloads, `pull` downloads and merges; a rejected push means pull first.
- Authenticate with the GitHub CLI, the credential manager or SSH keys; never force push shared branches.

## Try it

Open the **Do** tab to put your repository on GitHub.


Connect a local repository to GitHub, push your commits, and pull changes made elsewhere.

Remotes, push, and pull

How to clone, push, and pull with git (beginners GitHub tutorial)

1.6: Cloning Repo and Push/Pull - Git and GitHub for Poets

In ~/cli-practice/field-notes, run git switch main and git pull.

Create a branch with git switch -c add-site-checklist, add checklist.md with 4 or 5 items, and commit it.

Push the branch with git push -u origin add-site-checklist.

On GitHub, open a pull request from add-site-checklist into main with a clear title and a What / Why / How to check description.

Open the Files changed tab and leave a line comment on one item that could be clearer (or use the suggestion button to propose new text).

Back in the terminal, make that improvement on the same branch, commit with a message that mentions the review, and push.

On GitHub, check that the new commit appears in the PR, reply to the comment saying what you changed, and click Resolve conversation.

Merge the pull request (any merge method) and delete the branch on GitHub.

Locally, switch to main, git pull, and delete the local branch (git branch -d, or -D if it was squash-merged).

## Why it matters

On most teams, nobody pushes straight to `main`. Changes go on a branch, and a **pull request** (PR) asks for that branch to be merged. Teammates review the diff, comment, request changes and approve; automated checks run tests. This catches bugs, spreads knowledge across the team and leaves a written record of why each change was made. Knowing how to open a clear PR and handle feedback gracefully is a core professional skill.

## The pull request workflow

1. **Update main:** `git switch main && git pull`.
2. **Branch:** `git switch -c add-site-checklist`.
3. **Commit** focused changes on the branch.
4. **Push the branch:** `git push -u origin add-site-checklist`.
5. **Open the PR** on GitHub: a yellow banner offers *Compare & pull request*, or use the *Pull requests* tab > *New pull request*, with base `main` and compare `add-site-checklist`.
6. **Review:** reviewers read the *Files changed* tab and comment.
7. **Respond:** push more commits to the same branch; the PR updates automatically.
8. **Merge** when approved and checks pass, then delete the branch.

## Writing a good PR

**Title:** a short summary, like a commit message: "Add pre-visit safety checklist".

**Description:** answer what, why and how to check:

```markdown
## What
Adds checklist.md with the items to confirm before a site visit.

## Why
We forgot the spare batteries twice last month.

## How to check
Open checklist.md and compare it with the equipment list in notes.md.
```

Keep PRs small. A 50-line PR gets a careful review; a 2,000-line PR gets a rubber stamp. If you are not finished, open it as a **draft pull request** to share early work.

## Reviewing code

On the *Files changed* tab:

- Hover a line and click the **+** to comment on it. Use **Start a review** to batch several comments.
- Use the **suggestion** button (the file icon with +/- in the comment box) to propose exact replacement text the author can accept with one click.
- Finish with *Review changes*: **Comment**, **Approve** or **Request changes**. (You cannot approve your own PR, but you can comment on it.)

Good review comments are specific, kind and about the code, not the person:

| Unhelpful | Helpful |
|---|---|
| "This is wrong." | "This adds up the hours, but the header says minutes. Should it be `* 60`?" |
| "Bad name." | "Could we call this `site_count` instead of `x`? It took me a while to see what it holds." |
| (silence on good work) | "Nice, the checklist order matches the visit plan." |

Mark small preferences as optional, for example "nit: extra blank line".

## Responding to a review

- **Make the change** on the same branch, commit with a clear message ("Use minutes in total, per review"), and push. The new commit appears in the PR.
- **Reply** to each comment: "Done in 3a1f9e2", or explain why you chose differently. Disagreeing politely with reasons is fine.
- **Resolve conversation** once a thread is handled, so reviewers can see what is left.
- **Re-request review** with the circular arrow icon next to the reviewer's name.

Do not take review personally. Comments are about making the work better, and senior engineers get them too.

## Merging and cleaning up

GitHub offers three merge buttons:

- **Create a merge commit:** keeps every commit and adds a merge commit.
- **Squash and merge:** combines all the PR's commits into one on `main`. Common on teams that want a tidy history.
- **Rebase and merge:** replays the commits onto `main` without a merge commit.

Follow your team's convention. Afterwards, delete the branch on GitHub (there is a button), then locally:

```bash
$ git switch main
$ git pull
$ git branch -d add-site-checklist
```

If the branch was squash-merged, Git may say it is "not fully merged" because the original commits are not on `main`. Once you have checked that the PR really was merged on GitHub, `git branch -D add-site-checklist` deletes it.

## Forks

To contribute to a project you cannot push to (most open source), you **fork** it (copy it to your account), push a branch to your fork, and open a PR from your fork to the original. The review process is the same.

## Common mistakes

- Opening a PR from `main` instead of a branch.
- Huge PRs mixing several unrelated changes.
- Empty descriptions that make reviewers guess.
- Closing the PR and opening a new one for every fix, instead of pushing to the same branch.
- Forgetting to pull `main` after merging, then branching from stale code.

## Quick recap

- Branch, push the branch, open a PR, review, respond with new commits, merge, delete the branch.
- Clear title, a what/why/how-to-check description, and small scope.
- Review with specific, kind line comments and suggestions; respond, resolve, re-request.

## Try it

Open the **Do** tab to open a PR, review it, and respond to a comment.


Open a pull request from a branch, review changes line by line, and respond to review comments with new commits.

Pull requests and code review

How to create a pull request in 4 min | GitHub for Beginners

How to Review a Pull Request in GitHub the RIGHT Way

Create a branch: git switch main, git pull, git switch -c improve-readme.

Rewrite README.md with a title, one-sentence description, why it exists, how to get it (git clone command), how to use it, and a License section.

Preview it: push the branch and view README.md on GitHub, or use your editor's Markdown preview, and fix any formatting problems.

Create a .gitignore with at least: .DS_Store, Thumbs.db, *.log, .env and one folder pattern such as build/.

Test it: create test.log and .env (with a fake value like API_KEY=placeholder) and confirm with git status that neither appears. Run git check-ignore -v test.log.

Add a .env.example with placeholder values and mention it in the README.

Commit the README, .gitignore and .env.example with clear messages, push, open a PR, and merge it.

Optional: add a LICENSE using GitHub's Add file > Create new file, typing LICENSE as the name and choosing a template.

Clone the repo into a fresh folder and follow your README exactly. Fix anything that does not work.

## Why it matters

The README is the front page of a repository. Recruiters, teammates and your future self decide in seconds whether a project is understandable and usable. A `.gitignore` file keeps the repository clean by stopping clutter (system files, dependencies, build output) and, more importantly, **secrets** from being committed. Together they are the difference between a pile of files and a professional project.

## The README

GitHub shows `README.md` below the file list. It is written in **Markdown**:

```markdown
# Project title

**Bold**, *italic*, `inline code`, [a link](https://example.com)

## A section
- a bullet
1. a numbered step
```

Fenced code blocks use three backticks with a language name, which GitHub colours.

### What to include

1. **Title and one-sentence description:** what it is and who it is for.
2. **Why it exists** or what problem it solves.
3. **Getting started:** prerequisites and install steps, as copyable commands.
4. **Usage:** a short example of running it and what the output looks like. A screenshot helps for visual projects.
5. **Project structure** (optional): what the main folders hold.
6. **Contributing:** how to report issues or open PRs.
7. **License:** what others may do with it.
8. **Contact or credits.**

Small projects can be short, but everyone needs at least 1, 3 and 4.

### Worked example

````markdown
# unit-converter

A tiny command-line tool that converts lab measurements between metric and US units.

## Getting started
Requires Python 3.10 or newer.

```bash
git clone https://github.com/<you>/unit-converter.git
cd unit-converter
python3 convert.py --help
```

## Usage
```bash
python3 convert.py 12.5 psi kPa
# 86.18 kPa
```

## License
MIT. See LICENSE.
````

Test your own instructions: clone the repo into a fresh folder and follow the README exactly. If a step is missing, you will find out.

## The `.gitignore` file

A text file named `.gitignore` in the repository root. Each line is a pattern of paths Git should **not** track:

```gitignore
# operating system clutter
.DS_Store
Thumbs.db

# dependencies and build output
node_modules/
__pycache__/
dist/
build/

# logs and local data
*.log
data/raw/

# secrets and local settings
.env
*.pem
```

- `#` starts a comment.
- A trailing `/` matches folders.
- `*` is a wildcard: `*.log` ignores every log file.
- `!` re-includes something: `!keep.log`.

Commit the `.gitignore` itself so everyone shares the rules. GitHub's template collection (github.com/github/gitignore) has ready-made files for Python, Node, Unity, Java and more, and you can pick one when creating a repository.

Check why a file is ignored with `git check-ignore -v path/to/file`.

### Already-tracked files

`.gitignore` only affects **untracked** files. If you already committed `debug.log`, adding `*.log` does not remove it. Stop tracking it (but keep it on disk) with:

```bash
$ git rm --cached debug.log
$ git commit -m "Stop tracking debug.log"
```

### Secrets

If a password, API key or token is ever committed and pushed, assume it is compromised: **revoke it and create a new one** at the provider. Deleting it in a later commit does not remove it from history. Prevent this by keeping secrets in `.env` (ignored) and committing a `.env.example` with placeholder values so others know which settings exist.

## Other hygiene

- **LICENSE:** without one, others have no clear permission to reuse your code. choosealicense.com explains common options (MIT, Apache 2.0, GPL).
- **Descriptive repository name and About text** on GitHub, with a few topic tags.
- **Small, clearly messaged commits** (lesson 2 of module 2) make the history readable too.
- Do not commit large datasets or binaries; link to where they can be downloaded instead.

## Common mistakes

- A README that is only the title, or a template left unchanged.
- Install steps that worked only on your machine.
- Adding `.gitignore` after committing `node_modules/` or `.env`, and assuming that fixed it.
- Ignoring files the project needs to run (for example a small sample data file).

## Quick recap

- README: what it is, how to install, how to use, license. Test the steps from a fresh clone.
- `.gitignore`: patterns for OS files, dependencies, build output, logs and secrets; commit it.
- `git rm --cached` stops tracking an already committed file; leaked secrets must be revoked.

## Try it

Open the **Do** tab to give your repository a proper README and `.gitignore`.


Write a README that tells people what your project is and how to use it, and a .gitignore that keeps junk and secrets out of Git.

READMEs and project hygiene

Getting started with Markdown on GitHub

What is a .gitignore file and why do you need it?

Remotes, push and pull, pull requests and code review, and READMEs and .gitignore files.

Git & the Command Line

About this course

Course content

The Command Line

Git Basics

Collaborating on GitHub

Where this course leads

Next course on the path

Careers that use it