Skip to main content

Understanding Repositories: Where Your Code Lives

A repository is where Git stores your project's history. Understanding repositories is understanding Git's foundation.

🎯 The Big Picture​

Think of a repository like this: If your project folder is a house, the repository is the house plus a complete history of every change ever made to it.

A regular folder has files. A Git repository has files plus all the history, all the versions, all the changes.

That's the difference.

What Is a Repository?​

A repository (or "repo") is a directory that contains:

  1. Your project files
  2. A .git folder (the Git database)
  3. Git's complete history of your project

The .git folder is hidden. It contains everything Git needs:

  • All commits
  • All branches
  • All tags
  • Configuration
  • The staging area

You don't edit .git directly. Git manages it for you.

Types of Repositories​

Local Repository​

A repository on your computer. It's complete and independent.

# Create a local repository
git init my-project
cd my-project

# Now you have a local repository

Remote Repository​

A repository on a server (GitHub, GitLab, etc.). Used for collaboration and backup.

# Clone a remote repository
git clone https://github.com/user/repo.git

# Now you have a local copy of the remote repository

Bare Repository​

A repository without a working directory. Used for servers.

# Create a bare repository
git init --bare my-project.git

# This has no working files, just the Git database

Creating a Repository​

Method 1: Initialize a New Repository​

# Create a new directory
mkdir my-project
cd my-project

# Initialize Git repository
git init

# Now you have a repository!

What happens?

  • Git creates a .git folder
  • Sets up the repository structure
  • You're ready to start tracking files

Method 2: Clone an Existing Repository​

# Clone from GitHub
git clone https://github.com/user/repo.git

# Clone with a different name
git clone https://github.com/user/repo.git my-project

# Clone a specific branch
git clone -b branch-name https://github.com/user/repo.git

What happens?

  • Git downloads the repository
  • Creates a local copy
  • Sets up remote tracking
  • You're ready to work

Repository Structure​

Here's what a repository looks like:

my-project/
├── .git/                 # Git database (hidden)
│   ├── HEAD             # Current branch reference
│   ├── config           # Repository configuration
│   ├── objects/         # All Git objects (commits, files, etc.)
│   ├── refs/            # Branch and tag references
│   └── ...
├── README.md            # Your project files
├── src/                 # Your project files
└── ...

You work with the visible files. Git manages the .git folder.

Checking Repository Status​

# Check if you're in a repository
git status

# If you see "not a git repository", you're not in one
# If you see file status, you're in a repository

Repository States​

A repository can be in different states:

Clean State​

$ git status
On branch main
nothing to commit, working tree clean

Meaning: All changes are committed. No uncommitted work.

Modified Files​

$ git status
On branch main
Changes not staged for commit:
  modified:   file.txt

Meaning: Files are changed but not staged.

Staged Files​

$ git status
On branch main
Changes to be committed:
  new file:   newfile.txt

Meaning: Files are staged and ready to commit.

My Take: Repositories Are Simple​

I used to think repositories were complicated. They're not.

A repository is just a folder with a .git subfolder. That's it.

Everything else is just Git managing that .git folder for you.

Memory Tip: The Filing Cabinet Analogy​

Think of a repository like a filing cabinet:

  • Working Directory: Your desk (where you work)
  • Staging Area: The inbox (files ready to file)
  • Repository: The filing cabinet (permanent storage)
  • .git folder: The filing system (how it's organized)

Once you see it that way, repositories make sense.

Common Mistakes​

Mistake 1: Initializing in the Wrong Directory​

# Don't do this
cd ~
git init  # This makes your home directory a repository!

Fix: Always cd into your project directory first.

Mistake 2: Nested Repositories​

# Don't do this
git init parent
cd parent
git init child  # Repository inside a repository!

Fix: One repository per project. Not nested.

Mistake 3: Not Understanding .git Folder​

# Don't do this
rm -rf .git  # You just deleted all your history!

Fix: Never manually edit .git. Let Git manage it.

Key Takeaways​

  1. Repository = Project folder + .git folder - The .git folder contains all history
  2. Local vs Remote - Local is on your computer, remote is on a server
  3. Create with git init - Initialize a new repository
  4. Clone with git clone - Copy an existing repository
  5. Never edit .git directly - Let Git manage it

What's Next?​

Now that you understand repositories, let's learn about the Git workflow. Next: The Git Workflow.

Remember: A repository is just a folder with history. Don't overthink it.