Git Fundamentals: Build a Clean, Recoverable History

The staging area lets you craft exactly what goes into each commit. Here you create a project folder, turn it into a repository, add two files, and commit them. git init creates the hidden .git directory that stores the entire history, delete it and the folder becomes plain files again, which makes experimenting risk-free.

For this lab, break that one-liner into explicit steps so you can see each area change state. First create the project and a couple of files:

CREATE THE PROJECT

mkdir lab-notes && cd lab-notes
echo "# Lab Notes" > README.md
echo "passwords.txt" > .gitignore
git init

The .gitignore file above tells Git to never track passwords.txt, a small habit worth building early, because committing a secret is one of the classic mistakes covered in Troubleshooting. Now check the repository state:

INSPECT STATUS BEFORE STAGING

git status

"Untracked" means Git sees the files but has never been told to record them. Stage them, then commit. In this lab git add . stages everything in the folder, which is safe because you created exactly two files; in real projects prefer staging files explicitly (git add README.md config.yml) or interactively (git add -p), so an unrelated half-finished edit never sneaks into the commit:

STAGE THE FILES

git add .

Before committing, review the draft, this ten-second habit catches staging mistakes more reliably than any other:

REVIEW WHAT IS STAGED

git diff --cached --stat

Only the two intended files appear. If anything else showed up here, unstage it with git restore --staged <file> before continuing. Now freeze the draft into history:

COMMIT

git commit -m "Initial commit: README and .gitignore"

The output confirms the commit hash (yours will differ), the branch, and exactly what was recorded. Read the message like a changelog entry: short imperative subject of about 50 characters ("Add", "Fix", "Remove", not "Added"), then specifics if needed. If you omit -m, Git opens your configured editor so you can write a subject plus a longer body; pressuring yourself into one-liners is not the goal, clarity for a future reader (often you, in six months) is.

Confirm the commit exists where you expect it:

CONFIRM THE FIRST COMMIT

git log --oneline

Exactly one commit, and HEAD -> main confirms you are on the default branch pointing at it.

How to verify: run git status again, it should report "nothing to commit, working tree clean". If it still lists untracked files, you staged before creating them; run git add . and commit again. Also confirm the ignore rule worked: touch passwords.txt && git status should show a clean tree with no mention of the file, if passwords.txt appears as untracked, your .gitignore has a typo. Remember that .gitignore only ignores files that are not already tracked, so the rule must exist before the file ever gets added.

A branch is a movable pointer to a commit. Working on a branch means your half-finished experiment never touches main, which should always stay in a state you could show someone. git switch -c creates the branch and moves you onto it in one command (the older spelling is git checkout -b).

In this lab the "feature" is a notes file, the mechanics are identical to real code. Create the branch first and confirm where you are:

CREATE AND SWITCH TO A FEATURE BRANCH

git switch -c feature/login
git branch --show-current

Now make the change and commit it. The -a flag stages modifications to files Git already tracks, so you can skip a separate git add, but note it does not pick up brand-new files, which is why the file below is created before the commit, and staged explicitly first:

MAKE A CHANGE ON THE BRANCH

echo "- Draft: login flow notes" >> login-notes.md
git add login-notes.md
git commit -m "Add draft login flow notes"

Note the branch name in the output brackets, the commit landed on feature/login, not main. See both pointers at once with:

LIST ALL BRANCHES WITH THEIR TIPS

git branch -vv

The * marks the branch you are on; each line shows the branch's tip commit. As for naming: short, lowercase, hyphenated, and prefixed by intent, feature/..., fix/..., docs/..., so a glance at git branch reads like a to-do list. Avoid spaces (they complicate every command that takes a branch name) and avoid names like final or new, which say nothing after a week.

Prove the isolation is real: switch back to main and the new file disappears from the working tree, because that commit only exists on feature/login.

SWITCH BACK AND CHECK

git switch main
ls

Switch back to the feature branch before continuing. The handy shortcut git switch - jumps to whichever branch you were on last, which saves real typing when you are toggling between two branches:

git switch feature/login
ls

The file is back the instant you return, nothing was copied or restored from a backup; the file's presence simply reflects which commit HEAD points at. That disappearing-and-reappearing act is the whole point of branching: the experiment exists in parallel without touching main.

Common mistake: making commits on main because you forgot to create the branch first. Get in the habit of running git branch --show-current (or glancing at your shell prompt) before every commit. If you do slip, create the branch now, it points at the commit you just made, then reset main back one commit.

A remote is a named pointer to a copy of the repository on another server. The conventional name is origin. Create an empty repository on GitHub first (do not initialize it with a README, an existing commit there would create a divergent history and your first push would be rejected), then link it and push your branch.

The GitHub side takes about a minute: sign in, click the + menu → New repository, set the name to app, choose Public or Private, and leave every checkbox (Add a README, .gitignore, license) unticked. Click Create repository. GitHub then shows a "Quick setup" page with your remote URL in two flavors: an SSH URL ([email protected]:tyfsadik/app.git) and an HTTPS URL (https://github.com/tyfsadik/app.git). This lab uses SSH because it authenticates with a key and never asks for a password; HTTPS works identically for every Git command and simply prompts for credentials instead, you can switch flavors later with git remote set-url without redoing anything else.

The -u (short for --set-upstream) flag links your local branch to the remote one so that future git push and git pull need no arguments. You only do it once per branch. A full push transcript looks like this:

Confirm the remote is registered correctly:

VERIFY REMOTE CONFIGURATION

git remote -v

Two lines appear because fetch and push can technically point at different URLs; in practice they are always the same. Now confirm the upstream link that -u created, the branch.<name>.remote and branch.<name>.merge entries it writes into .git/config are the entire magic that makes a bare git push work afterwards:

CONFIRM THE UPSTREAM TRACKING LINK

git branch -vv

The bracketed [origin/feature/login] next to your current branch is the upstream: your local branch knows its remote counterpart, so plain git push, git pull, and status messages like "up to date with 'origin/feature/login'" all work with no arguments. Without it, Git prints "no upstream branch" and makes you type the remote and branch name every time.

How to verify: the branch should also appear on the GitHub web page for the repository. If the push fails with a permission error, your SSH key is not set up, see Troubleshooting. Also push main while you are here, so both branches exist remotely:

git push -u origin main

Before merging, learn the two inspection commands you will use daily. git log shows the commit chain; git diff shows line-level changes. Together they answer "what happened" and "what is about to happen", run them before every commit and every merge until it becomes reflex.

READ THE HISTORY

git log --oneline --graph --all

The graph shows both commits in a straight line because main has not moved since you branched. HEAD marks which commit your working tree is based on.

git diff has three everyday forms worth memorizing, because they answer three different questions. git diff alone shows changes in the working tree that are not yet staged; git diff --cached shows what is staged and waiting to be committed; and git diff main feature/login compares two commits, here, everything the feature branch would add to main. Right now the first two are empty and the third shows your one new line. For the contents of a single commit, git show 7c2e4b8 prints its message plus its full patch, the fastest way to answer "what exactly did that commit do?"

Now rehearse the most common recovery: you staged something that should not be committed. Stage a stray file, then unstage it without losing the file itself:

UNSTAGE WITHOUT LOSING WORK

echo "scratch" > scratch.tmp
git add scratch.tmp
git restore --staged scratch.tmp
git status --short

Prove the staging area is empty again before taking the transcript at its word, git diff --cached should print nothing at all:

git diff --cached --stat

The ?? means the file is untracked again, back out of staging, but still on disk. (git restore --staged is the modern spelling; older tutorials use git reset HEAD <file>, which does the same thing.) Delete the scratch file when done. Warning: plain git restore <file> without --staged discards uncommitted changes in the working tree permanently, that is the destructive twin of this command. If you are ever unsure which of the two forms you are about to run, run git status first and read its hints: the "Changes to be committed" section tells you exactly what to unstage, and its parenthetical suggestions literally spell out the recovery command for your situation.

Branching is only half the story; the change has to come home. Switch to main and merge. Because main never moved, Git performs a fast-forward: it simply slides the main pointer forward to the feature commit. No merge commit, no conflict.

First, one last review. The three-dot form git diff main...feature/login (note the three dots) shows only what the feature branch introduces since it diverged, the same set of changes the merge is about to bring into main:

PRE-MERGE REVIEW

git diff main...feature/login --stat

One file, one line, exactly what you intended, and nothing from anyone else's work. If this listing ever surprises you, stop and investigate before merging; after a fast-forward there is no merge commit to mark the event, so the pre-merge check is your audit trail.

MERGE INTO MAIN

git switch main
git merge feature/login

With the merge done, the feature branch has served its purpose. Delete it locally and on the remote to keep the branch list clean, deleting a branch deletes only the pointer, never the commits, because they are now reachable from main:

CLEAN UP THE MERGED BRANCH

git branch -d feature/login
git push origin --delete feature/login
git push

git branch -d (lowercase) refuses to delete a branch that is not fully merged, a built-in safety check. The uppercase -D forces deletion and will silently discard unmerged work, so reach for it only when you are certain.

One loose end remains: your local list no longer shows the branch, but the remote-tracking copy (origin/feature/login) lingers in git branch -a output until Git prunes it. Fetch with --prune to tidy it immediately rather than waiting for a later fetch to do it by accident:

PRUNE STALE REMOTE BRANCHES

git fetch --prune origin
git branch -a

Only main remains, locally and remotely, the feature branch is gone everywhere, while its commit lives on as part of main's history.

How to verify: ls should now show login-notes.md on main, and git log --oneline on main should include the "Add draft login flow notes" commit. If the merge instead reported a conflict, both branches changed the same lines, that scenario has its own lab, Merge Conflicts.

Collaboration means the remote moves without you: a teammate pushes, or you edit a file in the GitHub web UI. git pull fetches those commits and merges them into your current branch. Simulate it by fetching first, git fetch downloads remote state without touching your working tree, which makes it the safe way to look before you leap:

FETCH, INSPECT, THEN PULL

git fetch origin
git status
git pull

Nothing happened, and that is the lesson: git fetch downloaded the remote's state into your local copy (origin/main moved or confirmed) but touched neither your working tree nor your branch. It is a purely read-only look. git pull is simply git fetch followed by git merge into your current branch, "Already up to date" means the merge half had nothing to do.

Now make the remote actually move. On the GitHub web page for your repository, click README.md, then the pencil (Edit) icon, add a line such as Status: in progress, and press Commit changes with the message "Add status line to README". That commit exists on GitHub but not on your laptop, precisely the situation a teammate's push would create.

FETCH AGAIN AND READ THE DRIFT

git fetch origin
git status

The fetch output shows origin/main advancing from 7c2e4b8 to a1b2c3d (hashes abbreviated), and status translates that into English: behind by 1, safe to fast-forward. Your working tree is untouched, you could keep working, or even decide to handle it later. When ready, pull:

git pull

The README on disk now contains the status line, and git status reports "up to date with 'origin/main'" again. No editor opened, no conflict appeared, because your local main had no commits of its own, the merge was a pure fast-forward. The day it is not, you are in merge-conflict territory, which has its own lab.

Make git pull the first command of every work session; merging a small drift daily is painless, merging a month of drift is not. Some teams prefer git pull --rebase, which replays your unpushed commits on top of the fetched ones to keep history linear; it rewrites your local commits, so agree on it with your team before adopting it. The fetch-first discipline above applies either way.

Common mistake: pushing before pulling. If a teammate pushed first, your push is rejected as "non-fast-forward". The fix is simply git pull (resolve any conflicts if they appear), then push again, covered in Troubleshooting.

Two seconds after committing, you notice a typo in the message, or that a file never got staged. git commit --amend replaces the tip commit with a new one carrying the fix. Why this is safe here but dangerous later: amending does not edit the old commit, it creates a brand-new commit hash and abandons the old one. Unpushed, no one else has seen the old hash, so replacing it costs nothing. Once the commit is pushed, teammates may have built on it, and replacing it rewrites shared history, which is why the one rule of amending is only amend commits that have not left your machine.

Rehearse it with a deliberately mistyped message. Add another line and commit it, typo and all:

COMMIT WITH A TYPO (ON PURPOSE)

echo "- TODO: MFA notes" >> login-notes.md
git add login-notes.md
git commit -m "Add draft login flow ntoes"

Now fix the message. Without staged changes, --amend rewrites only the message:

AMEND THE MESSAGE

git commit --amend -m "Add draft login flow notes"

Compare the two outputs: the message is fixed, but the hash changed from 9f3d21a to 4e8c1a2. That hash change is the rewrite, the typo'd commit no longer exists anywhere, which is exactly why amending a pushed commit breaks everyone who pulled it. (If you want to fold a forgotten file into the commit instead, stage it and run git commit --amend --no-edit; the --no-edit keeps the existing message.)

VERIFY THE AMEND

git log --oneline -n 2

One commit per change, correct message, no trace of the typo.

Common mistake: amending a commit that was already pushed, then force-pushing to make it accepted. On any branch someone else might use, resist, use a follow-up commit instead. If it truly is your own branch and you must, git push --force-with-lease is the only acceptable force: it refuses to overwrite if the remote has moved since your last fetch, which plain --force does not check.

The reflog is Git's flight recorder: a local journal that records every movement of HEAD, commits, resets, pulls, branch switches, whether or not a branch still points at the commits involved. Why it matters: most "I lost my work" moments in Git are actually "no branch points at my work" moments, and the reflog almost always knows where it went. This is the skill that turns Git from an anxious tool into a confident one.

First, look at the journal. The newest entry is HEAD@{0}:

READ THE FLIGHT RECORDER

git reflog

Every event from this lab is there, including the abandoned typo'd commit 9f3d21a, which no branch references yet is still retrievable. Now simulate the classic accident: a reset --hard that appears to destroy your last commit. (A reset moves the branch pointer backward; --hard also rewrites the working tree to match. It never deletes commits, it just stops pointing at them.)

SIMULATE LOSING THE LAST COMMIT

git reset --hard HEAD~1
git log --oneline -n 1

The MFA-notes commit is gone from log, log only walks reachable history, and nothing points at 4e8c1a2 anymore. But the reflog saw the reset happen and still lists the commit. Find the entry for it and restore it by resetting back to that hash:

RESCUE THE COMMIT VIA REFLOG

git reflog -n 3
git reset --hard 4e8c1a2
git log --oneline -n 2

git log --oneline -n 2 once again shows 4e8c1a2 at the tip, the commit was never lost, only orphaned, and the reflog remembered it. For a gentler rescue that keeps your current branch untouched, you can instead hang the commit on a new branch: git switch -c rescue 4e8c1a2, then merge or cherry-pick from there.

Common mistake: assuming the reflog follows you to other machines. It is strictly local, a fresh clone has a nearly empty one, so recovery via reflog works only on the machine where the work happened (entries also expire after roughly 90 days by default). Also, do not confuse "deleted the branch" with "deleted the commits": git branch -D removes a pointer; the commits survive until garbage collection, findable exactly this way.