Part 1: Introduction to Version Control and Git Fundamentals

Introduction

I still remember the first time I lost hours of work because I didn't have proper version control. I was building a TypeScript API service, made some "quick changes" to refactor the authentication logic, and suddenly nothing worked. I couldn't remember exactly what I had changed, and my only backup was a zip file from two days ago. That painful experience taught me why version control isn't optional—it's fundamental to professional software development.

Fast forward to today, and I manage multiple TypeScript microservices across different repositories on GitHub. Version control has become second nature, but the journey from "git add, commit, push" to understanding proper workflows took time and real-world experience.

What Is Version Control?

Version control (also called source control) is a system that records changes to files over time so you can recall specific versions later. Think of it as a time machine for your code—you can go back to any point in your project's history, see what changed, who changed it, and why.

Why Version Control Matters

From my experience building production systems, here's why version control is critical:

1. Safety Net for Mistakes

When I accidentally deleted a critical database configuration file in one of my microservices, Git saved me:

# Oh no, I deleted the config!
rm src/config/database.ts

# Wait, I can restore it!
git checkout HEAD -- src/config/database.ts

2. Collaboration Without Chaos

In my multi-tenant POS system project, three developers worked on different features simultaneously. Without version control, we would have been emailing code files back and forth. With Git and GitHub:

# Developer A: Working on user authentication
git checkout -b feature/user-auth

# Developer B: Working on payment integration
git checkout -b feature/payment-integration

# Developer C: Working on inventory management
git checkout -b feature/inventory

Everyone works independently, and we merge changes systematically through pull requests.

3. Understanding Project History

When debugging a production issue, I often need to know when a bug was introduced:

# When did this payment calculation change?
git log --oneline -- src/services/payment.service.ts

# What exactly changed?
git show a1b2c3d

4. Experimentation Without Fear

I wanted to try a different database query optimization approach but wasn't sure if it would work:

# Create experimental branch
git checkout -b experiment/query-optimization

# Try the changes... if it doesn't work:
git checkout main
git branch -D experiment/query-optimization

No risk to the main codebase.

Understanding Git: The Most Popular Version Control System

Git is a distributed version control system created by Linus Torvalds in 2005. It's the industry standard and powers platforms like GitHub, GitLab, and Bitbucket.

Core Concepts

1. Repository (Repo)

A repository is a directory that Git tracks. It contains your project files and the complete history of all changes.

# Initialize a new repository
mkdir my-typescript-api
cd my-typescript-api
git init

# Output:
# Initialized empty Git repository in /path/to/my-typescript-api/.git/

2. Commit

A commit is a snapshot of your project at a specific point in time. Each commit has:

• A unique identifier (SHA hash)

• Author information

• Timestamp

• Commit message describing the changes

# Make changes to files, then:
git add src/controllers/user.controller.ts
git commit -m "Add user registration endpoint"

# Output:
# [main a1b2c3d] Add user registration endpoint
#  1 file changed, 45 insertions(+)

3. Branch

A branch is an independent line of development. Think of it as a parallel universe where you can make changes without affecting the main codebase.

# Create and switch to a new branch
git checkout -b feature/email-notifications

# List all branches
git branch
#   main
# * feature/email-notifications

4. Remote

A remote is a version of your repository hosted on a server (like GitHub). It enables collaboration and backup.

# Add GitHub as a remote
git remote add origin https://github.com/username/my-typescript-api.git

# Push your code to GitHub
git push -u origin main

Setting Up Git and GitHub

Installing Git

macOS:

# Using Homebrew
brew install git

# Verify installation
git --version
# git version 2.39.0

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install git
git --version

Windows: Download from git-scm.com

Initial Configuration

After installing Git, configure your identity:

# Set your name (appears in commits)
git config --global user.name "Your Name"

# Set your email (should match your GitHub email)
git config --global user.email "[email protected]"

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

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

# Verify configuration
git config --list

Setting Up GitHub

1. Create a GitHub Account: Go to github.com and sign up

2. Set Up SSH Keys (recommended for security):

# Generate SSH key
ssh-keygen -t ed25519 -C "[email protected]"

# Start SSH agent
eval "$(ssh-agent -s)"

# Add key to agent
ssh-add ~/.ssh/id_ed25519

# Copy public key to clipboard (macOS)
pbcopy < ~/.ssh/id_ed25519.pub

# Copy public key to clipboard (Linux)
cat ~/.ssh/id_ed25519.pub | xclip -selection clipboard

1. Add SSH Key to GitHub:

   • Go to GitHub Settings → SSH and GPG keys

   • Click "New SSH key"

   • Paste your public key

2. Test Connection:

ssh -T [email protected]
# Hi username! You've successfully authenticated...

Essential Git Commands and Workflows

Daily Workflow

Here's my typical workflow when working on a TypeScript microservice:

1. Start a New Feature

# Make sure main branch is up to date
git checkout main
git pull origin main

# Create feature branch
git checkout -b feature/add-product-search

# Verify you're on the right branch
git branch
#   main
# * feature/add-product-search

2. Make Changes and Commit

# Create a new file
touch src/services/search.service.ts

# Check status
git status
# On branch feature/add-product-search
# Untracked files:
#   src/services/search.service.ts

# Stage the file
git add src/services/search.service.ts

# Or stage all changes
git add .

# Commit with a descriptive message
git commit -m "Add product search service with fuzzy matching"

# Or use multi-line commit message
git commit -m "Add product search service

- Implement fuzzy search algorithm
- Add pagination support
- Include category filtering
- Add unit tests"

3. Push to GitHub

# First time pushing a new branch
git push -u origin feature/add-product-search

# Subsequent pushes
git push

Checking Status and History

# See current changes
git status

# See commit history
git log

# Compact view (my preferred format)
git log --oneline --graph --all

# See changes in working directory
git diff

# See changes that are staged
git diff --staged

# See changes in a specific file
git diff src/services/search.service.ts

Undoing Changes

Discard Changes in Working Directory:

# Discard changes in one file
git checkout -- src/services/search.service.ts

# Or using newer syntax
git restore src/services/search.service.ts

# Discard all changes
git checkout -- .
# Or: git restore .

Unstage Files:

# Unstage a file (keep changes in working directory)
git reset HEAD src/services/search.service.ts

# Or using newer syntax
git restore --staged src/services/search.service.ts

Undo Last Commit (keeping changes):

# Move HEAD back one commit, keep changes staged
git reset --soft HEAD~1

# Move HEAD back one commit, keep changes unstaged
git reset HEAD~1

# Move HEAD back one commit, discard changes (dangerous!)
git reset --hard HEAD~1

Working with Branches

# List all branches
git branch

# List remote branches
git branch -r

# List all branches (local and remote)
git branch -a

# Create new branch
git branch feature/new-feature

# Switch to branch
git checkout feature/new-feature

# Create and switch in one command
git checkout -b feature/new-feature

# Delete branch (safe - prevents deletion if not merged)
git branch -d feature/old-feature

# Force delete branch
git branch -D feature/experimental-feature

# Rename current branch
git branch -m new-branch-name

Merging Branches

# Switch to the branch you want to merge INTO
git checkout main

# Merge feature branch into main
git merge feature/add-product-search

# If there are conflicts, Git will tell you
# Fix conflicts manually, then:
git add .
git commit -m "Merge feature/add-product-search into main"

Real-World Example: Adding a New Feature

Here's how I recently added email notifications to one of my microservices:

# 1. Start from clean main branch
git checkout main
git pull origin main

# 2. Create feature branch
git checkout -b feature/email-notifications

# 3. Install dependencies
npm install nodemailer @types/nodemailer

# 4. Stage package files
git add package.json package-lock.json
git commit -m "Add nodemailer dependency for email notifications"

# 5. Create email service
# ... write code in src/services/email.service.ts ...

git add src/services/email.service.ts
git commit -m "Implement email service with template support"

# 6. Add tests
# ... write tests in src/services/email.service.test.ts ...

git add src/services/email.service.test.ts
git commit -m "Add email service unit tests"

# 7. Update environment config
git add src/config/env.ts .env.example
git commit -m "Add email configuration options"

# 8. Push to GitHub
git push -u origin feature/email-notifications

# 9. Create Pull Request on GitHub
# (done through GitHub web interface)

# 10. After PR approval and merge, clean up
git checkout main
git pull origin main
git branch -d feature/email-notifications

Understanding the Git Workflow

Git has three main states for files:

1. Working Directory: Your actual files where you make changes

2. Staging Area (Index): Files marked to be included in the next commit

3. Repository (.git directory): Committed snapshots of your project

Working Directory → (git add) → Staging Area → (git commit) → Repository

Example:

# Modified file is in working directory
echo "new feature" >> src/app.ts

# Check status
git status
# Changes not staged for commit:
#   modified: src/app.ts

# Move to staging area
git add src/app.ts

# Check status
git status
# Changes to be committed:
#   modified: src/app.ts

# Commit to repository
git commit -m "Add new feature"

# File is now in repository
git status
# nothing to commit, working tree clean

Common Git Workflows

Feature Branch Workflow

This is what I use daily for my TypeScript microservices:

# 1. Create feature branch from main
git checkout main
git pull origin main
git checkout -b feature/user-profile

# 2. Work on feature (multiple commits)
git add src/controllers/profile.controller.ts
git commit -m "Add profile controller"

git add src/services/profile.service.ts
git commit -m "Add profile service"

git add tests/profile.test.ts
git commit -m "Add profile tests"

# 3. Push feature branch
git push -u origin feature/user-profile

# 4. Create PR on GitHub, get review, merge
# 5. After merge, delete feature branch
git checkout main
git pull origin main
git branch -d feature/user-profile

Best Practices for Commits

Write Good Commit Messages

Bad:

git commit -m "fixed stuff"
git commit -m "updates"
git commit -m "wip"

Good:

git commit -m "Fix null pointer exception in payment service"
git commit -m "Add user authentication middleware with JWT validation"
git commit -m "Update database schema to support multi-tenancy"

Commit Message Format I Use:

<type>: <short description>

<detailed description if needed>

<optional footer with issue references>

Types:

• feat: New feature

• fix: Bug fix

• refactor: Code restructuring

• docs: Documentation changes

• test: Test additions/changes

• chore: Maintenance tasks

Example:

git commit -m "feat: Add product search with ElasticSearch integration

- Implement search service with fuzzy matching
- Add pagination and filtering
- Include relevance scoring
- Add integration tests

Closes #123"

Make Atomic Commits

Each commit should represent one logical change:

# Bad: Everything in one commit
git add .
git commit -m "Add feature and fix bugs"

# Good: Separate logical changes
git add src/services/payment.service.ts
git commit -m "Add payment service"

git add tests/payment.test.ts
git commit -m "Add payment service tests"

git add src/controllers/payment.controller.ts
git commit -m "Add payment controller endpoint"

.gitignore: What Not to Commit

Always create a .gitignore file to exclude files that shouldn't be version controlled:

# .gitignore for TypeScript/Node.js project
# Dependencies
node_modules/
npm-debug.log
yarn-error.log

# Build output
dist/
build/
*.js.map

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

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

# OS
.DS_Store
Thumbs.db

# Logs
logs/
*.log

# Coverage
coverage/
.nyc_output/

Conclusion

Version control with Git and GitHub is fundamental to modern software development. In this part, we covered:

• Why version control matters for backend development

• Core Git concepts: repositories, commits, branches, remotes

• Setting up Git and GitHub with SSH authentication

• Essential Git commands for daily workflows

• Best practices for commits and git ignore

From my experience, mastering these fundamentals makes everything else—branching strategies, monorepo vs polyrepo decisions, CI/CD integration—much easier to understand and implement.

In Part 2, we'll dive deep into branching strategies and workflows, exploring Git Flow, GitHub Flow, and Trunk-Based Development with real examples from production microservices.

---

Key Takeaways:

• Always commit early and often with meaningful messages

• Use branches for features, never commit directly to main

• Keep your commits atomic and focused

• Review your changes before committing (git diff)

• Pull before you push to avoid conflicts

Remember: Git is a tool that gets better with practice. Don't worry about making mistakes—that's what version control is for!