Version Control with Git Fundamentals

"Whoever can be trusted with very little can also be trusted with much, and whoever is dishonest with very little will also be dishonest with much." — Luke 16:10

The Discipline of Careful Record-Keeping

In ancient Israel, scribes meticulously copied Scripture letter by letter, counting every character to ensure perfect accuracy. They kept records so carefully that manuscripts separated by centuries were nearly identical. This discipline of precise record-keeping preserved God's Word across millennia.

Git is the software engineer's tool for meticulous record-keeping. It is a version control system — software that tracks every change you make to your code, who made it, when it was made, and why. Like a scribe's careful copying, Git preserves the complete history of a project so that nothing is ever truly lost.

Why Version Control Matters

Imagine writing a ten-page essay and accidentally deleting three paragraphs. Without version control, those paragraphs are gone. With Git, you can instantly restore any previous version of your work.

Now multiply that by a team of ten engineers working on the same codebase simultaneously. Without version control, they would overwrite each other's work constantly. With Git, each engineer works independently, and their changes are merged together systematically.

Git provides four essential capabilities:

1. History: Every change is recorded. You can see exactly what changed, when, and why.
2. Undo: Made a mistake? Roll back to any previous state.
3. Collaboration: Multiple people work on the same project without conflicts.
4. Branching: Experiment with new ideas without affecting the stable version.

Core Git Concepts

The Repository

A repository (or "repo") is a project folder that Git is tracking. When you "initialize" a Git repo, Git creates a hidden `.git/` folder inside your project that stores the entire history.

```bash

Turn your project into a Git repository

cd academy-first-project-chirho git init ```

After `git init`, Git is watching this directory. But it is not tracking any files yet — you must explicitly tell Git which files to track.

The Three States of a File

Every file in a Git repository exists in one of three states:

1. Modified: You changed the file, but Git has not recorded the change yet.
2. Staged: You told Git to include this change in the next commit.
3. Committed: The change is safely stored in Git's history.

Think of it like sending a letter:

• Modified = you wrote the letter
• Staged = you put it in an envelope (ready to send)
• Committed = you mailed it (permanently recorded)

Basic Git Commands

```bash

Check the status of your repository — what has changed?

git status

Stage a specific file (put it in the envelope)

git add index.ts

Stage ALL changed files

git add .

Commit staged changes with a message (mail the letter)

git commit -m "Add greeting program with Proverbs 1:7"

View the history of commits

git log

View a compact, one-line-per-commit history

git log --oneline

See what changed in a file since the last commit

git diff index.ts ```

Writing Good Commit Messages

A commit message explains why you made a change. Future you — or a teammate — will read this message to understand the project's history. Bad commit messages are like unlabeled boxes in a warehouse: technically stored, but practically useless.

Bad commit messages:

• "fix stuff"
• "asdf"
• "changes"
• "updated files"

Good commit messages:

• "Add input validation for user registration form"
• "Fix off-by-one error in pagination calculation"
• "Refactor database queries to reduce response time"

A good commit message:

1. Starts with a verb in the imperative mood: "Add," "Fix," "Refactor," "Remove"
2. Is specific: explains what changed and (briefly) why
3. Is concise: ideally under 72 characters for the first line
4. Adds detail below (optional): a blank line followed by a longer explanation if needed

Branching — Safe Experimentation

A branch in Git is like a parallel universe for your code. You can create a branch, make experimental changes, and if the experiment fails, simply delete the branch. The original code remains untouched.

```bash

Create a new branch and switch to it

git checkout -b feature-prayer-journal-chirho

List all branches (* marks the current one)

git branch

Switch back to the main branch

git checkout main

Merge a branch's changes into the current branch

git merge feature-prayer-journal-chirho

Delete a branch after merging

git branch -d feature-prayer-journal-chirho ```

The main branch (often called `main`) is the stable, production-ready version of your code. You should never make experimental changes directly on `main`. Instead:

1. Create a new branch for each feature or fix
2. Make your changes on the branch
3. Test thoroughly
4. Merge the branch back into `main` when it is ready
5. Delete the branch

This workflow protects the stable version while allowing free experimentation.

A Complete Git Workflow Example

Let us walk through a realistic workflow:

```bash

1. Start on the main branch

git checkout main

2. Create a feature branch

git checkout -b feature-add-verse-display-chirho

3. Make changes to your code

(edit files in your code editor)

4. Check what changed

git status git diff

5. Stage your changes

git add src/verse-display-chirho.ts

6. Commit with a clear message

git commit -m "Add verse display component with Proverbs 1:7"

7. Switch back to main

git checkout main

8. Merge your feature

git merge feature-add-verse-display-chirho

9. Clean up the branch

git branch -d feature-add-verse-display-chirho

10. View the history

git log --oneline ```

Common Mistakes and How to Avoid Them

Mistake 1: Committing too infrequently. If you work for eight hours and make one giant commit, you cannot undo individual changes. Commit small, logical units of work — one feature, one fix, one refactor at a time.

Mistake 2: Vague commit messages. "Update code" tells you nothing six months later. Be specific.

Mistake 3: Committing secrets. API keys, passwords, and tokens in your Git history are visible to anyone with access to the repository. Use `.gitignore` (as we learned yesterday) and environment variables.

Mistake 4: Working directly on main. Always create a branch for new work. This protects your stable code and makes collaboration possible.

A Thought to Carry

"Be sure you know the condition of your flocks, give careful attention to your herds" (Proverbs 27:23). A shepherd who does not keep track of his sheep will lose them. An engineer who does not keep track of code changes will lose work, introduce bugs, and create chaos. Git is the shepherd's crook of the software engineer — use it faithfully.