Version Control and Git Basics

Before version control, developers backed up work by copying folders. The result was chaos:

project/
├── app_v1.py
├── app_FINAL.py
├── app_FINAL_real.py
├── app_FINAL_v2_FIXED.py
└── app_backup_2024-01-09.py

This system has fatal flaws: there is no record of what changed between versions, no explanation of why, no way to work on two things simultaneously without overwriting each other, and no safe way to experiment without risking the working copy.

Git solves all of this. But understanding Git properly requires understanding the model it uses to store history.

Git's mental model is snapshots, not differences. When you commit, Git takes a complete picture of every tracked file at that moment in time. It stores this efficiently — unchanged files are referenced rather than duplicated — but the conceptual model is complete snapshots.

Each snapshot is called a commit. Every commit contains:

• The complete state of all tracked files
• A reference to the previous commit (the parent)
• The author's name and email
• The timestamp
• A message you wrote describing the change
• A unique identifier (a long hex string called a hash)

The sequence of commits forms a history — a chain going back to the very first commit. You can view any snapshot, compare any two, or return to any previous state. Nothing is ever lost.

Understanding Git requires understanding three places where your code can live:

The staging area is the key to understanding Git. It lets you be selective: if you changed three files but only two of the changes are ready, you can stage just those two and commit them. The third change stays in your working directory until you are ready.

# Changes exist only in working directory
[working dir]  app.py (modified)
[staging]      (empty)
[repository]   last commit: ...

# After: git add app.py
[working dir]  app.py (staged)
[staging]      app.py
[repository]   last commit: ...

# After: git commit -m 'Fix login bug'
[working dir]  app.py (clean)
[staging]      (empty)
[repository]   new commit: Fix login bug

1. git init

   Create a new repository in the current directory.

   bash

   mkdir my-project
    && cd my-project
   git init
   Initialized empty Git repository in .git/
   

   This creates a hidden .git directory. Your project is now a repository.

2. git status

   Your most-used command. Shows what has changed, what is staged, and what is untracked.

   bash

   git status
   On branch main
   Changes not staged for commit:
     modified:   app.py
   
   Untracked files:
     tests/
   
   no changes added to commit
   

3. git add

   Stage changes for the next commit.

   bash

   # Stage a specific file
   git add app.py
   
   # Stage all changes in current directory
   git add .
   
   # Stage parts of a file interactively
   git add -p app.py
     # choose individual hunks
   

4. git commit

   Take a snapshot of the staged changes.

   bash

   # Commit with inline message
   git commit -m "Add user validation"
   [main a1b2c3d] Add user validation
    2 files changed, 34 insertions(+), 5 deletions(-)
   
   # Open editor for a longer message
   git commit
   
   # Stage all tracked files and commit in one step
   git commit -am "Quick fix"
   

5. git log

   View the history of commits.

   bash

   # Default: full log
   git log
   
   # One line per commit
   git log --oneline
   a1b2c3d Add user validation
   9f3e2a1 Initial commit
   
   # Show last N commits
   git log --oneline -5
   
   # Show commits by a specific author
   git log --author="Alice"
   
   # Show commits affecting a specific file
   git log --oneline -- auth.py
   
   # Graphical representation (useful with branches)
   git log --oneline --graph --all
   

git diff compares versions of your files. Which versions it compares depends on what arguments you give it:

# Unstaged changes: working dir vs staging area
git diff

# Staged changes: staging area vs last commit
git diff --staged

# All changes: working dir vs last commit
git diff HEAD

# Compare two commits
git diff a1b2c3d f4e5d6c

# Show only the names of changed files
git diff --name-only

# Show statistics (lines added/removed per file)
git diff --stat

Reading a diff:

diff --git a/app.py b/app.py
--- a/app.py          # old version
+++ b/app.py          # new version
@@ -12,7 +12,8 @@    # location in file
 def login(user, pw): # unchanged line
-    return True      # removed line (red)
+    if not user or not pw:  # added line (green)
+        return False

Some files should never be committed: compiled outputs, local configuration, secrets, and large data files. A .gitignore file tells Git to ignore them.

# Python
__pycache__/
*.pyc
*.pyo
.pytest_cache/
htmlcov/

# Secrets — NEVER commit these
.env
*.key
secrets.yml

# IDE files
.vscode/
.idea/

# OS files
.DS_Store
Thumbs.db

# Dependency directories
node_modules/
venv/

Knowing how to undo is as important as knowing how to commit. Here are the main options:

A commit message is a gift to your future self and your teammates. Reading the log should tell the story of the project.

Add rate limiting to the login endpoint

Login attempts were unlimited, making brute-force attacks trivial.
Implements a sliding window of 5 attempts per IP per 15 minutes.
Exceeding the limit returns 429 Too Many Requests.

Fixes: JIRA-1234