Git & GitHub

Related guides: Personal OS · The Terminal · Zo Computer

Want to set this up with an agent? Try the Safety Net prompt, which walks through the map, the save-point idea, and protecting your folders step by step.

Preface

Git is the tool that answers three questions every project eventually asks:

1. What changed, and when? (version history)
2. How do I get the same files on another computer? (syncing)
3. How do multiple people — or multiple agents — work on the same files without destroying each other’s work? (collaboration)

It was built for software teams, but it works on any folder of files, which is exactly why it’s the backbone of your Personal OS: one repository, cloned onto every computer you use, with GitHub as the meeting point in the middle.

Two pieces of good news before the vocabulary. First, you only need a small slice of Git — the daily loop is four commands. Second, your agent knows Git deeply; your job is to understand the model well enough to ask for what you want and recognize what happened. When in doubt, ask the agent — “what’s the state of this repo?” and “explain what just happened” are always fair questions.

By the end of this guide you should be able to:

• Explain what a repository, commit, remote, push, pull, and clone are.
• Run (or delegate) the daily loop: pull → work → commit → push.
• Create a private GitHub repository with the gh CLI and clone it onto another machine.
• Keep secrets and heavy files out of a repository with .gitignore.

Basics

1. The mental model

• A repository (repo) is a folder that Git is tracking. Git keeps its records in a hidden .git subfolder; delete that and it’s just a normal folder again.
• A commit is a saved snapshot of the whole repo at a moment in time, with a short message describing what changed. The history of a repo is a chain of commits. Nothing is truly saved in Git until it’s committed — and once committed, it’s very hard to lose.
• A remote is another copy of the repository somewhere else — almost always on GitHub, a website that hosts repositories. Your laptop has a copy, your Zo computer has a copy, GitHub holds the shared copy in the middle.
• Push sends your new commits up to the remote. Pull brings down commits that arrived there from anywhere else. Clone copies an entire repository onto a machine for the first time.
• A branch is a parallel line of history — useful for trying changes without touching the main line. For a Personal OS you can live happily on the single default branch (main) for a long time. Just recognize the word: when an agent says “I created a branch,” it means “I did this work off to the side.”

The picture to hold: every machine has the full repository. GitHub is not “where the files really live” — it’s the always-on copy that every other copy syncs through. (This is also why Git doubles as a backup: losing your laptop loses nothing that was pushed.)

2. The daily loop

This is 90% of real Git usage:

git pull                        # start of session: get everyone else's changes
# ... do your work ...
git status                      # see what changed (always safe to run)
git add -A                      # stage all changes for the next snapshot
git commit -m "what I changed"  # take the snapshot
git push                        # send it to GitHub

In agent terms: “pull the latest” when you sit down, “commit and push” when you stand up. Say those phrases to your agent and it will run this loop correctly.

Two commands worth knowing for reading history:

git log --oneline    # the list of commits, newest first
git diff             # exactly what's changed since the last commit

3. The GitHub CLI (gh)

The gh command lets you (and your agent) operate GitHub from the terminal — create repos, clone them, open pull requests — without visiting the website.

Setup (once per machine):

brew install gh      # macOS; on Linux/Zo, ask your agent to install it
gh auth login        # opens a browser to log you into GitHub

gh auth login walks you through authentication interactively and stores the credential, which also makes plain git push/git pull work with GitHub without password prompts. This is the step you’ll repeat on every new machine, including your Zo computer.

Create your Personal OS repo (once ever): from inside your personal-os folder:

git init                                              # make the folder a repo
gh repo create personal-os --private --source=. --push  # create on GitHub, connect, upload

--private matters: your Personal OS is your life’s context. Private means only accounts you explicitly invite can see it.

Clone onto every other machine:

gh auth login                          # once per machine
gh repo clone <your-username>/personal-os

4. .gitignore — keeping things out

A file named .gitignore at the root of the repo lists patterns Git should never track. Two categories always belong there:

# secrets — never commit credentials
.env
*.key
.secrets

# heavy media — keep the repo light
*.mp4
*.mov
*.wav

Rules of thumb:

• Secrets: a Git repo remembers forever — a password committed once lives in the history even after you delete the file. If you ever commit a secret, treat it as exposed: rotate it (get a new one), don’t just remove the file.
• Heavy media: video and audio make every clone slow and bloated. Keep the media elsewhere and commit a small index or download script instead.
• Ask your agent to review what’s about to be committed the first few times: “Before you push, check that nothing sensitive or huge is included.”

5. When something goes wrong

• Merge conflict (you edited the same file on two machines between syncs): Git stops and asks a human — or an agent — to choose. This is routine, not a disaster. Ask your agent: “Resolve this merge conflict; here’s which version I want.” Prevent most of them with the pull-first/push-after habit.
• “I made a mess.” Git’s superpower is that committed history is recoverable. Tell the agent what state you want back: “Restore this file to how it was this morning” or “Undo the last commit but keep my changes.”
• Detached HEAD, rebase, stash, … — jargon you can safely ignore until it appears, at which point: “Explain what state this repo is in and get me back to normal.”

Practice

1. Do the full setup on your laptop: git init your Personal OS, create the private GitHub repo with gh, push it.
2. Clone the repo onto a second machine (your Zo computer is the natural target).
3. Run one full round trip: change a file on machine A, commit and push; pull on machine B and confirm the change arrived; change it on B, push, and pull it back on A.
4. Deliberately create a tiny merge conflict (edit the same line on both machines without syncing), then ask your agent to resolve it. Watching one resolve safely removes most of the fear.
5. Add a .gitignore, then verify it works: create a file matching an ignored pattern and confirm git status doesn’t list it.

Proof of understanding

• What is a commit, and why is “committed” different from “saved”?
• Where does your repository “really” live once it’s on your laptop, your Zo computer, and GitHub?
• Recite the daily loop — which command starts a session, and which ends it?
• Why must a committed secret be rotated rather than just deleted?
• What is a merge conflict, when does it happen, and what’s the habit that prevents most of them?
• What does gh auth login do, and when do you need to run it?

Further reading

• Personal OS guide, section 4 — what this syncing machinery is for.
• Zo Computer guide — cloning your Personal OS onto your cloud computer.
• GitHub’s own “Hello World” tutorial (docs.github.com) — a gentle browser-based walkthrough of the same concepts.
• Ask your agent for a personalized tour: “Teach me Git interactively in a scratch folder — make commits with me and show me what each command did.”