Article 1: Version Control with Git

Introduction

Version control is the foundation of modern software engineering. Through my experience working on both solo projects and large team codebases, I've seen how proper Git practices can mean the difference between smooth collaboration and merge conflict nightmares.

This article covers Git fundamentals from a practical perspective—not just the commands, but the workflows and habits that make version control work effectively in real projects.

Why Version Control Matters

Version control provides:

History tracking: Every change is recorded with who, when, and why
Collaboration: Multiple developers can work simultaneously
Experimentation: Try ideas in branches without risking stable code
Recovery: Revert to any previous state when things go wrong
Code review: Review changes before they're merged

Git Fundamentals

The Three States

Understanding Git's three states is essential for working effectively:

State

Description

Command to Move

Working Directory

Files you're actively editing

Staging Area

Changes ready to be committed

git add

Repository

Committed history

git commit

Essential Commands

# Initialize a new repository
git init

# Clone an existing repository
git clone https://github.com/username/repo.git

# Check status of working directory
git status

# Stage changes
git add filename.py        # Stage specific file
git add .                  # Stage all changes
git add -p                 # Interactive staging (review each change)

# Commit changes
git commit -m "Add user authentication module"

# View commit history
git log --oneline          # Compact view
git log --graph            # Visual branch history

# Push to remote
git push origin main

# Pull latest changes
git pull origin main

Understanding Commits

A commit is a snapshot of your project at a point in time:

# Example: What a commit captures
"""
Commit: a1b2c3d
Author: [email protected]
Date: 2024-01-15 10:30:00

Message: Add input validation to user registration

Changes:
  - Modified: src/validators.py (+25, -3)
  - Added: tests/test_validators.py (+45)
"""

Commit Best Practices

Writing Good Commit Messages

The conventional commit format I use in my projects:

<type>(<scope>): <subject>

<body>

<footer>

Types:

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Formatting, no code change
refactor: Code restructuring
test: Adding tests
chore: Maintenance tasks

Examples:

# Good commit messages
git commit -m "feat(auth): add password reset functionality"
git commit -m "fix(api): handle null response from external service"
git commit -m "docs: update installation instructions for Python 3.11"
git commit -m "refactor(models): extract validation logic to separate module"

# Bad commit messages
git commit -m "fix stuff"
git commit -m "updates"
git commit -m "WIP"

Commit Frequency

Guidelines from my experience:

Commit often, but meaningfully - Each commit should represent one logical change
Don't commit broken code to main branches
Use staging selectively - git add -p lets you commit related changes separately

# Interactive staging example
$ git add -p
diff --git a/src/models.py b/src/models.py
@@ -10,6 +10,12 @@ class User:
     def validate_email(self):
         # validation logic
+        if not self.email:
+            raise ValueError("Email is required")
Stage this hunk [y,n,q,a,d,e,?]? y

Branching Strategies

Git Flow

The branching model I use for most projects:

Branch Types:

Branch

Purpose

Naming

main

Production-ready code

main

develop

Integration branch

develop

feature

New features

feature/description

bugfix

Bug fixes

bugfix/description

hotfix

Urgent production fixes

hotfix/description

release

Release preparation

release/v1.0.0

GitHub Flow (Simplified)

For smaller projects, I often use the simpler GitHub Flow:

Steps:

Create branch from main
Make changes and commit
Open Pull Request
Review and discuss
Merge to main
Deploy

Branch Commands

# Create and switch to new branch
git checkout -b feature/user-authentication

# List all branches
git branch -a

# Switch branches
git checkout develop
# Or with newer Git:
git switch develop

# Delete a branch
git branch -d feature/completed-feature

# Push new branch to remote
git push -u origin feature/user-authentication

Merging and Rebasing

Merge vs Rebase

When to use each:

Scenario

Strategy

Reason

Merging feature to main

Merge

Preserves feature history

Updating feature with main

Rebase

Keeps history clean

Public/shared branches

Merge

Don't rewrite shared history

Local cleanup

Rebase

Clean up before sharing

Merge Commands

# Merge a branch
git checkout main
git merge feature/auth

# Merge with no fast-forward (creates merge commit)
git merge --no-ff feature/auth

# Rebase current branch onto main
git checkout feature/auth
git rebase main

# Interactive rebase to clean up commits
git rebase -i HEAD~3

Resolving Merge Conflicts

When conflicts occur:

# The file will show conflict markers
<<<<<<< HEAD
def authenticate(username, password):
    return check_credentials(username, password)
=======
def authenticate(user, pwd):
    return validate_user(user, pwd)
>>>>>>> feature/auth

Resolution steps:

# 1. Open conflicted file and resolve manually
# 2. Remove conflict markers, keep correct code
# 3. Stage the resolved file
git add src/auth.py

# 4. Continue the merge or rebase
git merge --continue
# or
git rebase --continue

Collaborative Workflows

Pull Request Workflow

Keeping Branches Updated

# Fetch latest changes
git fetch origin

# Update your branch with main
git checkout feature/my-feature
git rebase origin/main

# Or merge approach
git merge origin/main

Working with Remotes

# Add a remote
git remote add upstream https://github.com/original/repo.git

# View remotes
git remote -v

# Fetch from all remotes
git fetch --all

# Push to specific remote
git push origin feature/my-feature

Undoing Changes

Common Scenarios

Commands for Undoing

# Discard changes in working directory
git checkout -- filename.py
# Newer syntax:
git restore filename.py

# Unstage a file
git reset HEAD filename.py
# Newer syntax:
git restore --staged filename.py

# Undo last commit (keep changes)
git reset --soft HEAD~1

# Undo last commit (discard changes) - DANGEROUS
git reset --hard HEAD~1

# Revert a commit (creates new commit)
git revert abc123

# Amend the last commit message
git commit --amend -m "New message"

Git Configuration

Essential Settings

# Set your identity
git config --global user.name "Your Name"
git config --global user.email "[email protected]"

# Set default branch name
git config --global init.defaultBranch main

# Set default editor
git config --global core.editor "code --wait"

# Enable color output
git config --global color.ui auto

# Set pull behavior
git config --global pull.rebase true

Useful Aliases

Add these to your .gitconfig:

[alias]
    st = status
    co = checkout
    br = branch
    ci = commit
    lg = log --oneline --graph --decorate
    last = log -1 HEAD
    unstage = reset HEAD --
    amend = commit --amend --no-edit
    branches = branch -a
    tags = tag -l
    stashes = stash list
    # Show what I did today
    today = log --since=midnight --author='Your Name' --oneline

.gitignore Patterns

# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
venv/
.env

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

# Testing
.pytest_cache/
.coverage
htmlcov/
.tox/

# Build
dist/
build/
*.egg-info/

# OS
.DS_Store
Thumbs.db

# Project specific
*.log
secrets.yaml

Advanced Git Techniques

Stashing Changes

# Stash current changes
git stash

# Stash with a message
git stash save "WIP: working on auth"

# List stashes
git stash list

# Apply most recent stash
git stash pop

# Apply specific stash
git stash apply stash@{2}

# Drop a stash
git stash drop stash@{0}

Cherry-picking

# Apply a specific commit to current branch
git cherry-pick abc123

# Cherry-pick without committing
git cherry-pick --no-commit abc123

Bisect for Bug Finding

# Start bisect
git bisect start

# Mark current version as bad
git bisect bad

# Mark known good version
git bisect good v1.0.0

# Git will checkout commits for you to test
# After each test, mark as good or bad
git bisect good
# or
git bisect bad

# When found, reset
git bisect reset

Practical Exercise

Exercise 1: Repository Setup

# Create a new project with proper Git setup
mkdir task-manager && cd task-manager

# Initialize repository
git init

# Create initial structure
mkdir -p src/task_manager tests
touch src/task_manager/__init__.py
touch README.md .gitignore

# Create .gitignore
cat > .gitignore << 'EOF'
__pycache__/
*.pyc
venv/
.env
.pytest_cache/
EOF

# Initial commit
git add .
git commit -m "chore: initial project setup"

Exercise 2: Feature Branch Workflow

# Create feature branch
git checkout -b feature/add-task-model

# Create the model file
cat > src/task_manager/models.py << 'EOF'
from dataclasses import dataclass
from datetime import datetime
from typing import Optional

@dataclass
class Task:
    title: str
    description: str
    created_at: datetime
    completed_at: Optional[datetime] = None
    
    @property
    def is_completed(self) -> bool:
        return self.completed_at is not None
EOF

# Commit the change
git add src/task_manager/models.py
git commit -m "feat(models): add Task dataclass with completion tracking"

# Switch back to main and merge
git checkout main
git merge --no-ff feature/add-task-model -m "Merge feature/add-task-model"

# Delete the feature branch
git branch -d feature/add-task-model

Exercise 3: Handling Conflicts

# Create two branches that will conflict
git checkout -b branch-a
echo "Version A" > conflict.txt
git add conflict.txt
git commit -m "Add version A"

git checkout main
git checkout -b branch-b
echo "Version B" > conflict.txt
git add conflict.txt
git commit -m "Add version B"

# Merge branch-a into main
git checkout main
git merge branch-a

# Now try to merge branch-b (will conflict)
git merge branch-b
# Resolve the conflict manually, then:
git add conflict.txt
git commit -m "Merge branch-b, resolve conflict"

Common Mistakes and How to Avoid Them

Mistake

Prevention

Recovery

Committing to wrong branch

Always check git status first

git stash, switch branch, git stash pop

Committing sensitive data

Use .gitignore, review before commit

git filter-branch or BFG Repo Cleaner

Force pushing to shared branch

Use --force-with-lease

Coordinate with team, restore from backup

Large binary files

Use Git LFS for binaries

Remove with git filter-branch

Vague commit messages

Use templates, review before pushing

git rebase -i to reword

Key Takeaways

Commit messages matter - They're documentation for your future self and teammates
Branch strategically - Use branches for features, but don't let them live too long
Pull/rebase regularly - Keep your branch updated to minimize conflicts
Never rewrite shared history - Use revert for pushed commits
Configure Git properly - Good defaults save time and prevent mistakes

What's Next?

With version control mastered, you're ready to set up a professional development environment. In Article 2: Development Environment Setup, we'll configure Python tooling, virtual environments, and IDE settings for productive development.

This article is part of the Software Engineering 101 series.

PreviousSoftware Engineering 101 NextArticle 2: Development Environment Setup

Last updated 15 hours ago

hashtagIntroduction

hashtagWhy Version Control Matters

hashtagGit Fundamentals

hashtagThe Three States

hashtagEssential Commands

hashtagUnderstanding Commits

hashtagCommit Best Practices

hashtagWriting Good Commit Messages

hashtagCommit Frequency

hashtagBranching Strategies

hashtagGit Flow

hashtagGitHub Flow (Simplified)

hashtagBranch Commands

hashtagMerging and Rebasing

hashtagMerge vs Rebase

hashtagMerge Commands

hashtagResolving Merge Conflicts

hashtagCollaborative Workflows

hashtagPull Request Workflow

hashtagKeeping Branches Updated

hashtagWorking with Remotes

hashtagUndoing Changes

hashtagCommon Scenarios

hashtagCommands for Undoing

hashtagGit Configuration

hashtagEssential Settings

hashtagUseful Aliases

hashtag.gitignore Patterns

hashtagAdvanced Git Techniques

hashtagStashing Changes

hashtagCherry-picking

hashtagBisect for Bug Finding

hashtagPractical Exercise

hashtagExercise 1: Repository Setup

hashtagExercise 2: Feature Branch Workflow

hashtagExercise 3: Handling Conflicts

hashtagCommon Mistakes and How to Avoid Them

hashtagKey Takeaways

hashtagWhat's Next?