## Why version control matters when you’re touching code

Open Figma, click File → Show Version History, and scroll back through every save the team has ever made. That’s version control for design files. **Git is the same idea for code** — except instead of one stream of saves, every contributor can work on their own parallel timeline and merge their work back together when it’s ready.

Once you understand that one analogy, git stops being scary. The vocabulary that follows — _branch_, _commit_, _push_, _pull request_ — is just words for the same primitives Figma’s version history already uses, plus one extra primitive (the branch) for parallel work.

## GitHub setup

You’ll need three things to get started:

1. **A GitHub account.** [github.com/signup](https://github.com/signup). Pick a username you’re happy attaching your name to publicly — your commits will be tagged with it.
2. **A way to talk to GitHub from your laptop.** Most designers we know start with [GitHub Desktop](https://desktop.github.com/) — a friendly app that does the most common git operations with buttons. The terminal (`git` command-line) is more powerful, but Desktop covers 90% of what you need.
3. **An SSH key** so GitHub trusts your laptop. GitHub’s [own setup guide](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) is excellent and short. Or, if you’re using GitHub Desktop, it’ll handle the equivalent step for you.

Account on GitHub, key on your laptop. Once they recognize each other, you can clone repos and push commits.

That’s it for setup. From here on, everything happens inside _repositories_ — a fancy word for “a folder of code that has a git history attached to it.”

## Cloning a repo

When your team’s code lives on GitHub and you want a copy on your laptop to run it, you **clone** it. Cloning copies every file, plus the entire history, plus a hidden `.git/` folder that tracks everything.

In the terminal, that’s:

```
git clone github.com/your-team/your-app
cd your-app
```

In GitHub Desktop, it’s File → Clone Repository, then pick from the list.

A clone is just a copy with memory. The .git/ folder holds every prior commit so you can rewind, branch, or compare.

After cloning, you have a folder. Combine it with [Localhost 1](/content/localhost/frontend-fundamentals/index.html) and you can run it: `npm install`, `npm run dev`, browser at `localhost:3000`.

## Branches, simplified

A **branch** is a parallel timeline for work-in-progress. Every repo has a default branch — usually called `main` (or sometimes `master`). When you make a new branch off `main`, you get a private copy of every file, where your edits don’t affect anyone else’s work until you decide to merge them back.

The metaphor that clicks for most designers: think of `main` as the _Production_ file in Figma. Every team member works in their own _Draft_ file (a branch). When a draft is ready, you merge its changes into Production.

`main` is the trunk. A branch peels off, you make a couple of commits on it, then merge back. The history records the whole thing.

In practice:

- Make a branch when you’re starting any new piece of work: `git switch -c feat/hero-redesign` (or “Branch → New Branch” in Desktop).
- Stay on the branch until the work is ready to ship.
- Use a name with a prefix: `feat/`, `fix/`, `chore/`. It signals what kind of change it is.

The rule of thumb: **never commit directly to `main`.** Always branch. This protects production from a half-finished thought.

## Making a commit

A **commit** is a saved point in your branch’s history. It captures _which files changed_ and _why_ (the message you write). Good commits are small and named well; great commits are reviewable in under a minute.

The flow:

1. **Make some edits.** Save your files.
2. **Stage the changes you want to include.** Git asks “which of these edits go into the next commit?” In Desktop, you tick the files. In the terminal: `git add src/Hero.tsx`.
3. **Write a commit message.** One sentence, present tense. _“Polish hero alignment + add icon.”_ Not _“changes.”_
4. **Commit.** `git commit -m "Polish hero alignment"`, or click the big button in Desktop.

Three things in every commit: the files you ticked, a message that describes the why, and a button you press at the end.

After committing, the change lives in your branch’s history but is still only on your laptop. To send it to GitHub so others can see it, you **push**: `git push`, or click “Push origin” in Desktop.

## Pull requests

A **pull request** (PR) is a structured conversation about merging your branch into `main`. You open a PR on GitHub from your branch; teammates review the diff (a side-by-side view of what changed), leave comments, request changes, and ultimately approve. Once approved, the branch merges into `main`.

This is also where designers’ superpower kicks in. The diff isn’t just for engineers — it’s a chance to verify the implementation matches the design intent. Look at the rendered preview (most teams have a preview link per PR), check spacing, check states, leave a comment if something’s off.

The diff shows what changed. The thread shows who said what. Once it's approved, the merge button at the bottom turns green.

A good PR has:

- **A clear title.** Same energy as a commit message — describe the change, not the file paths.
- **A short description.** What changed, why, and any screenshots or recordings of the result.
- **A small scope.** PRs over ~400 lines of diff get sloppy reviews. Smaller is better.

## Try it yourself

Time to do this for real. If you cloned [`handle-playground`](https://github.com/tonkotsu-ai/handle-playground) in the previous article, it’s the perfect target — a small, public repo where you can run the whole PR loop without worrying about breaking your team’s production codebase.

1. **Fork** the repo on GitHub (the Fork button, top-right).
2. Clone _your_ fork: `git clone https://github.com/<your-username>/handle-playground.git`, then `cd handle-playground`.
3. Branch: `git switch -c chore/test-pr` (or use Desktop).
4. Change one tiny thing — fix a typo in the README, tweak a color value in the CSS.
5. Commit it with a real message.
6. Push the branch: `git push -u origin chore/test-pr`.
7. Open a PR on GitHub and write a description. The “Compare & pull request” button shows up on your fork right after you push.

The first time you do this, the loop feels enormous. By the third time, it’ll be muscle memory.

Once you’re comfortable with the loop, the next layer is the new collaborator that’s quietly become part of every modern codebase — coding agents.