Version control with git

Snapshots instead of final_v3_REAL.docx

You've probably seen a folder like this: landing-page-v2.html, landing-page-v2-edits.html, landing-page-FINAL.html. Version control fixes that mess. Git records snapshots of a whole folder over time. Each snapshot is called a commit, and it stores exactly what every file looked like at that moment, plus a short message saying why it changed.

A folder whose history git is tracking is called a repository (or "repo"). With one you can:

• see every change ever made, when, and why;
• get back any earlier version of any file;
• try risky ideas without breaking the version that works;
• share the project and combine work from several people.

Git is the program on your computer. GitHub is a website that stores copies of git repositories online and adds collaboration features on top. You can use git without GitHub, but most teams use both.

Three places a change can be

Git asks you to choose what goes into each snapshot. So a change moves through three places:

Think of packing a box to ship. The working directory is your desk, with everything spread out. git add puts chosen items in the box. git commit seals the box and writes a label on it. Things left on the desk aren't in the box, even if you changed them.

The command you'll run most is git status. It tells you which files changed, which changes are staged, and which files git isn't tracking yet. When in doubt, run it.

git init                        # start tracking this folder (once per project)
git status                      # what's changed? what's staged?
git add index.html              # stage one file
git add .                       # or stage every change in this folder
git commit -m "Add landing page"   # save the staged changes as a commit
git log --oneline               # list commits, newest first

Try it below. The landing-page folder isn't a repository yet.

staged = ["app.py"]
changed = ["app.py", "notes.txt"]
commit = [f for f in changed if f in staged]
print(commit)

Good commits

Each commit gets a unique ID (a hash), like 3f9a2c1, plus your message, your name and the time. git log --oneline shows one line per commit, newest first:

a41c9e2 Add pricing section
3f9a2c1 Shorten hero headline
0b7d115 Add landing page

Write messages that say what the commit does, as if finishing the sentence "This commit will...": Add pricing section, Fix broken signup link. "Changes" or "stuff" tells your future self nothing.

Commit small and often: one change per commit, whenever something works. Small commits are easy to understand and easy to undo.

Two more commands help you see what's going on before you commit:

• git diff shows the exact lines you've changed but not yet staged, with removed lines marked - and added lines marked +.
• git restore index.html throws away your uncommitted edits to that file. It puts back the last committed version. It's an undo button for work you haven't committed, and it's permanent: those edits are gone.

Branches: a safe place to experiment

A branch is a separate line of commits. Think of a copy of a document you scribble on, while the clean copy stays in the drawer. Every repository starts with one branch, usually called main. When you want to try something, such as a new headline or a risky redesign, you create a branch and commit there. main stays exactly as it was.

git switch -c new-headline    # create a branch and move onto it
git branch                    # list branches; * marks the one you're on
git switch main               # go back to main

(git checkout -b new-headline is the older way to write the first command. You'll see both.)

If the experiment works, the branch is merged back into main, combining its commits. On GitHub this usually happens through a pull request. That's a page showing the branch's changes, so someone can review them before they're merged. If the experiment fails, you switch back to main and delete the branch. Nothing was ever at risk.

Remotes and GitHub

A remote is a copy of the repository somewhere else, typically on GitHub. By convention the main remote is called origin.

• git clone <url> downloads a repository, with its whole history, onto your computer.
• git push sends your new commits up to the remote.
• git pull brings down commits other people pushed.

The simulator here has no remote, so git push won't work in it. On your own machine, you'd create a repository on GitHub, connect it once, and push.

Some files should never be committed: passwords and API keys, a .env file holding them, large data files, and installed packages. You list them in a file called .gitignore, and git ignores them. A public GitHub repository is visible to everyone, including bots that scan for leaked keys. The API keys lesson comes back to this.

Worked example: undo an AI assistant's edit

You ask an AI assistant to shorten the headline in index.html, and it also rewrites half the page. Git lets you see what happened and choose what to keep. Lines starting with % are what you type. The diff is trimmed to just the changed lines:

% git status
On branch main
Changes not staged for commit:
        modified:   index.html
% git diff index.html
-<h1>Rain shells built for the commute, not the catwalk</h1>
+<h1>Rain shells for the commute</h1>
-<p>Free returns for 60 days.</p>
+<p>Unbeatable deals on every jacket!</p>
% git restore index.html
% git status
On branch main
nothing to commit, working tree clean

Step by step:

1. git status shows one changed file.
2. git diff shows the headline change you wanted, plus a change you didn't: the returns promise was replaced with hype.
3. git restore puts the file back to the last commit, and git status confirms it's clean.

Then you ask again, more precisely: "change only the h1". Because you committed before the assistant started, nothing you'd saved was ever at risk.