# Git From Zero - Version Control for People Who've Never Used It

> Start from nothing: what version control is, how to install Git, make your first commit, and get your code on GitHub - calmly, with every step explained.


---

# Git From Zero - Version Control for People Who've Never Used It

Maybe you've got a folder called `project_final_v2_REALLY-final`. Maybe someone said "just push it to the
repo" and your stomach tightened because you weren't sure what any of those words meant. Maybe you've
never opened a terminal in your life. That's exactly who this guide is for.

We start from absolute zero - nothing installed, nothing assumed - and walk together until you've made
your first commit and put real code on GitHub. No memorizing spells, no pretending it's obvious. By the
end, "version control" won't be a phrase you nod along to; it'll be a thing you actually do.

## How to read this
- **Brand new and just want it working?** Read in order, type along, top to bottom. Each phase is one
  sitting.
- **Something's already gone wrong?** Jump to [Phase 4: When the First Day Goes Sideways](04-first-day-snags.md)
  and find your error message in the cheat-card.

## The phases
1. **[What Version Control Even Is](01-what-is-version-control.md)** - the why, the Git-vs-GitHub
   confusion cleared up, and getting Git installed and ready on your computer.
2. **[Your First Repository](02-your-first-repository.md)** - make a project, take your first snapshots
   with `add` and `commit`, all on your own machine. No internet required.
3. **[Putting It on GitHub](03-putting-it-on-github.md)** - what GitHub actually is, how to connect to
   it, the authentication part nobody warns you about, and your first `push`.
4. **[When the First Day Goes Sideways](04-first-day-snags.md)** - the handful of errors that ambush
   every beginner, each with a calm one-line fix.

> This guide gets your hands on the keyboard. Once the moves feel familiar, the next guide -
> [Git, Explained Like You're a Human](/guides/git-explained-like-a-human) - shows you what Git was
> *actually doing* underneath every command, so the scary words (branches, HEAD, merge conflicts) stop
> being scary.


---

# What Version Control Even Is (and Getting Git Installed)

Before we touch a single command, let's clear up what this thing *is* - because if you don't know what
problem Git solves, every command will feel like a magic word you're scared to get wrong.

So: what's the problem?

## The problem version control actually solves

You're working on something. It works. You want to change it - but you're afraid that if the change
breaks everything, you won't be able to get back to the version that worked. So you do what everyone
does: you copy the whole folder and name it `project-backup`. Then `project-backup-2`. Then
`project-final`. Then `project-final-ACTUALLY-final`.

And when a teammate emails you *their* copy, now there are two histories and no way to safely combine
them. You're manually comparing files at midnight trying to figure out whose version is right.

**That entire mess is what version control was invented to delete.**

**What version control actually is.** It's a tool that takes named snapshots of your *whole project* and
remembers every one of them, forever. Think of save points in a video game - except *you* decide when to
save, *you* write a note on each save ("beat the boss," "fixed the login bug"), and you can return to any
save you've ever made. No more copied folders. The folder stays one folder; the history lives quietly
alongside it.

It does one more thing the copied-folders approach never could: it lets several people work on the same
project and combine their work intelligently, instead of overwriting each other.

📝 **Terminology.** *Version control* (also called *source control*) is the general idea. *Git* is the
specific, wildly popular tool that does it. When people say "the repo," they mean a project that Git is
tracking. We'll define "repo" properly in [Phase 2](02-your-first-repository.md).

## Git is not GitHub (this trips up everybody)

You will hear "Git" and "GitHub" used almost interchangeably, and it causes real confusion on day one.
They are two different things:

```text
   GIT                                   GITHUB
   ─────────────────────────             ─────────────────────────
   A program on your computer.           A website (github.com).
   Takes the snapshots.                  Stores copies of your project
   Works with zero internet.             online so you (and others)
                                         can access and share them.

   The tool.                             A place to keep a copy of
                                         what the tool produces.
```

A useful comparison: **Git is like a word processor; GitHub is like Google Drive.** One creates and
manages the work on your machine; the other is a place on the internet to store and share it. There are
other such websites (GitLab, Bitbucket) - GitHub is just the most common. You can use Git completely on
your own with no account anywhere, which is exactly what we'll do in Phase 2. GitHub doesn't enter the
picture until [Phase 3](03-putting-it-on-github.md).

💡 **Key point.** Git lives on your computer and does the real work. GitHub is an optional online home
for a copy of it. Get this distinction now and half of the early confusion never happens.

## Step 1: Install Git

Git is a small free program. Installing it is the same as installing any app - find your operating system
below.

**Windows.** Download the installer from [git-scm.com/download/win](https://git-scm.com/download/win) and
run it. The default options are fine - keep clicking Next. This also installs a terminal called **Git
Bash**, which is where you'll type the commands in this guide.

**macOS.** Open the **Terminal** app (press `Cmd-Space`, type "Terminal", hit Enter) and type
`git --version`. If Git isn't installed yet, macOS offers to install the developer command-line tools for
you - accept it. (If you use [Homebrew](https://brew.sh), `brew install git` works too.)

**Linux (Debian/Ubuntu).** Open a terminal and run:
```console
$ sudo apt update && sudo apt install git
```
On Fedora it's `sudo dnf install git`. (`sudo` means "do this as administrator"; it'll ask for your
password.)

## Step 2: Check it worked

Open your terminal (Git Bash on Windows; Terminal on macOS/Linux) and type:
```console
$ git --version
git version 2.43.0
```
*What just happened:* You asked Git to report its version, and it answered. The exact number doesn't
matter - any answer at all means Git is installed and your terminal can find it. (If instead you got
`command not found` or `'git' is not recognized`, see [Phase 4](04-first-day-snags.md) - it's a common,
fixable first stumble.)

## Step 3: Tell Git who you are

This is the one setup step everyone skips and then trips over. Remember that every snapshot gets a note?
It also gets *signed* with your name and email, so that later - especially when working with others -
history shows who made each change. Git refuses to take its first snapshot until you've told it who you
are.

You only do this once per computer. Type these two lines, with your own name and email:
```console
$ git config --global user.name "Ada Lovelace"
$ git config --global user.email "ada@example.com"
```
*What just happened:* Nothing printed, and that's correct - these commands save your settings quietly.
`--global` means "use this for every project on this computer," so you never have to repeat it. Use the
same email you'll later use for GitHub; it makes your commits line up with your account.

While you're here, set the default name for the starting branch to `main` (the modern standard - don't
worry about what a branch is yet):
```console
$ git config --global init.defaultBranch main
```

To confirm it all saved:
```console
$ git config --global --list
user.name=Ada Lovelace
user.email=ada@example.com
init.defaultBranch=main
```
*What just happened:* Git read back the settings you just stored. Seeing your name and email here means
you're fully set up.

⚠️ **Gotcha.** If you skip this step, your very first commit in Phase 2 fails with `Author identity
unknown / Please tell me who you are`. It looks alarming but means only this: you haven't run the two
`config` commands above. Run them and try again. (It's in the Phase 4 cheat-card too.)

## Recap

1. **Version control** = named save-points for your whole project, kept forever, plus a sane way to
   combine work from multiple people.
2. **Git** is the tool on your computer; **GitHub** is an optional website that hosts copies. Not the
   same thing.
3. You **installed Git** and proved it with `git --version`.
4. You **told Git who you are** with `git config --global user.name`/`user.email` - required before your
   first commit.

Your machine is ready. Next, you'll make an actual project and take your first snapshot - entirely
offline, no GitHub needed yet.


---

# Your First Repository - init, add, commit, log

Git is installed and knows your name. Now you'll actually use it: create a project, and take your first
real snapshot of it. Everything in this phase happens on your own computer - no internet, no GitHub, no
account. Git works perfectly well entirely alone, and starting here keeps the moving parts to a minimum.

Type along. Doing it once in your own terminal teaches more than reading it five times.

## Make a project folder

First, a plain folder with one file in it. In your terminal:
```console
$ mkdir hello-git
$ cd hello-git
```
*What just happened:* `mkdir` ("make directory") created an empty folder called `hello-git`, and `cd`
("change directory") moved you *into* it. Your terminal is now "standing inside" that folder, so the
commands you type next apply there. Nothing about Git yet - this is just a normal folder.

## `git init` - start tracking this folder

```console
$ git init
Initialized empty Git repository in /home/ada/hello-git/.git/
```
*What just happened:* `git init` ("initialize") turned this ordinary folder into one Git is watching. It
did that by creating a hidden sub-folder named `.git` - see it mentioned in the output? That hidden folder
*is* the repository: it's where Git will quietly store every snapshot and all the history. Your files stay
exactly where they are; Git just added a notebook to the corner of the room.

📝 **Terminology.** A **repository** (everyone says "repo") is a project folder that Git is tracking,
together with its entire history stored in that hidden `.git` folder. "Make a repo" just means "run
`git init` in a folder."

⚠️ **Gotcha.** Run `git init` *inside the folder you want to track* - check with `cd` first. Accidentally
running it in your home folder or Desktop makes Git try to track everything you own, which is a confusing
mess to undo. If you ever see `fatal: not a git repository` later, it's the opposite problem: you're
standing in a folder Git isn't watching. Both are in the [Phase 4 cheat-card](04-first-day-snags.md).

## Create a file, then check `git status`

Let's add something to take a snapshot of. Create a simple text file:
```console
$ echo "Hello, Git!" > hello.txt
```
*What just happened:* `echo` printed the text `Hello, Git!`, and `>` redirected that text into a new file
called `hello.txt` instead of to the screen. (You could just as easily create the file in any text
editor - this is only a quick way to do it from the terminal.)

Now ask Git what it sees:
```console
$ git status
On branch main

No commits yet

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        hello.txt

nothing added to commit but untracked files present (use "git add" to track)
```
*What just happened:* `git status` is your dashboard - it reports the state of things and changes nothing,
so run it as often as you like. It's telling you two things: there are `No commits yet` (you haven't taken
any snapshots), and `hello.txt` is **untracked** - Git can see the file sitting there but isn't recording
it yet. New files start out untracked; you opt them in.

## `git add` - choose what goes in the snapshot

```console
$ git add hello.txt
$ git status
On branch main

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)
        new file:   hello.txt
```
*What just happened:* `git add hello.txt` moved the file into a holding area Git calls the **staging
area** - think of it as packing a box with the things you want in your next snapshot. Notice `hello.txt`
flipped from "Untracked" to "Changes to be committed." It's *in the box*, but the box isn't sealed yet -
nothing is saved to history at this point.

You might wonder why there's a separate "add" step instead of Git just snapshotting everything. Short
answer: it lets you choose *exactly* what goes into each snapshot - useful once projects have many files.
For now, "`add` puts a file in the box" is all you need. The next guide explains the staging area in
depth.

## `git commit` - seal the snapshot

```console
$ git commit -m "Add hello.txt"
[main (root-commit) 0a3f9c2] Add hello.txt
 1 file changed, 1 insertion(+)
 create mode 100644 hello.txt
```
*What just happened:* `git commit` sealed the box into a permanent snapshot. The `-m` flag attaches a
**message** - your note describing the save ("Add hello.txt"). That's it: **you just made your first
commit.** A few things in the output worth reading:

- `(root-commit)` means this is the very first commit in the repo - the root of all history.
- `0a3f9c2` is the commit's unique ID (its *hash*). Yours will differ; every commit gets its own.
- `1 file changed, 1 insertion(+)` is Git summarizing what's new compared to before (one new line).

📝 **Terminology.** A **commit** is one saved snapshot, with its message, ID, and a record of what came
before it. "Commit your work" means "take a snapshot now."

⚠️ **Gotcha.** If you run `git commit` *without* `-m "..."`, Git opens a text editor to make you write a
message - and on many systems that editor is **Vim**, which is notoriously hard to exit if you've never
met it. If you get stranded in it, type `:q!` and press Enter to back out without committing, then run the
command again *with* `-m`. (Also in the Phase 4 cheat-card.)

## Do it again - the loop you'll repeat forever

Here's the whole rhythm of using Git day to day. Change a file, then add and commit. Let's add a second
line:
```console
$ echo "Version control is just save-points." >> hello.txt
$ git add hello.txt
$ git commit -m "Add a second line"
[main 7b1e4d8] Add a second line
 1 file changed, 1 insertion(+)
```
*What just happened:* `>>` *appends* a line to the file (a single `>` would overwrite it). Then the same
two moves - `add` to stage, `commit` to seal. No `(root-commit)` this time, because this snapshot has a
parent: your first commit. That's the loop, forever:

```mermaid
flowchart LR
  E(edit a file<br/>do the work) -->|git add| S(stage<br/>pack the box)
  S -->|git commit| C(snapshot<br/>seal it)
  C -->|repeat| E
```

## `git log` - see your history

```console
$ git log --oneline
7b1e4d8 (HEAD -> main) Add a second line
0a3f9c2 Add hello.txt
```
*What just happened:* `git log` lists your commits, newest first - your two snapshots, each with its short
ID and message. `--oneline` keeps it to one tidy line each (plain `git log` shows a fuller, screen-filling
version; if it ever traps you in a scrolling pager, press `q` to quit). This list is your project's memory.
Every commit you make joins it.

💡 **Key point.** You now have a complete, private version-controlled project. You can keep working like
this forever without ever touching the internet - `edit → add → commit`, and `git log` to look back.
GitHub, next, is only about putting a copy of this online.

## Recap

1. **`git init`** turns a folder into a repo (creates the hidden `.git`).
2. **`git status`** shows you what's going on - run it constantly; it changes nothing.
3. **`git add <file>`** puts a file in the box (staging) for the next snapshot.
4. **`git commit -m "message"`** seals the box into a permanent snapshot.
5. **`git log --oneline`** shows your history of snapshots.

That `edit → add → commit` loop is the heart of Git. Everything else builds on it. Next, let's get this
project onto GitHub so it's backed up and shareable.

Watch it animated: [staging changes](/explainers/Staging.dc.html) and [making your first commits](/explainers/Commits.dc.html)

## Try it yourself

Run commands and watch the history graph build - `commit -m "first"`, `branch dev`, `checkout dev`, `commit -m "work"`, `checkout main`, `merge dev`:

```playground-git
```

## Practice

```exercise
[
  {
    "type": "predict",
    "task": "You run `git init` in an empty folder, then immediately run `git status`. What does it print?",
    "accept": ["nothing to commit", "/nothing to commit, working tree clean/i"],
    "hint": "A brand-new repo has no changes yet - status has nothing to report."
  },
  {
    "type": "predict",
    "task": "You edit a tracked file but never run `git add`. What does `git commit -m \"update\"` do?",
    "accept": ["nothing", "/nothing to commit/i", "fails", "/it fails/i", "does nothing"],
    "hint": "Commit only seals what's staged. An edited-but-unstaged file isn't in the box yet."
  },
  {
    "type": "task",
    "task": "Create a new folder, turn it into a Git repo, add one file, and make your first commit - from memory, no looking back at the guide.",
    "reveal": "mkdir my-project && cd my-project, then git init, create a file, git add <file>, then git commit -m \"first commit\".",
    "checklist": ["Ran git init before anything else", "Checked git status before staging", "Wrote a real commit message, not \"update\"", "Confirmed it worked with git log"]
  }
]
```


---

# Putting It on GitHub - remote, push, and clone

Your project lives on your computer with a full history. That's already real version control. But it's
only in one place - if your laptop dies, so does everything. And nobody else can see it. **GitHub fixes
both:** it keeps an online copy of your project, as a backup and as something you can share or collaborate
on.

This phase has one genuinely fiddly part - proving to GitHub that you're you. We'll go slow there, because
it's where almost everyone gets stuck, and it's not your fault: GitHub changed how this works a few years
ago and most old tutorials are now wrong.

## First, the picture

Remember from Phase 1: Git is the tool on your computer; GitHub is a website that hosts a copy. So you'll
have *two* copies of the project - yours, and GitHub's - and you'll **push** your commits up to keep
GitHub's copy in sync with yours.

```mermaid
flowchart LR
  L(your computer<br/>hello-git repo<br/>your commits) -->|git push| G(GitHub<br/>hello-git repo<br/>the copy)
```

📝 **Terminology.** That online copy is called a **remote** - a copy of your repo that lives somewhere
else. By tradition, the main remote is nicknamed **origin**. So "push to origin" just means "send my
commits to the GitHub copy."

## Step 1: Make a GitHub account and an empty repo

1. Sign up at [github.com](https://github.com) if you don't have an account. Use the **same email** you
   gave Git in Phase 1.
2. Click the **+** in the top-right → **New repository**.
3. Name it `hello-git` (matching your folder keeps things clear).
4. Leave it **empty** - do *not* check "Add a README," "Add .gitignore," or a license. (Those create a
   commit on GitHub's side, which would clash with the history you already have locally. Starting empty
   avoids a confusing first-day conflict.)
5. Click **Create repository.**

GitHub now shows you a setup page with several commands. The section you want is **"…or push an existing
repository from the command line."** It contains your repo's address - a URL like
`https://github.com/ada/hello-git.git`. Keep that page open.

## Step 2: Connect your local repo to GitHub

Back in your terminal, inside the `hello-git` folder, tell Git the address of the remote:
```console
$ git remote add origin https://github.com/ada/hello-git.git
```
*What just happened:* Nothing printed - that's fine. You saved GitHub's URL under the nickname `origin`,
so from now on you can say "origin" instead of typing the whole address. Confirm it stuck:
```console
$ git remote -v
origin  https://github.com/ada/hello-git.git (fetch)
origin  https://github.com/ada/hello-git.git (push)
```
*What just happened:* Git listed your remotes. `origin` now points at your GitHub repo for both
downloading (`fetch`) and uploading (`push`). The connection exists; nothing has been sent yet.

## Step 3: The authentication part (read this slowly)

When you push, GitHub needs to confirm you're allowed to. **Here's the thing nobody tells beginners: you
cannot type your GitHub website password here.** GitHub removed password-over-the-command-line in 2021 -
try it and you'll get an error that literally says *"Support for password authentication was removed."*
Many older tutorials still tell you to type your password; they're out of date.

There are a few legitimate ways to authenticate. For someone starting out, the smoothest is the **GitHub
CLI**, a small official tool that handles the whole handshake through your browser. Install it from
[cli.github.com](https://cli.github.com), then run:
```console
$ gh auth login
? Where do you use GitHub? GitHub.com
? What is your preferred protocol for Git operations? HTTPS
? Authenticate Git with your GitHub credentials? Yes
? How would you like to authenticate GitHub CLI? Login with a web browser

! First copy your one-time code: ABCD-1234
Press Enter to open github.com in your browser...
✓ Authentication complete.
✓ Configured git protocol
```
*What just happened:* You proved who you are by signing in through the browser - the same way you log into
any website - and `gh` saved that approval on your computer. Git will now use it automatically every time
you push. You only do this once per machine.

> **Other paths, briefly.** On Windows, the Git installer bundles a "credential manager" that pops up a
> browser sign-in the *first* time you push - so you may not need `gh` at all; just try Step 4 and follow
> the prompt. Two more options you'll hear about: a **Personal Access Token** (a long password-like string
> you generate in GitHub's settings and paste when asked) and **SSH keys** (a more permanent setup). All
> of them work; `gh auth login` is least painful on day one - SSH keys are worth setting up eventually, a
> topic for a later guide.

## Step 4: Push

Now send your commits up:
```console
$ git push -u origin main
Enumerating objects: 6, done.
Counting objects: 100% (6/6), done.
Writing objects: 100% (6/6), 512 bytes | 512.00 KiB/s, done.
Total 6 (delta 0), reused 0 (delta 0)
To https://github.com/ada/hello-git.git
 * [new branch]      main -> main
branch 'main' set up to track 'origin/main'.
```
*What just happened:* Git uploaded your commits to GitHub. Reading the key lines: `[new branch] main ->
main` means GitHub now has your `main` and its full history, and the last line means your local `main` is
now *linked* to GitHub's - that's what `-u` did. Because of that link, from now on you can just type
`git push` (no extra words) to send future commits.

**Go look.** Refresh your GitHub repo page in the browser. There's `hello.txt`, your commit messages,
your history - the same project, now safely online. That's the whole goal of this phase, done.

## The daily loop, now with a remote

With GitHub connected, your everyday rhythm gains one step at the end:
```console
$ echo "Third line." >> hello.txt
$ git add hello.txt
$ git commit -m "Add a third line"
$ git push
```
*What just happened:* The familiar `edit → add → commit` from Phase 2, then `push` to mirror it to GitHub.
Commit as often as you like locally; push when you want the online copy caught up.

There's a partner command, `git pull`, which does the reverse - it **downloads** commits from GitHub into
your copy. You reach for it when work shows up on GitHub that you don't have yet (most often because a
teammate pushed, or you committed from another computer). The deeper mechanics of `pull` live in the
[next guide](/guides/git-explained-like-a-human); for now, "`push` sends up, `pull` brings down" is
enough.

## Cloning - getting a repo you don't have yet

The flip side of all this: when a project *already* exists on GitHub and you want it on your machine, you
**clone** it. This is how you'd download your own repo onto a second computer, or grab someone else's
project:
```console
$ git clone https://github.com/ada/hello-git.git
Cloning into 'hello-git'...
remote: Enumerating objects: 6, done.
remote: Total 6 (delta 0), reused 0 (delta 0)
Receiving objects: 100% (6/6), done.
```
*What just happened:* `git clone` created a `hello-git` folder, downloaded the entire project *and its full
history*, and even set up `origin` for you automatically. A clone is ready to go - no `init`, no `remote
add` needed.

⚠️ **Gotcha.** If a `push` ever gets rejected with `Updates were rejected ... fetch first`, it means
GitHub's copy has commits yours doesn't (you probably added that README on the website after all, or
pushed from elsewhere). Git is refusing to overwrite work you haven't seen - which is it protecting you,
not breaking. Run `git pull` to bring those commits down, then `git push` again. It's in the
[Phase 4 cheat-card](04-first-day-snags.md).

## Recap

1. A **remote** is an online copy of your repo; the main one is nicknamed **origin**.
2. **`git remote add origin <url>`** connects your local repo to a GitHub repo.
3. You **can't** use your website password on the command line - authenticate with `gh auth login` (or
   the credential-manager browser pop-up, a token, or SSH).
4. **`git push`** sends your commits up; **`git pull`** brings new ones down.
5. **`git clone <url>`** downloads an existing repo, history and all.

You can now go from an empty folder to a backed-up, shareable project online. That's the entire core
workflow. The last phase is your safety net: the small errors that ambush beginners, and the calm fix for
each.

Watch it animated: [pushing to a remote](/explainers/Remotes.dc.html)


---

# When the First Day Goes Sideways - Beginner Errors, Calmly Fixed

Every single person who learns Git hits a few of these in their first week. They look like cryptic
failures; they're really just Git telling you one specific thing is missing or out of place. None of them
mean you broke anything. Find your error below, breathe, apply the fix, and read the short *why* so it
won't rattle you next time.

## The cheat-card

> **Match the message you got to the row, then read the section under it.**

| The error you're seeing | The calm fix |
|---|---|
| `git: command not found` / `'git' is not recognized` | Git isn't installed or the terminal can't find it - reopen the terminal, or reinstall (§1) |
| `Author identity unknown` / `Please tell me who you are` | Set your name and email once (§2) |
| `fatal: not a git repository` | You're not inside a repo folder - `cd` into it, or `git init` (§3) |
| `Support for password authentication was removed` / `Authentication failed` | Don't use your password - authenticate properly (§4) |
| `Updates were rejected ... fetch first` | GitHub has commits you don't - `git pull`, then push (§5) |
| Stuck in a weird full-screen editor after `git commit` | You're in Vim - type `:q!` then Enter to escape (§6) |
| `warning: LF will be replaced by CRLF` (Windows) | Harmless line-ending notice - you can ignore it (§7) |
| Committed the wrong file (and haven't pushed) | Undo the last commit but keep your work (§8) |

---

## 1. `git: command not found`

**What you'll see.** You type `git --version` and get `command not found` (macOS/Linux) or `'git' is not
recognized as an internal or external command` (Windows).

**What it means.** Your terminal can't find the Git program - either it isn't installed, or it was
installed after this terminal window opened and it doesn't know about it yet.

**The calm fix.** First, **close the terminal completely and open a new one** - this alone fixes it
surprisingly often. Still failing? Reinstall Git from [Phase 1](01-what-is-version-control.md), and on
Windows use **Git Bash** (which comes with Git) rather than the default Command Prompt.

## 2. `Author identity unknown`

**What you'll see.**
```console
$ git commit -m "My first commit"
Author identity unknown

*** Please tell me who you are.

Run

  git config --global user.email "you@example.com"
  git config --global user.name "Your Name"

fatal: unable to auto-detect email address
```

**What it means.** Every commit is signed with a name and email, and you haven't told Git yours yet
(this is the Phase 1 setup step) - Git won't take the snapshot until you do.

**The calm fix.** Run the two lines Git is literally suggesting, with your details, then commit again:
```console
$ git config --global user.name "Ada Lovelace"
$ git config --global user.email "ada@example.com"
$ git commit -m "My first commit"
```
*What just happened:* You set your identity once, for every project on this machine, and the commit that
failed now succeeds. Your staged work was never lost - it waited in the box the whole time.

## 3. `fatal: not a git repository`

**What you'll see.** Almost any Git command answers with `fatal: not a git repository (or any of the
parent directories): .git`.

**What it means.** You're standing in a folder Git isn't tracking - no `.git` in it or any folder above
it. Usually you opened the terminal somewhere else, or never ran `git init` here.

**The calm fix.** If the repo exists, move into it. If this is a brand-new project, initialize it:
```console
$ cd path/to/your/project    # go into the repo, OR
$ git init                   # if this folder should be a new repo
```
*What just happened:* Git commands only work *inside* a repository. `cd` puts you in an existing one;
`git init` makes the current folder into one. Run `git status` afterward to confirm.

## 4. `Authentication failed` when pushing

**What you'll see.**
```console
remote: Support for password authentication was removed on August 13, 2021.
fatal: Authentication failed for 'https://github.com/ada/hello-git.git/'
```

**What it means.** You tried to push and either entered your GitHub website password (no longer works on
the command line) or haven't set up authentication at all. This is the single most common first-push
wall - old tutorials still tell people to type their password.

**The calm fix.** Authenticate the modern way. The smoothest is the GitHub CLI:
```console
$ gh auth login
```
Follow the browser sign-in (full walkthrough in [Phase 3, Step 3](03-putting-it-on-github.md)), then push
again. On Windows, retrying the push may pop up a browser sign-in from the bundled credential manager -
let it. A Personal Access Token or SSH key also work; you only need one.

## 5. `Updates were rejected (fetch first)`

**What you'll see.**
```console
$ git push
 ! [rejected]        main -> main (fetch first)
error: failed to push some refs to 'https://github.com/ada/hello-git.git'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally.
```

**What it means.** GitHub's copy has at least one commit your computer doesn't - often because you
checked "Add a README" when creating the repo, or pushed from another machine. Git refuses to overwrite
history you haven't seen. **This is a safety feature, not a failure.**

**The calm fix.** Bring GitHub's commits down, then push:
```console
$ git pull
$ git push
```
*What just happened:* `git pull` merged the missing commit(s) into your copy so both sides agree, and the
push then succeeds. (If `pull` asks you to pick a merge strategy or drops you into an editor, the
[next guide](/guides/git-explained-like-a-human) covers it - for now, accepting the default is fine.)

## 6. Trapped in a full-screen editor after `git commit`

**What you'll see.** You ran `git commit` with no `-m`, and your terminal filled with a cryptic text
screen showing lines starting with `#`, and nothing you type seems to work normally.

**What it means.** Git opened an editor - usually **Vim** - for you to type a commit message, and Vim
doesn't behave like a normal text box. It's not broken; it just has its own rules, and nobody warned you.

**The calm fix.** To leave *without* committing: press `Esc`, then type `:q!` and press Enter.
```text
   Esc        ← make sure you're not in "typing" mode
   :q!        ← type these three characters
   Enter      ← and press Enter - you're out
```
Then run the command again *with* a message to skip the editor entirely:
```console
$ git commit -m "Your message here"
```

## 7. `warning: LF will be replaced by CRLF` (Windows)

**What you'll see.** On Windows, `git add` prints `warning: LF will be replaced by CRLF in hello.txt`.

**What it means.** Windows and macOS/Linux mark the end of a line of text differently, and Git is just
*telling you* it's smoothing that over. It's a **warning, not an error** - your file is fine and your
commit will work.

**The calm fix.** Nothing required - safe to ignore.

## 8. "I committed the wrong file" (and haven't pushed yet)

**What you'll see.** No error - just the sinking realization that your last commit included something it
shouldn't have (a giant file, a password, the wrong thing entirely), and you haven't pushed it anywhere
yet.

**What it means.** The commit is only on your machine, so it's easy to take back. You want to undo the
*commit* while keeping your *files* exactly as they are, so you can re-stage and commit correctly.

**The calm fix** (only for a commit you have **not** pushed):
```console
$ git reset --soft HEAD~1
```
*What just happened:* This rewound the last commit, putting all of its changes back into the staging box,
untouched - as if you'd never hit commit. Remove what shouldn't be there (`git restore --staged <file>`
takes a file out of the box) and commit again. To stop a file from ever being committed, list its name in
a `.gitignore` file.

⚠️ **One caution.** That `--soft` form keeps your work safe. Its cousin `git reset --hard` *deletes*
changes - don't reach for that one while you're still learning. And this trick is for commits that exist
only on your computer; undoing something already *pushed* is a more careful operation covered in a later
guide.

---

## You made it through the first day

You installed Git, made a repository, took your first snapshots, put them on GitHub, and learned to read
errors instead of fearing them. That's the hardest part - the cold start - and it's behind you now. From
here, the same `edit → add → commit → push` loop carries you a very long way.

**Where to go next.** You can now *do* the everyday moves. The natural next step is understanding what Git
is doing underneath them - why branches aren't scary, what HEAD means, how to fix the bigger "oh no"
moments calmly. That's the next guide:
**[Git, Explained Like You're a Human](/guides/git-explained-like-a-human)**.