Skip to content

Commit edc6353

Browse files
brabojclaude
andcommitted
feat: add 6 new playbook recipe pages
Add recipes for subtrees, hooks, remote management, diffing, history, and selectors — covering all Git commands taught in the tutorial that were missing from the playbook. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent c45ab59 commit edc6353

7 files changed

Lines changed: 394 additions & 3 deletions

File tree

chapters/playbook/diffing.md

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
title: "Diffing"
3+
description: "Git recipes for comparing unstaged changes, staged changes, branches, commits, and specific files."
4+
section: "playbook/diffing"
5+
order: 85
6+
---
7+
8+
## Diffing
9+
10+
### Show unstaged changes
11+
12+
```text
13+
$ git diff
14+
```
15+
16+
Compares working tree against the index (staged snapshot).
17+
18+
### Show staged changes
19+
20+
```text
21+
$ git diff --staged
22+
```
23+
24+
Compares the index against the last commit — shows what will go into
25+
the next commit.
26+
27+
### Compare two branches
28+
29+
```text
30+
$ git diff main feature/name
31+
```
32+
33+
Shows all differences between the tips of both branches.
34+
35+
### Compare two commits
36+
37+
```text
38+
$ git diff abc1234 def5678
39+
```
40+
41+
### Show changes introduced by a single commit
42+
43+
```text
44+
$ git diff HEAD~1 HEAD
45+
```
46+
47+
Or use `git show` for the same result with commit metadata:
48+
49+
```text
50+
$ git show HEAD
51+
```
52+
53+
### Diff a specific file
54+
55+
```text
56+
$ git diff -- path/to/file
57+
$ git diff --staged -- path/to/file
58+
```
59+
60+
### Diff with statistics only
61+
62+
```text
63+
$ git diff --stat main feature/name
64+
```
65+
66+
Shows a summary of changed files and line counts without the full
67+
patch.

chapters/playbook/history.md

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
title: "History"
3+
description: "Git recipes for viewing, formatting, and filtering commit history — log output, author filters, date ranges, and path-based searches."
4+
section: "playbook/history"
5+
order: 86
6+
---
7+
8+
## History
9+
10+
### Compact one-line log
11+
12+
```text
13+
$ git log --oneline
14+
```
15+
16+
### Graph view with branches
17+
18+
```text
19+
$ git log --oneline --graph --all
20+
```
21+
22+
Shows the full branch topology in ASCII art.
23+
24+
### Filter by author
25+
26+
```text
27+
$ git log --author="Branko" --oneline
28+
```
29+
30+
Matches against the author name or email. Supports regex.
31+
32+
### Filter by date range
33+
34+
```text
35+
$ git log --after="2025-01-01" --before="2025-06-30" --oneline
36+
```
37+
38+
### Filter by file path
39+
40+
```text
41+
$ git log -- path/to/file --oneline
42+
```
43+
44+
Shows only commits that modified the specified file.
45+
46+
### Custom format
47+
48+
```text
49+
$ git log --format="%h %an %s" -10
50+
```
51+
52+
Common placeholders: `%h` (short hash), `%an` (author name),
53+
`%s` (subject), `%ar` (relative date), `%d` (refs).
54+
55+
### Show changes in each commit
56+
57+
```text
58+
$ git log -p -3
59+
```
60+
61+
Combines log output with the full diff for the last 3 commits.
62+
63+
### Count commits per author
64+
65+
```text
66+
$ git shortlog -sn
67+
```
68+
69+
Useful for understanding contribution distribution.

chapters/playbook/hooks.md

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
title: "Hooks"
3+
description: "Git recipes for creating pre-commit and commit-msg hooks, sharing hooks across a team, and bypassing hooks when needed."
4+
section: "playbook/hooks"
5+
order: 83
6+
---
7+
8+
## Hooks
9+
10+
### Create a pre-commit hook
11+
12+
```text
13+
$ cat > .git/hooks/pre-commit << 'EOF'
14+
#!/bin/sh
15+
# Reject commits that contain TODO
16+
if git diff --cached --quiet -S "TODO"; then
17+
exit 0
18+
fi
19+
echo "Error: commit contains TODO"
20+
exit 1
21+
EOF
22+
$ chmod +x .git/hooks/pre-commit
23+
```
24+
25+
The hook runs before every commit. A non-zero exit code aborts the
26+
commit.
27+
28+
### Create a commit-msg hook
29+
30+
```text
31+
$ cat > .git/hooks/commit-msg << 'EOF'
32+
#!/bin/sh
33+
# Enforce minimum message length
34+
if [ $(wc -c < "$1") -lt 10 ]; then
35+
echo "Error: commit message too short"
36+
exit 1
37+
fi
38+
EOF
39+
$ chmod +x .git/hooks/commit-msg
40+
```
41+
42+
Receives the commit message file as `$1`. Useful for enforcing
43+
message conventions.
44+
45+
### Share hooks with the team
46+
47+
```text
48+
$ mkdir .githooks
49+
$ cp .git/hooks/pre-commit .githooks/
50+
$ git config core.hooksPath .githooks
51+
$ git add .githooks/
52+
$ git commit -m "Add shared hooks"
53+
```
54+
55+
Everyone who clones the repo runs `git config core.hooksPath .githooks`
56+
to activate the shared hooks.
57+
58+
### Bypass a hook
59+
60+
```text
61+
$ git commit --no-verify -m "WIP: skip hooks"
62+
$ git push --no-verify
63+
```
64+
65+
Use sparingly — hooks exist for a reason.

chapters/playbook/index.md

Lines changed: 29 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,18 +14,44 @@ and what to watch out for.
1414
For command syntax, see [Appendix](../08-appendix.md). For definitions,
1515
see [Glossary](../09-glossary.md).
1616

17-
## Recipes
17+
## Everyday
1818

1919
| Recipe | What you'll find |
2020
|--------|-----------------|
2121
| [Undoing Changes](undoing-changes.md) | Discard, unstage, reset, revert, and recover lost commits |
22+
| [Diffing](diffing.md) | Unstaged, staged, between branches, commits, and files |
23+
| [History](history.md) | Log formatting, filtering by author, date, and path |
24+
| [Stashing](stashing.md) | Save and restore work in progress |
25+
26+
## Branching and Merging
27+
28+
| Recipe | What you'll find |
29+
|--------|-----------------|
2230
| [Branching](branching.md) | Create, delete, rename, and inspect branches |
2331
| [Merging](merging.md) | Fast-forward, no-ff, squash, conflict resolution |
2432
| [Rebasing](rebasing.md) | Linearize history and squash commits interactively |
25-
| [Remote Operations](remote-operations.md) | Push, pull, force push safely, sync forks |
2633
| [Cherry-Picking](cherry-picking.md) | Apply individual commits across branches |
27-
| [Stashing](stashing.md) | Save and restore work in progress |
34+
35+
## Remote
36+
37+
| Recipe | What you'll find |
38+
|--------|-----------------|
39+
| [Remote Operations](remote-operations.md) | Push, pull, force push safely, sync forks |
40+
| [Remote Management](remote-management.md) | Add, rename, remove remotes, switch URL, SSH setup |
41+
42+
## Project Structure
43+
44+
| Recipe | What you'll find |
45+
|--------|-----------------|
2846
| [Tagging](tagging.md) | Create, push, and delete annotated tags |
2947
| [Submodules](submodules.md) | Add, clone, update, and remove submodules |
48+
| [Subtrees](subtrees.md) | Add, pull, push, and remove subtrees |
49+
50+
## Advanced
51+
52+
| Recipe | What you'll find |
53+
|--------|-----------------|
54+
| [Selectors](selectors.md) | Tilde, caret, double-dot, triple-dot, reflog refs |
55+
| [Hooks](hooks.md) | Pre-commit, commit-msg, sharing hooks, bypassing |
3056
| [Debugging](debugging.md) | Bisect, blame, and search commit history |
3157
| [Configuration](configuration.md) | Identity, defaults, aliases, and diagnostics |
Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
title: "Remote Management"
3+
description: "Git recipes for adding, renaming, and removing remotes, switching remote URLs, and setting up SSH authentication."
4+
section: "playbook/remote-management"
5+
order: 84
6+
---
7+
8+
## Remote Management
9+
10+
### List remotes
11+
12+
```text
13+
$ git remote -v
14+
```
15+
16+
Shows all configured remotes with their fetch and push URLs.
17+
18+
### Add a remote
19+
20+
```text
21+
$ git remote add upstream <url>
22+
```
23+
24+
Common when working with forks — `origin` is your fork, `upstream`
25+
is the original repository.
26+
27+
### Rename a remote
28+
29+
```text
30+
$ git remote rename origin old-origin
31+
```
32+
33+
### Remove a remote
34+
35+
```text
36+
$ git remote remove upstream
37+
```
38+
39+
Also removes all remote-tracking branches for that remote.
40+
41+
### Switch a remote URL (HTTPS to SSH)
42+
43+
```text
44+
$ git remote set-url origin git@github.com:<user>/<repo>.git
45+
```
46+
47+
### Set up SSH authentication
48+
49+
```text
50+
$ ssh-keygen -t ed25519 -C "you@example.com"
51+
$ eval "$(ssh-agent -s)"
52+
$ ssh-add ~/.ssh/id_ed25519
53+
$ ssh -T git@github.com # verify connection
54+
```
55+
56+
Add the public key (`~/.ssh/id_ed25519.pub`) to your GitHub account
57+
under Settings > SSH Keys.

chapters/playbook/selectors.md

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
---
2+
title: "Selectors"
3+
description: "Git recipes for navigating history with tilde, caret, double-dot, triple-dot, and reflog selectors."
4+
section: "playbook/selectors"
5+
order: 87
6+
---
7+
8+
## Selectors
9+
10+
### Navigate to a parent commit (tilde)
11+
12+
```text
13+
$ git show HEAD~1 # parent
14+
$ git show HEAD~3 # great-grandparent
15+
```
16+
17+
Tilde follows the first-parent chain. `HEAD~3` means "go back 3
18+
commits along the first parent."
19+
20+
### Select a specific parent (caret)
21+
22+
```text
23+
$ git show HEAD^1 # first parent
24+
$ git show HEAD^2 # second parent (merge commits)
25+
```
26+
27+
Caret selects which parent of a merge commit to follow. Only
28+
meaningful on merge commits — `^1` and `^2` differ.
29+
30+
### Combine tilde and caret
31+
32+
```text
33+
$ git show HEAD~1^2 # second parent of the previous commit
34+
```
35+
36+
### Commits on one branch but not another (double-dot)
37+
38+
```text
39+
$ git log main..feature --oneline
40+
```
41+
42+
Shows commits reachable from `feature` that are not reachable from
43+
`main` — what would be merged.
44+
45+
### Symmetric difference (triple-dot)
46+
47+
```text
48+
$ git log --left-right main...feature --oneline
49+
```
50+
51+
Shows commits on either branch but not both. The `--left-right`
52+
flag marks each commit with `<` (left) or `>` (right).
53+
54+
### Reflog selectors
55+
56+
```text
57+
$ git show HEAD@{1} # previous position of HEAD
58+
$ git show main@{yesterday} # where main was yesterday
59+
$ git show HEAD@{2.hours.ago} # HEAD two hours ago
60+
```
61+
62+
Reflog entries expire after 90 days (reachable) or 30 days
63+
(unreachable) by default.

0 commit comments

Comments
 (0)