The daily loop

1 · Why branches exist

Imagine four people editing the same document at once, each saving over the top of the others. That's a shared project without branches.

A branch is a private lane. You take a copy of main, work in it for however long you need, and main stays exactly as it was for everyone else. When your work is finished and reviewed, it gets folded back in. If it turns out to be a bad idea, you throw the branch away and nothing was ever disturbed.

2 · Making and moving between branches

Before branching, make sure you're starting from a current copy of main. Branching off a stale main is one of the most common self-inflicted wounds.

$ git switch main
$ git pull
Updating 4b2c1e0..9df8a31  Fast-forward

# -c creates the branch and moves you onto it
$ git switch -c add-search-box
Switched to a new branch 'add-search-box'

Naming branches

No rule, but conventions help. Most teams use a short prefix and a hyphenated description: fix/login-redirect, feat/csv-export, docs/api-examples. If your team tracks work in issues, including the number is a kindness: fix/312-login-redirect.

3 · Commits worth reading

A commit message is a note to a future stranger, and that stranger is usually you. The gold standard is simple: finish the sentence "if applied, this commit will…"

For anything non-obvious, add a body. The subject line says what; the body says why, which is the part that can't be recovered from the code.

$ git commit
# opens your editor:

Debounce the search input by 300ms

Every keystroke was firing a request, so a five-letter query
meant five round trips and visible flicker as results raced
each other. 300ms tested as the point where it feels instant
but no longer stutters.

Closes #312

Writing Closes #312 is not decoration — GitHub reads it, and when this commit reaches main it will close issue 312 automatically and link the two together forever. Fixes and Resolves work the same way.

Staging selectively

You don't have to commit everything you've touched. A few useful forms:

$ git add src/search.js src/search.css
# just these two files

$ git add -p
# walk through each chunk of change and answer y/n —
# the best habit in this entire guide

$ git restore --staged src/search.css
# changed your mind — unstage it (the edit itself is untouched)

git add -p deserves a moment. It shows you every chunk of every change and asks whether you want it in this commit. Beyond producing tidier history, it forces you to re-read your own work before it goes anywhere — and it catches an astonishing number of stray debug lines.

4 · Reading a diff

A diff is the before-and-after of a change, and it's the format you'll spend most of your review time in. It looks cryptic once and then never again.

diff --git a/src/search.js b/src/search.js
@@ -12,7 +12,9 @@ function handleInput(event) {
   const query = event.target.value;
-  fetchResults(query);
+  clearTimeout(pending);
+  pending = setTimeout(() => fetchResults(query), 300);
 }

• − lines were removed, + lines were added. A "modified" line is shown as one of each.
• Lines with no marker are unchanged context, included so you can see where you are.
• @@ -12,7 +12,9 @@ means: this chunk starts at line 12 and covered 7 lines before, 9 after. You can safely ignore it most of the time.

$ git diff
# edits you haven't staged yet
$ git diff --staged
# what's about to go into your next commit
$ git diff main...HEAD
# everything your branch changes — the same view your reviewer sees

On GitHub, the same information appears under the Files changed tab of any pull request, in colour, with room to leave a comment on any individual line.

5 · Opening a pull request

Despite the name, a pull request isn't a request to pull anything. It's a proposal — "here are my commits, please look at them and merge them into main" — wrapped in a discussion thread, a diff view, and (usually) automated checks.

1. Push your branch

   first push of a new branch

   $ git push -u origin add-search-box
   remote: Create a pull request for 'add-search-box' on GitHub by visiting:
   remote:   https://github.com/acme/site/pull/new/add-search-box
   

   -u links your local branch to the one on GitHub, so from then on plain git push and git pull know what you mean. You only need it the first time.

2. Open the PR

   Follow the link Git printed, or use the banner GitHub shows on the repo page. Check the two branches at the top: you're merging add-search-box into main. Getting these the wrong way round is a rite of passage.

   Prefer the terminal? gh pr create --web does the same in one step.

3. Write a description someone can act on

   The person reviewing has no idea what you've been thinking for the last two hours. Three short headings cover almost every case:

   pull request description

   ## What
   Debounces the search input so it only fires a request 300ms
   after the user stops typing.
   
   ## Why
   Every keystroke was hitting the API. Closes #312.
   
   ## How to check it
   Open /search, type quickly, watch the network tab — you should
   see one request, not eight.
   

   If the repo has a template, GitHub pre-fills this box for you. Fill it in rather than deleting it.

4. Open it as a draft if it isn't ready

   The Create pull request button has a dropdown with Draft pull request. A draft can't be merged and doesn't ping reviewers, but it does run the automated checks and gives people a place to look. Ideal for "here's my direction, sanity-check me before I go further".

6 · Merging, and the three buttons

Once the PR is approved and the checks are green, someone presses merge. GitHub offers three ways to do it, and repos usually enforce one. Knowing the difference makes the button meaningful rather than mysterious.

7 · Cleaning up and staying in sync

After the merge, tidy up. GitHub usually offers a Delete branch button on the merged PR — take it. The commits are safely in main, and the branch has served its purpose. Then, locally:

$ git switch main
$ git pull
# now your main includes your merged work, and everyone else's

$ git branch -d add-search-box
Deleted branch add-search-box (was 8f21b0c).

Long-running branches drift

If your branch lives more than a day or two, main will move underneath it. Pull those changes in periodically rather than discovering all of them at merge time:

$ git switch add-search-box
$ git fetch origin
$ git merge origin/main

git fetch downloads what's new without changing any of your files — it's always safe to run. git merge is the step that actually applies it. (git pull is simply those two commands in one.) If this produces a conflict, that's normal and part 3 walks through resolving one.

8 · When it goes sideways

Four situations that will happen in your first month, and the one command that fixes each. Nothing here is dangerous.