Git, in plain English

Why this exists

Last week Josh updated a skill in a pull request, merged it into the main branch, and then ran the skill from his laptop. He got the old version. The update was live on GitHub but invisible to his local Claude Code session. This guide explains why, and what to do about it.

This pattern is everywhere on our team right now. As of today, we have feature branches sitting 47, 60, 90, and even 264 commits behind main. Anyone working on those branches is running ancient versions of every skill, every rule, every prompt, every helper script. We don't notice because the failures are silent — the old version still runs, it just runs wrong.

The fix is not technical. It's a daily habit, supported by three small Claude Code helpers we're shipping alongside this guide. By the end of this page you'll have:

• A mental model of what git actually is and why it works this way
• The vocabulary — branch, commit, push, pull, fetch, rebase, merge — explained in plain English
• A 30-second morning ritual that prevents the problem entirely
• The two-track rule for when you need a pull request and when you don't
• The four most common errors and exactly how to fix each one

Read it once. Bookmark the cheat sheet at the bottom. Run the daily ritual every morning. That's it.

The mental model

Three sentences. If you remember nothing else, remember these.

1. Your laptop has its own complete copy of every file in the repo. So does GitHub. So does every teammate. They're independent copies.
2. Nothing moves between these copies unless you explicitly tell it to. Merging a pull request on GitHub does not update your laptop. Closing your laptop does not update GitHub.
3. The job of git is to keep these copies in sync — but only when you ask. The commands you'll learn (fetch, pull, push, rebase) are how you ask.

       ┌─────────────────────┐
       │      GitHub.com     │
       │   (the shared copy) │
       │                     │
       │   main: commit X    │ ◄────── PR #221 lands here
       └──────────┬──────────┘
                  │
       ┌──────────┴──────────┐
       │                     │
   git fetch              git push
   git pull               (you send up)
   (you pull down)
       │                     │
       ▼                     │
┌───────────────┐    ┌───────────────┐    ┌───────────────┐
│  Josh's Mac   │    │  David's Mac  │    │  Doug's Mac   │
│  main: W      │    │  main: V      │    │  main: X      │
│  (3 behind)   │    │  (5 behind)   │    │  (current)    │
└───────────────┘    └───────────────┘    └───────────────┘
    

Same picture applies to feature branches. When you create feat/my-thing, you're branching off whatever your local main currently is. If your local main is 60 commits stale, your feature branch starts 60 commits stale.

The vocabulary

Plain English. Two sentences each, with an analogy. Read once, reference forever.

Your daily ritual

Every morning, before you open Claude Code, before you start a campaign, before you touch any file — run this. It is one command.

What /sync does under the hood, in case you're curious:

What if I don't have /sync yet?

If your Claude Code session doesn't recognize /sync, you're either on an older version of the repo (run git pull origin main on your local main first) or in a Claude Code session that started before the command was added. Restart Claude Code from your terminal.

What if I'm offline?

The Session Start banner that ships with this guide will fail silently if you have no internet. You can keep working — git is happy offline. Just remember to sync before you push anything up.

What about during the day?

Run /sync again any time:

• You notice someone shipped a PR you care about
• You're about to invoke a skill or rule that was recently changed
• Something seems off — an old prompt is firing, a rule isn't being respected, a script is missing
• You're returning from lunch or a meeting

The two-track rule

Not every change needs the full pull-request process. We have three tracks, calibrated to how much damage a bad change could do.

When in doubt

If you're not sure which track applies, default up — Track B is the safer choice than Track C, Track A is safer than B. The friction cost of one extra reviewer is much smaller than the cleanup cost of a bad change that landed without review.

The 3-day branch rule

Any branch you keep open for more than three days needs to be rebased on the latest main. The longer a branch lives without syncing, the harder the eventual merge becomes. Three concrete checkpoints:

• Day 3: rebase on main. /sync handles this.
• Day 14: ship it or close it. A branch that's two weeks old and unmerged is almost always either abandoned or scope-creeped — make a decision.
• 100 commits behind main: the branch is presumed abandoned. Either rebase it back to life or delete it.

Why we're relaxing some rules and tightening others

Our team is mostly GTM operators making client-context updates, not software engineers shipping features. The blanket "two reviewers for everything" rule from our original git workflow was a copy-paste from how engineering teams work — it didn't fit. The two-track model puts strict review where the risk actually lives (code) and removes friction where it doesn't (notes). Most weekly updates fall into Track C and become a single commit to main.

Your slash commands

You don't need to memorize git. We wrapped the four operations you'll do every day into Claude Code commands. Type a slash, press tab, you're done.

What about plain git commands?

You can absolutely use git fetch, git pull, git rebase, git push, git status, git log directly from your terminal. The slash commands are wrappers, not replacements. If you prefer raw git, the daily ritual is:

git fetch origin
# if on main:
git pull origin main
# if on a feature branch:
git rebase origin/main

Both paths get you to the same place.

When something goes wrong

Git's error messages are scary but the situations are usually simple. Here are the four you'll hit, in order of frequency.

<<<<<<< HEAD
my version of the line
=======
the other version of the line
>>>>>>> origin/main

# Save your work to a new branch
git branch oops-rescue
# Reset main back to where GitHub thinks it is
git reset --hard origin/main
# Switch to your rescue branch — your changes are here
git checkout oops-rescue

git reflog

git reset --hard a1b2c3d

Check your state

Three commands tell you everything you need to know about where you are, what's changed, and how far behind you are.

73d9416 feat(scheduler): multi-client cron
ac04d5c chore: bump heyreach-cli submodule
5dda048 feat(attribution-report): v2
27833c7 feat(henry-ai): bi-weekly brief generator
780163a feat(balance-cash): HubSpot deal pipeline

The Session Start banner

When you open Claude Code in this repo, you'll now see one of these at the top:

✓ On main, current with origin/main

⚠️ This branch is 12 commits behind origin/main. Run /sync to update.

⚠️ Skills changed on main since this branch forked:
   - .claude/skills/client-call-prep/SKILL.md
   - .claude/rules/cold-email-subject-lines.md
   Run /sync first if you plan to use these.

You don't have to remember any of this. The banner does the remembering for you. When it warns you, run /sync.

What the GitHub PR page tells you

When you open a pull request page on GitHub, look for the small status line near the top:

• "This branch is up to date with the base branch" — your PR is current with main, easy to merge.
• "This branch is N commits behind" — rebase your branch (run /sync locally) and force-push before merging.
• "This branch has conflicts that must be resolved" — you need to rebase and resolve manually. See Section 7, error #2.

Never merge a PR that says "behind" or "has conflicts." Fix the local branch first.

Cheat sheet

Print this. Stick it on your monitor. Refer to it whenever you forget which command does what.

/sync

/sync
# then make your changes
/push "short description"

git checkout main
git pull origin main
# create or edit your note file at:
# 01_clients/<slug>/notes/<YYYY-MM-DD>-<name>.md
git add <path-to-your-note>
git commit -m "docs: capitalize weekly brief 2026-05-14"
git push origin main

git status                          # branch + changed files
git log --oneline -10               # last 10 commits on this branch
git rev-list --count HEAD..origin/main  # how many behind

/sync

# Open the file, find <<< / === / >>> markers
# Pick the right version, delete markers
git add <file>
git rebase --continue

git branch oops-rescue
git reset --hard origin/main
git checkout oops-rescue
git branch -m feat/whatever

git reflog
# find the line right before the bad command
git reset --hard <short-hash>

type: short imperative description