Git - Repository Basics

Beginner

A Git repository is the heart of version control—it's where Git stores all the history and metadata for your project. Understanding repositories is crucial for working with Git effectively.

What is a Git Repository?

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

Your project files (the working directory)
Git's tracking data (the .git directory)
Complete history of all changes ever made
Branches and tags for organizing work

my-project/                 ← Repository root
├── .git/                   ← Git's internal database (don't touch!)
│   ├── objects/            ← All file contents and commits
│   ├── refs/               ← Branch and tag pointers
│   ├── HEAD                ← Current branch pointer
│   └── config              ← Repository settings
├── README.md               ← Your project files
├── src/
│   └── main.js
└── package.json

Creating Repositories

Method 1: Initialize New Repository

Start a new project from scratch:

Create new directory and initialize:

mkdir awesome-project
cd awesome-project
git init

Expected Output:

Initialized empty Git repository in /Users/john/awesome-project/.git/

Initialize with specific branch name:

git init --initial-branch=main
# or
git init -b main

Method 2: Initialize in Existing Directory

Add Git to an existing project:

cd existing-project
git init

This won't affect existing files until you add and commit them.

Method 3: Clone Existing Repository

Copy someone else's repository:

Clone from GitHub:

git clone https://github.com/user/repository.git

Clone with custom directory name:

git clone https://github.com/user/repository.git my-custom-name

Clone with SSH (recommended after setup):

git clone [email protected]:user/repository.git

Expected Output:

Cloning into 'repository'...
remote: Enumerating objects: 125, done.
remote: Counting objects: 100% (125/125), done.
remote: Compressing objects: 100% (85/85), done.
remote: Total 125 (delta 45), reused 98 (delta 25), pack-reused 0
Receiving objects: 100% (125/125), 23.45 KiB | 7.82 MiB/s, done.
Resolving deltas: 100% (45/45), done.

Understanding the .git Directory

Let's explore what Git creates when you initialize a repository:

List .git contents (Unix/Mac):

ls -la .git/

List .git contents (Windows):

dir .git

Expected Output:

total 15
drwxr-xr-x  9 john staff   288 Oct 25 14:30 .
drwxr-xr-x  3 john staff    96 Oct 25 14:30 ..
-rw-r--r--  1 john staff    21 Oct 25 14:30 HEAD
-rw-r--r--  1 john staff   137 Oct 25 14:30 config
-rw-r--r--  1 john staff    73 Oct 25 14:30 description
drwxr-xr-x  2 john staff    64 Oct 25 14:30 hooks
drwxr-xr-x  2 john staff    64 Oct 25 14:30 info
drwxr-xr-x  4 john staff   128 Oct 25 14:30 objects
drwxr-xr-x  4 john staff   128 Oct 25 14:30 refs

Key .git Components

File/Directory	Purpose	Safe to Edit?
HEAD	Points to current branch	❌ No
config	Repository settings	⚠️ Via git config
objects/	All file contents and commits	❌ No
refs/	Branch and tag pointers	❌ No
hooks/	Automation scripts	✅ Yes
info/	Repository info and excludes	✅ Yes

Repository States

Repositories can be in different states:

Bare Repository

A repository without a working directory (used for sharing):

git init --bare shared-repo.git

Bare repositories are used on servers. You can't edit files directly in them—only push and pull changes.

Working Repository

Normal repository with files you can edit (what we usually use):

git init  # Creates working repository

Practical Examples

Starting a New Web Project

# Create project structure
mkdir my-website
cd my-website
git init

# Create initial files
echo "# My Awesome Website" > README.md
echo "" > index.html
echo "My Site" >> index.html
echo "Welcome!
" >> index.html

# Create CSS directory
mkdir css
echo "body { font-family: Arial, sans-serif; }" > css/style.css

# Add .gitignore
echo "*.log" > .gitignore
echo "node_modules/" >> .gitignore
echo ".DS_Store" >> .gitignore

# Initial commit
git add .
git commit -m "Initial website structure"

Cloning and Exploring a Repository

Clone a popular repository:

git clone https://github.com/microsoft/vscode.git

Explore the repository:

cd vscode
ls -la                    # See project structure
git log --oneline -10     # See recent commits
git branch -a             # See all branches
git remote -v             # See remote connections

Repository Information Commands

Basic Information

# Check if you're in a Git repository
git status

# Show repository configuration
git config --list

# Show remote repositories
git remote -v

# Show current branch
git branch --show-current

Repository Statistics

# Count total commits
git rev-list --count HEAD

# Show repository size
du -sh .git/

# Show number of files tracked
git ls-files | wc -l

# Show contributors
git shortlog -sn

Example outputs:

$ git rev-list --count HEAD
247

$ du -sh .git/
15M     .git/

$ git ls-files | wc -l
89

$ git shortlog -sn
    156  John Doe
     45  Jane Smith
     28  Bob Wilson

Working with Multiple Repositories

Repository Organization

~/projects/
├── personal/
│   ├── my-blog/          ← Independent Git repo
│   └── side-project/     ← Independent Git repo
├── work/
│   ├── main-app/         ← Independent Git repo
│   └── microservice/     ← Independent Git repo
└── learning/
    └── git-tutorial/     ← Independent Git repo

Each directory is its own separate Git repository with independent history.

Switching Between Repositories

# Work on project A
cd ~/projects/work/main-app
git status
git add .
git commit -m "Fix user authentication"

# Switch to project B
cd ~/projects/personal/my-blog
git status
git pull origin main
# Make changes and commit

Repository Best Practices

Repository Structure

Good repository structure:

my-project/
├── README.md           ← Project description
├── .gitignore          ← Files to ignore
├── LICENSE             ← License information
├── docs/               ← Documentation
├── src/                ← Source code
├── tests/              ← Test files
├── scripts/            ← Build/utility scripts
└── config/             ← Configuration files

What to Track

✅ Include in Git:

- Source code
- Configuration files
- Documentation
- Build scripts
- Test files
- README and LICENSE

❌ Don't include in Git:

- Compiled binaries
- Log files
- Temporary files
- IDE-specific files
- Dependencies (node_modules, etc.)
- Sensitive data (passwords, keys)

Repository Naming

✅ Use descriptive names: user-authentication-service
✅ Use hyphens for readability: my-awesome-app
✅ Be consistent: Choose a naming convention and stick to it
❌ Avoid spaces: My Project becomes My%20Project in URLs
❌ Don't use special characters: my_app@2023

Repository Security

Sensitive Data Prevention

Create comprehensive .gitignore:

# Environment variables
.env
.env.local
.env.production

# API keys and secrets
config/secrets.json
*.key
*.pem

# Database files
*.db
*.sqlite

# Logs
*.log
logs/

# Operating system files
.DS_Store
Thumbs.db

# IDE files
.vscode/
.idea/
*.swp

Never commit: Passwords, API keys, private keys, database credentials, or any sensitive information.

Repository Maintenance

Checking Repository Health

# Check for corruption
git fsck

# Optimize repository
git gc

# Show repository statistics
git count-objects -v

Cleaning Up

# Remove untracked files (be careful!)
git clean -n    # Dry run - see what would be deleted
git clean -f    # Actually remove files

# Remove untracked directories too
git clean -fd

Common Repository Issues

Not in a Git Repository

Error:

fatal: not a git repository (or any of the parent directories): .git

Solutions:

Run git init to create a new repository
Navigate to a directory that contains a .git folder
Clone an existing repository

Permission Denied

Error:

Permission denied (publickey)

Solutions:

Set up SSH keys properly
Use HTTPS instead of SSH for cloning
Check your GitHub/GitLab access permissions

Summary

You now understand Git repositories:

✅ What a repository is and what it contains
✅ How to create repositories with git init
✅ How to clone existing repositories
✅ The structure and purpose of the .git directory
✅ Best practices for repository organization
✅ What files to include and exclude
✅ Basic repository maintenance commands

Next Steps

Now that you understand repositories, let's dive deeper into staging and adding files:

→ Git - Adding & Staging

Practice Tip: Create several practice repositories with different types of projects (web, mobile, data science) to get comfortable with repository management.