Git version control basics

Essential Commands - Derived from Workflow

1. Initializing and Cloning

Formula Starting a Repository

Option A: Create new repo

git init

Creates .git directory in current folder
Initializes HEAD pointing to refs/heads/main Option B: Clone existing repo

git clone <url>

Downloads entire history from remote
Sets up remote tracking branch automatically
Creates working directory with latest commit checked out

WHY CLONE? You get the full history locally—you can work offline and have complete backup.

2. Basic Workflow Commands

Formula The Add-Commit Cycle

# 1. Check status
git status
# Shows: untracked, modified, staged files
# 2. Stage specific files
git add <file1> <file2>
# Or stage all changes:
git add .
# 3. Commit with message
git commit -m "Add feature X"
# Creates snapshot with descriptive message
 
# 4. View history
git log --oneline --graph
# Shows commit tree visually

DERIVATION: Why this sequence?

status → understand current state
add → curate what goes in next commit (atomic changes)
commit → finalize the snapshot with context (message)
log → verify the history graph

3. Branching and Merging

Formula Branch Operations

Creating and switching branches:

# Create new branch
git branch feature-x
# Switch to it
git checkout feature-x
# Or both in one command:
git checkout -b feature-x

WHY?

branch creates a new pointer to current commit
checkout updates HEAD to point to that branch
HEAD determines which branch gets new commits Merging changes back:

git checkout main
git merge feature-x

HOW MERGE WORKS:

Fast-forward merge: If main hasn't diverged, just move pointer forward
Three-way merge: If both branches have new commits, Git creates a merge commit with two parents $\text{Merge} = \text{Find common ancestor} + \text{Apply both sets of changes}$

4. Remote Operations

Formula Synchronizing with Remote

# Add remote repository
git remote add origin <url>
 
# Push local commits to remote
git push origin main
# origin = remote name, main = branch
 
# Fetch updates from remote (doesn't merge)
git fetch origin
 
# Pull = fetch + merge
git pull origin main

WHAT HAPPENS IN PUSH:

Git compares local commits with remote HEAD
Sends missing commit objects over network
Updates remote branch pointer
Fast-forward only if no conflicts

WHY FETCH BEFORE MERGE? Lets you review changes before integrating them into your work.

Worked Examples

Worked example Example 1: Creating a New ML Project with Git

Scenario: You're starting a new machine learning project and want version control from day one.

# Step 1: Create project directory
mkdir ml-classifier
cd ml-classifier

Why? Start with a clean directory structure.

# Step 2: Initialize Git
git init

Why this step? Creates .git folder to track history. Now every change can be recorded.

# Step 3: Create initial files
echo "# ML Classifier Project" > README.md
echo "*.pyc\n__pycache__/\n.venv/" > .gitignore

Why .gitignore? Tells Git to ignore compiled files and virtual environments—don't want to track auto-generated files.

# Step 4: Stage and commit
git add README.md .gitignore
git commit -m "Initial commit: Add README and gitignore"

Why this step? Creates the first snapshot. Message describes what the commit contains.

# Step 5: Check status
git log --oneline
# Output: e7f3a2c (HEAD -> main) Initial commit: Add README and gitignore

Why check? Verify the commit was created and HEAD points to main branch.

Worked example Example 2: Feature Branch Workflow

Scenario: You need to add a data preprocessing module without breaking the main codebase.

# Step 1: Create and switch to feature branch
git checkout -b feature/preprocessing

Why? Isolates your work. Main branch stays stable while you experiment.

# Step 2: Create preprocessing module
cat > preprocessing.py << 'EOF'
import pandas as pd
def clean_data(df):
    """Remove null values and duplicates"""
    return df.dropna().drop_duplicates()
EOF

Why create file? This is the actual feature you're building.

# Step 3: Stage and commit
git add preprocessing.py
git commit -m "Add data cleaning function"

Why this message? Describes the functionality added, not implementation details.

# Step 4: Make another commit (iterative work)
cat >> preprocessing.py << 'EOF'
def normalize_features(df):
    """Scale features to [0,1] range"""
    return (df - df.min()) / (df.max() - df.min())
EOF
git add preprocessing.py
git commit -m "Add feature normalization"

Why separate commit? Each commit should be one logical change. Easier to revert if normalization has bugs.

# Step 5: Merge back to main
git checkout main
git merge feature/preprocessing

Why this step? Integrates the working feature into the main codebase.

# Step 6: Delete feature branch (optional)
git branch -d feature/preprocessing

Why delete? Keeps branch list clean. The commits are still in main's history.

Worked example Example 3: Collaborating with Remote Repository

Scenario: You're working with a team on GitHub. You need to push your changes and pull teammate updates.

# Step 1: Link to remote repository
git remote add origin https://github.com/username/ml-classifier.git

Why? Establishes connection to the remote server. "origin" is conventional name for primary remote.

# Step 2: Push your local commits
git push -u origin main

Why -u flag? Sets up tracking relationship: git push will default to origin main in future.

What happens internally:

Git compresses commit objects
Sends them over HTTPS/SSH
Remote updates its main branch pointer

# Step 3: Teammate makes changes, you need to update
git pull origin main

Why pull? Downloads teammate's commits and merges them into your local main.

If there are conflicts:

# Git shows conflict markers in files:
<<<<<<< HEAD
Your changes
=======
Teammate's changes
>>>>>>> commit-hash
# Resolve manually, then:
git add <resolved-file>
git commit -m "Merge branch 'main' of origin"

Why manual resolution? Git can't decide which version is correct—needs human judgment.

Common Mistakes

Common mistake Mistake 1: Committing Without Staging

Wrong approach:

# Modified train.py
git commit -m "Update model"
# Error: no changes added to commit

Why it feels right: Coming from systems where "save" immediately persists changes.

Steel-man: This two-step process seems redundant—why not commit directly?

The fix:

git add train.py
git commit -m "Update model architecture"

Why staging exists: Lets you commit part of your changes. You might have modified5 files but only want to commit 2 related changes. Staging gives you fine-grained control.

Shortcut (use carefully):

git commit -am "Update model"  # -a stages all tracked modified files

Common mistake Mistake 2: Vague Commit Messages

Wrong approach:

git commit -m "fix"
git commit -m "updates"
git commit -m "changes"

Why it feels right: You know what you changed right now, so details seem unnecessary.

Steel-man: Writing detailed messages slows down development flow.

The fix:

git commit -m "Fix null pointer error in data loader
- Add null check before accessing dataframe columns
- Return empty list instead of None for edge case
- Fixes issue #42"

Why this matters: In 3 months, you (or a teammate) need to understand why this change was made. git blame and git log become useless with vague messages. Good messages:

Describe what changed
Explain why (if not obvious)
Reference issues/tickets

Format convention:

<type>: <short summary> (50 chars max)
<detailed explanation> (72 chars per line)

Common mistake Mistake 3: Not Using .gitignore

Wrong approach:

git add .
# Accidentally commits:
# - __pycache__/
# - .venv/
# - .env (with API keys!)
# - dataset.csv (100MB)

Why it feels right: git add . is quick and seems comprehensive.

Steel-man: You want everything version-controlled for reproducibility.

The fix:

# Create .gitignore first
cat > .gitignore << 'EOF'
# Python
__pycache__/*.pyc
.venv/
venv/
# Environment variables (NEVER commit secrets!)
.env
.env.local
# Data files (too large for Git)
*.csv
*.h5
data/
 
# IDE
.vscode/
.idea/
# Model checkpoints (use Git LFS or external storage)
*.pth
*.ckpt
EOF
git add .gitignore
git commit -m "Add gitignore for Python ML project"

Why this matters:

Security: Prevents leaking API keys, passwords
Size: Git is designed for source code, not large binaries
Cleanliness: Avoids polluting history with auto-generated files If you already committed secrets:

# Remove from history (DANGEROUS—rewrites history)
git filter-branch --force --index-filter \
  "git rm --cached --ignore-unmatch .env" --prune-empty --tag-name-filter cat -- --all
# Then: IMMEDIATELY rotate the exposed credentials

Common mistake Mistake 4: Merging Without Reviewing

Wrong approach:

git merge feature-x
# Auto-merge failed, conflicts in train.py
# User just accepts all incoming changes without reading
git add train.py
git commit -m "Merge feature-x"
# Result: broken code in main branch

Why it feels right: Conflicts are frustrating—just want to get past them.

Steel-man: The feature branch was tested, so it must be correct.

The fix:

git merge feature-x
# Conflict in train.py
# 1. Open the file, look for conflict markers
# <<<<<<< HEAD
# model = LinearRegression()
# ======
# model = RandomForestRegressor()
# >>>>>>> feature-x
# 2. Understand BOTH versions
# - HEAD: main branch uses linear model
# - feature-x: new branch uses random forest
# 3. Decide based on context (maybe keep feature-x version)
# Remove markers, keep one version:
# model = RandomForestRegressor()
# 4. Test before committing
python -m pytest tests/
# 5. Stage and commit only after verification
git add train.py
git commit -m "Merge feature-x: Switch to random forest model
 
Resolved conflict by choosing RF over linear regression.
All tests passing."

Why this process: Merges can introduce subtle bugs even without conflicts. Always test the merged result.

Git Workflow Patterns

Formula Feature Branch Workflow (Industry Standard)

Pattern:

2. Create feature branch
3. Make commits on feature branch
4. Push feature branch to remote
5. Open pull request (PR)
6. Code review
7. Merge to main
8. Delete feature branch

Mathematical model: Each branch is a directed acyclic graph (DAG) of commits.

$\text{Branch}_{\text{feature}} = \text{Branch}_{\text{main}} + \Delta\text{commits}$

$\text{Merge} : \text{Branch}_{\text{main}} \leftarrow \text{Branch}_{\text{main}} \cup \Delta\text{commits}$

WHY DAG? Commits can have multiple parents (merge commits) but no cycles—you can't commit to the past.

Best Practices for ML Projects

Formula ML-Specific Git Practices

1. Don't commit large datasets or models

Use Git LFS (Large File Storage) for files >50MB
Or store in cloud (S3, GCS) and commit download scripts

2. Version your data and code together

# In train.py
DATA_VERSION = "v2.3"  # Corresponds to s3://bucket/data-v2.3/
MODEL_VERSION = "0.41"

3. Commit experiment configs, not just code

# config.yaml (tracked by Git)
model:
  type: "random_forest"
  n_estimators: 100
  max_depth: 10
data:
  version: "v2.3"

4. Use tags for production models

git tag -a v1.0 -m "First production model"
git push origin v1.0

WHY? Tags mark specific commits as significant. You can always checkout v1.0 to reproduce the exact production model.

Recall Feynman Explanation (Explain to a 12-year-old)

Imagine you're writing a story in a magic notebook. Every time you finish a chapter, you can press a button called "Save Checkpoint" (that's a commit). The magic notebook remembers every checkpoint you ever made.

If you write something and don't like it later, you can flip back to any old checkpoint and start over from there. You never lose your old work!

Now, let's say you want to try a different ending for your story. You create a branch—it's like a parallel universe for your story. In this branch, the hero wins differently. In the main story, things stay the same. Later, if you like the new ending, you can merge it back into the main story.

Your friend also has a copy of the magic notebook (on their computer). When you both make changes, you push your checkpoints to a shared cloud notebook (GitHub), and you pull their checkpoints to see what they wrote. If you both changed the same sentence, you have a conflict—you have to decide whose version to keep. That's Git! It's a time machine + parallel universes + cloud sharing for your code.

Connections

1.4.10-Command-line-interface - Git is primarily used via CLI
1.4.12-GitHub-workflows - Remote collaboration patterns
2.1.3-Jupyter-notebooks - Git works with .ipynb but diffs are mesy (use nbdime)
3.2.5-Experiment-tracking - Version control integrates with MLflow, Weights & Biases
4.1.8-CI-CD-pipelines - Git triggers automated testing and deployment
5.3.2-Model-versioning - Similar concepts applied to ML artifacts

#flashcards/ai-ml

What is a Git repository? :: A directory tracked by Git containing project files and a .git folder with complete version history, commits, and branch metadata.

What are the three states of files in Git?

Modified (working directory), Staged (index/staging area), and Committed (stored in .git repository).

What does git add do?

Stages changes from the working directory to the staging area, marking them for inclusion in the next commit.

What is a commit in Git?

A snapshot of the project at a specific time, identified by a SHA-1 hash, containing author info, timestamp, message, and pointer to parent commit(s).

What is a branch in Git?

A movable pointer to a commit, representing an independent line of development. Just41 bytes referencing a commit hash.

What is the difference between git fetch and git pull? :: git fetch downloads remote changes without merging; git pull does fetch + merge automatically.

Why use a .gitignore file?

To prevent Git from tracking auto-generated files, large datasets, secrets, and environment-specific files that shouldn't be in version control.

What does git checkout -b feature-x do?

Creates a new branch named "feature-x" and switches to it in one command (shorthand for git branch + git checkout).

What is a merge commit?

A commit with two (or more) parent commits, created when merging branches that have diverged—combines changes from both branches.

What does HEAD point to in Git?

The current branch reference or commit you're working on. Determines where new commits will be added.

Why use feature branches?

To isolate experimental work from the stable main branch, enabling parallel development without breaking production code.

What is the purpose of commit messages?

To document what changed and why, making history searchable and helping future developers understand the evolution of the codebase.

How does Git store commits efficiently?

By storing only the differences (deltas) between commits, not full file copies, using content-addressable storage.

What is a fast-forward merge?

When the target branch hasn't diverged, Git simply moves the branch pointer forward instead of creating a merge commit.

What does git push origin main do?

Sends local commits from the main branch to the remote repository named "origin" and updates the remote branch pointer.

Why are tags useful in ML projects?

They mark specific commits as significant (e.g., production models), enabling exact reproduction of a model version by checking out the tag.

Concept Map

Hinglish (regional understanding)

Intuition Hinglish mein samjho

Git ek version control system hai jo tumhare code ka time travel possible banata hai. Socho agar tumnek Python model likha, phir tuning karte-karte kuch broke ho gaya — Git ke saath tum instantly purane working version pe wapas jaa sakte ho. Ye especially ML projects ke liye zaroori hai kyunki experiments bahut hote hain aur track karna mushkil.

Teen stages hain: Modified (tumne file change kari but abhi Git ko bataya nahi), Staged (tumne git add kiya,

Core Concepts

The Three States of Files

Essential Commands - Derived from Workflow

1. Initializing and Cloning

2. Basic Workflow Commands

3. Branching and Merging

4. Remote Operations

Worked Examples

Common Mistakes

Git Workflow Patterns

Best Practices for ML Projects

Connections

Concept Map

Hinglish (regional understanding)

Go deeper — visual, from zero

Test yourself — Python & Scientific Computing

Connections