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

Git & the Command Line

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.