Version Control & Collaboration

Every Git repository is, at its heart, a content-addressed key-value store. Git stores four types of objects, each identified by the SHA-1 hash of its content:

• blob: the raw bytes of a file's contents (no filename, no metadata)
• tree: a directory listing mapping names to blob or tree hashes
• commit: a snapshot pointer (root tree hash) plus metadata — author, timestamp, message, and parent commit hash(es)
• tag: an annotated pointer to a commit

This forms a Merkle DAG: each commit hashes its parent, each tree hashes its children. If anyone tampers with any historical file, every hash up the chain changes, making corruption immediately detectable.

Why content-addressing matters for branching: A branch in Git is literally just a text file containing a 40-character SHA-1 hash — the hash of the tip commit. Creating a branch costs essentially nothing. There are no expensive copies. Two branches can point to the same commit, and diverge only as new commits are added.

The staging area (index): Git has three "areas": the working directory (files on disk), the index/staging area (what the next commit will look like), and the repository (committed objects). git add moves changes from working directory to index. git commit creates a commit object from the index. This three-way design lets you craft precise, logical commits even when your working directory is a mess of half-finished work.

# Look inside Git's object store directly
$ git cat-file -t HEAD          # type of HEAD object → 'commit'
$ git cat-file -p HEAD          # pretty-print commit object
tree 4b825dc642cb6eb9a060e54bf8d69288fbee4904
author Alice <alice@example.com> 1700000000 +0000
committer Alice <alice@example.com> 1700000000 +0000

Initial commit

$ git cat-file -p HEAD^{tree}   # the root tree
100644 blob a8c1...  README.md
040000 tree 3f2e...  src

# A branch is just a file:
$ cat .git/refs/heads/main
3f2e8a9c1b4d7e0f2a5c8b3d6e9f1a4b7c0d3e6f

A commit is a snapshot, not a diff. This is a crucial mental model shift from older systems like SVN (which stored deltas). Git stores the complete tree state at each commit, relying on content-addressing to deduplicate unchanged files (the same blob hash is stored only once regardless of how many commits reference it).

The history of a repository is a DAG of commits. Each commit points to one or more parents:

• Linear history: each commit has exactly one parent
• Merge commit: has two (or more) parents — the tips of the merged branches
• Root commit: no parent (the very first commit)

Because commits are immutable and addressed by content hash, git rebase does not "move" commits — it creates new commit objects with the same changes but different parent pointers (and thus different hashes). This is why rebasing rewrites history: the SHA-1 hashes change even if the diffs are identical.

Reading history: git log --graph --oneline renders the DAG as ASCII art. git diff A B computes the difference between two tree snapshots. git bisect performs a binary search through commit history to find which commit introduced a bug — it checks out the midpoint commit, you test, and it halves the search space. For a project with 1024 commits, bisect finds the culprit in at most 10 steps.

# Visualize the DAG
$ git log --graph --oneline --all
* 7a1b2c3 (HEAD -> main) Fix null pointer in parser
*   5d4e3f2 Merge branch 'feature/auth'
|\  
| * 2f1e0d9 (feature/auth) Add JWT validation
| * 1c2b3a4 Scaffold auth module
* 1a2b3c4 Refactor database layer

# Binary search for a bug
$ git bisect start
$ git bisect bad                  # current commit is broken
$ git bisect good v2.3.0          # this tag was known good
# Git checks out midpoint...
$ make test                        # test it
$ git bisect good                  # or: git bisect bad
# Repeat ~10 times → Git prints the first bad commit

A branch is a movable pointer to a commit. HEAD is a pointer to the current branch (or directly to a commit in "detached HEAD" state). When you commit, the current branch pointer advances to the new commit.

Creating and switching:

git switch -c feature/login   # create + switch
git switch main               # switch back

Three merge strategies:

1. Fast-forward: If the target branch has not diverged from the source, Git simply moves the pointer forward. No merge commit is created. History is linear. Use --no-ff to force a merge commit and preserve branch topology in history.

2. Three-way merge: Git finds the merge base — the most recent common ancestor commit of the two branch tips — and computes two diffs (base→branch-A, base→branch-B). Changes that don't overlap are applied automatically. Overlapping changes to the same lines produce a merge conflict that must be resolved manually.

3. Rebase: Instead of creating a merge commit, replay the commits from one branch on top of another, creating new commit objects. The result is a linear history. The tradeoff: rebase rewrites history (new SHAs), so never rebase commits that have been pushed to a shared branch — it creates a split timeline for other developers.

Cherry-pick: git cherry-pick <sha> applies the diff introduced by a single commit onto the current branch, creating a new commit. Useful for backporting bug fixes to release branches.

# Three-way merge mechanics (pseudocode)
def three_way_merge(base, branch_a, branch_b):
    diff_a = diff(base, branch_a)   # changes in A since common ancestor
    diff_b = diff(base, branch_b)   # changes in B since common ancestor
    conflicts = []
    result = copy(base)
    for change in diff_a + diff_b:
        if not overlaps_with_other_branch(change, diff_a, diff_b):
            apply(result, change)
        else:
            conflicts.append(change)  # human must resolve
    return result, conflicts

# Fast-forward vs merge commit
$ git merge --no-ff feature/login  # always create merge commit
# vs
$ git merge feature/login          # fast-forward if possible

# Rebase feature branch onto updated main
$ git switch feature/login
$ git rebase main
# Replays each commit in feature/login on top of latest main

Git is a distributed VCS: every clone is a full copy of the repository, including complete history. There is no architectural difference between a "server" and a "client" — GitHub/GitLab are just well-known repositories that teams agree to treat as canonical.

Remotes are named references to other repositories:

• origin: the conventional name for the remote you cloned from
• upstream: the conventional name for the original repo when working with forks

Remote-tracking branches like origin/main are local read-only snapshots of where the remote's branches were last time you fetched. They are not automatically updated — git fetch updates them without touching your working directory, while git pull is git fetch followed by git merge (or git rebase with --rebase).

Push/pull mechanics:

• git push origin main: sends local commits to origin, updating origin's main pointer. This is rejected if origin has commits you don't have (non-fast-forward push). You must pull first.
• Force push (--force-with-lease): overwrites remote history. Dangerous on shared branches; acceptable on your own feature branches after a rebase. The --force-with-lease variant refuses to push if someone else has pushed in the meantime.

Forks: In open-source workflows, contributors fork the canonical repository (creating their own copy on GitHub), push changes to their fork, and open a pull request from their fork's branch into the upstream repository. They never have write access to upstream.

# Typical distributed workflow
$ git clone https://github.com/org/repo.git
$ git remote -v
origin  https://github.com/org/repo.git (fetch)
origin  https://github.com/org/repo.git (push)

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

# Keep fork in sync with upstream
$ git fetch upstream
$ git switch main
$ git merge upstream/main      # or: git rebase upstream/main
$ git push origin main

# Safe force push after local rebase
$ git rebase -i origin/main    # interactive rebase to clean up commits
$ git push --force-with-lease origin feature/my-branch

A branching strategy is the team agreement about what branches exist, what they mean, and how code flows between them. Choosing the right strategy is a key software engineering decision that affects release cadence, how quickly developers can integrate work, and the blast radius of bugs.

GitHub Flow (simple, continuous delivery):

• One long-lived branch: main (always deployable)
• Short-lived feature branches cut from main
• PR → review → merge to main → deploy immediately
• Best for: web services deploying many times per day

Gitflow (structured, versioned releases):

• Long-lived: main (production), develop (integration)
• Short-lived: feature/*, release/*, hotfix/*
• Features merge to develop; release branches cut from develop for stabilization; hotfixes cut from main and merged to both main and develop
• Best for: libraries, apps with explicit versioned releases
• Criticism: develop branch often becomes a long-diverging mess; PRs are harder to review; not suited for continuous delivery

Trunk-Based Development (TBD):

• Everyone commits to main (the "trunk") at least once per day
• Feature flags hide incomplete work instead of long-lived branches
• Short-lived branches (< 1 day) are acceptable
• Best for: large teams, high-frequency deployment (Google's Piper, Facebook's monorepo use variants of this)
• Requires strong CI: every commit to trunk must be green

The empirical evidence (DORA metrics, Accelerate research) shows that high-performing teams use trunk-based development with short integration cycles. Long-lived feature branches are correlated with integration pain and lower deployment frequency.

# GitHub Flow in shell commands
$ git switch main && git pull
$ git switch -c feature/add-payment-endpoint
# ... make changes, commit ...
$ git push -u origin feature/add-payment-endpoint
# Open PR on GitHub → review → squash-merge → delete branch

# Gitflow: create a release
$ git switch develop
$ git switch -c release/2.1.0
# Bug fixes only on release branch
$ git switch main
$ git merge --no-ff release/2.1.0
$ git tag -a v2.1.0 -m "Release 2.1.0"
$ git switch develop
$ git merge --no-ff release/2.1.0
$ git branch -d release/2.1.0

# Trunk-based: feature flag hides incomplete work
if feature_flags.enabled('new_checkout_flow', user):
    return new_checkout(cart)
else:
    return legacy_checkout(cart)

A pull request (PR) — called a merge request (MR) in GitLab — is a structured proposal to merge one branch into another. It is not a Git concept; it is a collaboration layer built on top of Git by hosting platforms. A PR bundles together:

1. The diff (what changes)
2. A description (why the change, link to issue/ticket)
3. An automated check suite (CI results)
4. A threaded discussion for review comments
5. An approval gate before merge

Why code review exists: Code review is not about catching every bug (though it helps). Its primary value is knowledge transfer — the reviewer learns what changed and why, reducing bus factor. Secondary values: catching logic errors, enforcing style, discussing design tradeoffs before they are committed to history.

How to give good review:

• Distinguish blocking (must fix) from non-blocking (suggestion) comments
• Review the design first; don't nitpick style if the architecture is wrong
• Be specific: quote the exact line, propose a concrete alternative
• Assume competence; ask questions rather than making accusations
• Review in a reasonable time window (< 24 hours) — slow review is a productivity tax on the author

How to receive review well:

• Keep PRs small (< 400 lines of diff is a common heuristic; smaller is better)
• Write a clear description; link to the issue; explain non-obvious decisions
• Respond to every comment; resolve threads after addressing them
• Don't take comments personally — the reviewer is reviewing the code, not you

Merge strategies: squash (collapse all PR commits into one clean commit on main — good for feature branches with messy WIP commits), merge commit (preserve all PR commits with a merge commit — good when commit granularity matters), rebase (replay commits linearly without a merge commit — keeps history clean but loses branch topology).

# Good PR description template (markdown)
## What
Add rate limiting middleware to the API gateway.
Fixes #482.

## Why
Without rate limiting, a single client can exhaust DB connection pool.
Load tests showed 500 errors at 200 req/s from one source.

## How
- Added `RateLimiter` class using token-bucket algorithm (src/middleware/rate_limit.py)
- Configured: 100 req/min per IP, 1000 req/min per API key
- Returns 429 with Retry-After header on breach

## Testing
- Unit tests: tests/test_rate_limit.py (22 new tests)
- Load test: `locust -f tests/locustfile.py` — no 500s at 500 req/s

## Checklist
- [x] Tests added
- [x] Docs updated
- [x] No breaking API changes

Continuous Integration is the practice of automatically building and testing every proposed code change. The canonical formulation (Martin Fowler, 2006): "everyone integrates frequently — at least daily — and each integration is verified by an automated build to detect errors as quickly as possible."

A CI pipeline is a sequence of automated stages triggered by a push or pull request:

1. Checkout: fetch the code
2. Install dependencies: pip install / npm install / etc.
3. Lint / static analysis: catch style violations and obvious bugs before tests
4. Compile/build: fail fast if the code doesn't even compile
5. Unit tests: fast, isolated tests (~seconds)
6. Integration tests: slower tests involving databases, services (~minutes)
7. Security scan: dependency vulnerability scanning (Snyk, Dependabot)
8. Code coverage gate: fail if coverage drops below threshold
9. Build artifact: produce a deployable container image, binary, or package

Why CI matters: Without CI, integration bugs accumulate on long-lived branches and explode at merge time ("integration hell"). CI makes integration continuous and cheap. The cost of fixing a bug caught by CI is a fraction of the cost of fixing the same bug after deployment.

CI platforms: GitHub Actions (.github/workflows/*.yml), GitLab CI (.gitlab-ci.yml), Jenkins, CircleCI, Buildkite. All share the same model: YAML config file in the repo defines stages and steps; pushes trigger pipeline runs; results are posted back to the PR.

The fast-feedback principle: Stages should be ordered cheapest-first. If lint fails in 5 seconds, there is no point running a 10-minute test suite. Fail fast.

# .github/workflows/ci.yml  (GitHub Actions)
name: CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install dependencies
        run: pip install -e '.[dev]'

      - name: Lint
        run: ruff check src/ tests/

      - name: Type check
        run: mypy src/

      - name: Run tests with coverage
        run: pytest --cov=src --cov-fail-under=85

      - name: Security scan
        run: pip-audit

Continuous Delivery (CD) extends CI: every change that passes CI is automatically made releasable — i.e., a deployable artifact is produced and staged, requiring one manual approval click to go to production. Continuous Deployment goes further: every passing build deploys to production automatically, with no manual gate.

The distinction matters: Continuous Deployment requires high confidence in your test suite and monitoring. Continuous Delivery is more common in regulated or enterprise settings where a human sign-off is required before production.

Deployment pipeline stages:

1. CI (as above)
2. Build artifact: Docker image pushed to registry, versioned with the commit SHA
3. Deploy to staging: identical to production environment
4. Smoke tests / integration tests on staging
5. Deploy to production (automatic in CD, manual click in delivery)
6. Post-deploy monitoring: error rates, latency SLOs watched

Deployment strategies:

• Blue-green: two identical production environments; switch traffic from blue to green atomically. Rollback = switch back.
• Canary: route 1-5% of traffic to new version; watch metrics; gradually increase or rollback.
• Feature flags: deploy code to 100% of servers but enable features for a small percentage of users. Decouples deployment from release.

DORA metrics (from the Accelerate research, Forsgren et al.) measure delivery performance: Deployment Frequency, Lead Time for Changes, Change Failure Rate, and Time to Restore Service. High performers deploy multiple times per day with < 1 hour lead time.

# Simplified CD pipeline extension in GitHub Actions
  deploy-staging:
    needs: test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4

      - name: Build Docker image
        run: |
          docker build -t myapp:${{ github.sha }} .
          docker push registry.example.com/myapp:${{ github.sha }}

      - name: Deploy to staging
        run: |
          kubectl set image deployment/myapp \
            app=registry.example.com/myapp:${{ github.sha }} \
            --namespace=staging

      - name: Run smoke tests
        run: pytest tests/smoke/ --base-url=https://staging.example.com

  deploy-production:
    needs: deploy-staging
    environment:
      name: production   # requires manual approval in GitHub
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to production
        run: |
          kubectl set image deployment/myapp \
            app=registry.example.com/myapp:${{ github.sha }} \
            --namespace=production

A well-maintained commit history is a first-class engineering artifact. Every commit message is a message to a future engineer — often yourself, six months from now — explaining not just what changed but why. Bad commit messages (fix, stuff, wip) are one of the most common sources of lost institutional knowledge.

The Conventional Commits standard (widely adopted):

<type>(<scope>): <short summary>

<body: explain why, not what>

<footer: breaking changes, issue references>

Types: feat, fix, docs, style, refactor, test, chore, perf, ci.

Atomic commits: each commit should represent one logical change that leaves the codebase in a working state. This enables git bisect, selective cherry-picking, and readable history. If you refactor AND add a feature in one commit, the history is harder to understand and bisect.

Interactive rebase (git rebase -i) lets you rewrite local, unpushed history before sharing it: reorder commits, squash WIP commits into logical units, edit commit messages, drop commits. It is the tool for making messy exploratory work into clean, reviewable history.

Signed commits: git commit -S signs commits with a GPG or SSH key, proving authorship. GitHub shows a "Verified" badge. Important for open-source projects to prevent commit forgery.

# Good commit message
feat(auth): add JWT expiry validation

Previously, expired tokens were accepted silently because the
decoding step only checked signature, not the `exp` claim.

Added `validate_expiry()` in src/auth/jwt.py. Raises
`TokenExpiredError` (HTTP 401) with a `WWW-Authenticate` header
so clients know to refresh rather than re-login.

Closes #217
Breaking change: clients must handle 401 on previously-valid tokens

# Interactive rebase: clean up 5 messy commits before PR
$ git rebase -i HEAD~5
# Editor opens:
pick a1b2c3d feat: scaffold auth module
squash b2c3d4e wip: half-done validation  # squash into prev
squash c3d4e5f fix typo                   # squash into prev
pick d4e5f6a test: add JWT unit tests
reword e5f6a7b docs: update readme        # edit message

Technical debt is a metaphor introduced by Ward Cunningham (1992): code that is not quite right — written quickly to meet a deadline — is like a financial debt. It accrues "interest" in the form of extra effort required to understand, modify, and extend it. Left unmanaged, interest payments eventually exceed the cost of actual feature work.

Sources of technical debt:

• Deliberate, prudent: "We know this is not ideal; we'll fix it after launch." The only acceptable form — must be tracked.
• Deliberate, reckless: "We don't have time for tests." Unprofessional.
• Inadvertent, prudent: "Now we know the right design." Normal; discovered through experience.
• Inadvertent, reckless: "What's layering?" Ignorance-driven.

Technical debt in version control:

• Commit history reveals debt: files with many churn cycles (high change frequency relative to size) are debt hotspots
• git log --follow -p -- src/legacy_module.py shows the full life story of a file
• Tools like git log --stat | grep 'changed' or external tools (CodeClimate, SonarQube) quantify hotspots
• PRs are the opportunity to pay down debt incrementally: the Boy Scout Rule — "leave the campground cleaner than you found it"

Refactoring strategy: Never refactor and add features in the same commit (or PR, ideally). Separate the "change the structure" commit from the "add behavior" commit. This makes the refactoring trivially verifiable (tests pass before and after, diff is pure restructuring) and the feature addition small and focused.

Tracking debt: TODO, FIXME, HACK, XXX comments in code are informal debt markers. Teams often create tickets for significant debt items so they compete honestly with feature work in sprint planning.

# Find debt hotspots: files changed most frequently
$ git log --format=format: --name-only \
  | grep -v '^$' \
  | sort \
  | uniq -c \
  | sort -rg \
  | head -20

# Output (fictional):
 142 src/billing/invoice.py     # changed 142 times — debt hotspot
  98 src/legacy/data_mapper.py
  87 src/api/routes.py

# Track deliberate debt in code
def process_payment(order):
    # TODO(#482): Replace with idempotent payment processor.
    # Currently, network retry can charge user twice.
    # Deadline workaround: check duplicate_charge table first.
    if is_duplicate(order.idempotency_key):
        return cached_result(order.idempotency_key)
    return _charge(order)

A monorepo stores multiple projects (services, libraries, tools) in a single repository. A polyrepo gives each project its own repository. This is one of the most consequential — and contentious — architectural decisions in software engineering infrastructure.

Monorepo advantages:

• Atomic cross-project changes: rename an API and update all callers in one commit, one PR, one review
• Unified CI: a single pipeline can verify that a library change doesn't break any downstream consumers
• Simplified dependency management: all projects use the same version of internal libraries — no version skew
• Shared tooling: linters, formatters, build systems configured once
• Adopted by: Google (Piper, ~2 billion lines of code), Meta (fbsource), Twitter, Stripe

Polyrepo advantages:

• Independent deployment: teams own their release cadence without coordination
• Simpler access control: different teams have write access to different repos
• Smaller cognitive footprint: a new engineer only needs to understand one service
• Native Git performance: Git scales poorly to very large repos (Google built Piper and Virtual Filesystem for Git (VFS4G) to work around this)

The tooling gap: Monorepos require specialized build tooling (Bazel, Nx, Turborepo) that understands dependency graphs and only rebuilds/retests what changed. npm install in a monorepo with 200 packages is expensive without caching; Bazel uses content-addressed caching to make incremental builds fast.

The empirical evidence leans toward monorepos for tightly-coupled systems, polyrepos for truly independent microservices. Many large companies run hybrid approaches.

# Monorepo structure (Nx / turborepo style)
my-org/
  apps/
    web/          # Next.js frontend
    api/          # Express backend
    mobile/       # React Native
  packages/
    ui/           # shared React component library
    auth/         # shared auth utilities
    types/        # shared TypeScript types
  turbo.json      # build graph configuration
  package.json    # root workspace

# turbo.json: define task dependency graph
{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],  # build deps first
      "outputs": ["dist/**"]
    },
    "test": {
      "dependsOn": ["build"]
    }
  }
}

# Run only what changed since last commit:
$ turbo run test --filter='...[HEAD^1]'