What is a repository? (it's not just a folder)

What it actually is

A repository, “repo” for short, is your project’s folder plus the complete history git has recorded for everything inside it. An ordinary folder only holds whatever files happen to be in it right now: overwrite a file, and the old version is gone. A repository is more like a manuscript written with track changes turned on since page one: every earlier draft, every deleted paragraph, every note about why a change was made, is still sitting there if you go looking for it.

What makes a folder a repository is a hidden subfolder called .git, created the moment someone runs git init inside it (or you clone one that already exists). That .git folder is where the actual history lives: every commit, every branch, every message. The rest of the folder, your code, your images, your README, is just the current snapshot git is tracking.

A repository doesn’t need to live in more than one place. It can sit purely on your laptop and never touch the internet. But most of the time, it also exists as a copy hosted somewhere like GitHub, GitLab, or Bitbucket. That hosted copy is called a remote, and by convention it’s named origin. Your local repo and origin are two separate copies of the same project, not one shared thing, and they only agree with each other right after you’ve pushed commits up or pulled commits down. In between, they can differ, which is exactly what messages like “your branch is 2 commits ahead of origin/main” are telling you.

Why your AI just did this

When you start a new project, Claude Code will often run git init before writing a single line of code, which is what turns a plain folder into a repository. From there, it can commit as it goes: each meaningful change becomes a saved point it can describe, compare, or roll back to later, instead of one undifferentiated pile of edits.

If you then ask it to “push this to GitHub,” that’s two separate moves happening under one instruction. First, a repository has to exist on GitHub’s servers, either created through the GitHub website or with a command like gh repo create. Second, your local repo has to be told that this remote repository exists and is where it should send its history (git remote add origin <url>), before git push can upload anything at all. Skip either step and the push fails, it isn’t one automatic action.

When you’ll run into it

• fatal: not a git repository (or any of the parent directories): .git, you ran a git command in a folder that was never turned into a repo, or its .git folder is missing
• Your agent says “I’ve initialized a git repository here” the first time you ask it to start tracking changes
• remote: Repository not found, the GitHub repo doesn’t exist yet, you don’t have access to it, or the URL is misspelled
• Your local files and what shows up on github.com look different, because nothing has been pushed since your last change
• Running git clone <url> downloads someone’s entire repository, full commit history included, not just a snapshot of their current files

What to check

• Run git status inside the folder. “Not a git repository” means there’s no .git here yet, run git init to create one
• Run git remote -v to see if a remote is even configured. Empty output means this repo only exists on your machine
• Before making a repository public on GitHub, check there’s no .env file or hardcoded key sitting inside it (see exposed API keys)
• A repo’s tracked history isn’t the same as “everything in the folder”: files listed in .gitignore sit in the folder but never make it into a commit

Say it like a dev

Instead of: “the folder with my code” Say: “my repo” or “my local repository”

Instead of: “put it online” Say: “push it to GitHub” or “create the remote”

Instead of: “is this saved somewhere safe” Say: “has this been committed, and is there a remote we’ve actually pushed to”