git-workshop/01-essentials/02-history/README.md

# Module 02: Viewing History

## Learning Objectives

In this module, you will:
- Understand commit history and how to navigate it
- Use `git log` to view commit history with various formats
- Use `git show` to view specific commit details
- Use `git diff` to compare changes between commits
- Use `git diff --staged` to view changes ready to be committed
- Understand commit hashes and references
- Discover how `git diff` reveals changes not visible in current files

## Challenge

### Setup

Run the setup script to create your challenge environment:

```powershell
.\setup.ps1
```

This will create a `challenge/` directory with a Git repository that already has some commit history.

### Your Task

You'll explore an existing Git repository that contains multiple commits. Your goal is to use Git commands to discover information about the repository's history, including:
- Viewing commit history
- Examining changes between specific commits
- Understanding staged changes
- **Finding a secret code hidden in the commit history!** (Only discoverable by using `git diff`)

The setup script will create an `answers.md` file in the challenge directory with questions for you to answer. Fill in your answers directly in that file.

**Suggested Approach:**

1. Navigate to the challenge directory: `cd challenge`
2. Open `answers.md` to see the questions
3. View the commit history: `git log` or `git log --oneline`
4. Check repository status: `git status`
5. View staged changes: `git diff --staged`
6. Try different log formats: `git log --stat`, `git log --graph`
7. View specific commits: `git show <commit-hash>`
8. Compare specific commits: `git diff <commit1> <commit2> <file>`
9. Fill in your answers in `answers.md`
10. Remember to save `answers.md`

> **Important Notes:**
> - You can use any Git commands you like to explore the repository
> - Fill in your answers directly in the `answers.md` file (there are placeholder sections for each answer)
> - Commit hashes can be referenced by their full hash or just the first 7 characters
> - Notice that one file is already staged - use `git diff --staged` to see what it contains

## Key Concepts

- **Commit Hash**: A unique identifier (SHA-1 hash) for each commit. You can use the full hash or just the first few characters.
- **Commit Message**: A description of what changed in that commit, written by the author.
- **Commit History**: The chronological record of all changes made to a repository.
- **HEAD**: A pointer to the current commit you're working from.
- **Diff**: A view showing the differences between two versions of files.
- **Staging Area**: Where changes wait before being committed. Use `git diff --staged` to see what's ready to commit.
- **Working Directory vs Staged vs Committed**:
  - Working Directory: Files you're currently editing
  - Staged (Index): Changes marked for the next commit (via `git add`)
  - Committed: Changes permanently saved in history

## Understanding Diff Output

When you run `git diff` between commits, the output can look confusing at first. Here's how to read it:

### Example Diff Output

```diff
diff --git a/app.py b/app.py
index 1a2b3c4..5d6e7f8 100644
--- a/app.py
+++ b/app.py
@@ -1,5 +1,7 @@
 # app.py - Main application file
+from auth import login, logout

 def main():
     print("Welcome to My App!")
-    # Application initialization code here
+    login("user", "password")
     pass
```

### Breaking It Down

**1. File Header**
```diff
diff --git a/app.py b/app.py
```
- Shows which file is being compared
- `a/app.py` = old version (before)
- `b/app.py` = new version (after)

**2. Metadata**
```diff
index 1a2b3c4..5d6e7f8 100644
--- a/app.py
+++ b/app.py
```
- `---` indicates the old version
- `+++` indicates the new version
- The hashes (1a2b3c4, 5d6e7f8) are internal Git identifiers

**3. Change Location (Hunk Header)**
```diff
@@ -1,5 +1,7 @@
```
- `@@ -1,5 +1,7 @@` tells you where changes occurred
- `-1,5` = in the old file, starting at line 1, showing 5 lines
- `+1,7` = in the new file, starting at line 1, showing 7 lines
- The file grew by 2 lines (from 5 to 7)

**4. The Actual Changes**

Lines are prefixed with symbols:
- ` ` (space) = unchanged line (context)
- `-` (minus) = line removed from old version (shown in red in terminal)
- `+` (plus) = line added in new version (shown in green in terminal)

In our example:
```diff
 # app.py - Main application file          ← unchanged
+from auth import login, logout             ← added (new)

 def main():                                ← unchanged
     print("Welcome to My App!")            ← unchanged
-    # Application initialization code here ← removed (old)
+    login("user", "password")              ← added (new)
     pass                                   ← unchanged
```

### Reading Multiple Files

If multiple files changed, you'll see multiple diff sections:

```diff
diff --git a/app.py b/app.py
[changes to app.py]

diff --git a/auth.py b/auth.py
[changes to auth.py]
```

### Pro Tips

- **Context lines**: Unchanged lines around changes help you understand where the change happened
- **Color coding**: In your terminal, deletions are usually red, additions are green
- **No newline warning**: If you see `\ No newline at end of file`, it means the file doesn't end with a newline character (usually not important for beginners)
- **Binary files**: For images or other binary files, Git just says "Binary files differ"

### Try It Yourself

In this module's challenge, you'll use:
```bash
# See what's staged for the next commit
git diff --staged

# Compare changes between specific commits
git diff <commit2> <commit4> app.py
```

Pay attention to:
- Which lines were added (green, with `+`)
- Which lines were removed (red, with `-`)
- The surrounding context (white, with space)
- How `git diff --staged` shows only changes ready to commit

## Useful Commands

### Viewing History

```bash
git log                      # View commit history
git log --oneline            # Compact one-line format
git log --stat               # Show files changed in each commit
git log --graph              # Show branch graph (more useful with branches)
git show <commit>            # View specific commit details
git show <commit>:<file>     # View a file from a specific commit
```

### Comparing Changes with git diff

```bash
# Compare commits
git diff <commit1> <commit2>        # Compare two commits
git diff <commit1> <commit2> <file> # Compare specific file between commits
git diff <commit>                   # Compare commit with current working directory

# Compare staged changes
git diff --staged               # Show changes in staging area (ready to commit)
git diff --cached               # Same as --staged (alternative syntax)
git diff                        # Show unstaged changes in working directory
git diff HEAD                   # Show all changes (staged + unstaged) vs last commit
```

**When to use each `git diff` variant:**
- `git diff` - See what you've changed but haven't staged yet
- `git diff --staged` - Review what you're about to commit
- `git diff HEAD` - See all your changes since the last commit
- `git diff <commit1> <commit2>` - Compare any two points in history

## Verification

Once you've filled in your answers in `answers.md`, verify your solution:

```powershell
.\verify.ps1
```

The verification script will check that your answers contain the expected information.

## Need to Start Over?

If you want to reset the challenge and start fresh:

```powershell
.\reset.ps1
```

This will remove the challenge directory and run the setup script again, giving you a clean slate.