Skip to content

Commit c8d75a5

Browse files
brabojclaude
andcommitted
docs: improve thin recipes in rebasing, stashing, and submodules
Add context, explanations, and tips to 6 recipes that were bare commands without enough context for beginners. Closes #154 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 18b7e20 commit c8d75a5

3 files changed

Lines changed: 35 additions & 7 deletions

File tree

chapters/recipes/rebasing.md

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,17 +16,29 @@ $ git rebase main
1616

1717
### Squash commits with interactive rebase
1818

19+
Squashing combines multiple commits into one, keeping history clean
20+
before merging a feature branch.
21+
1922
```text
2023
$ git rebase -i HEAD~3
21-
# change "pick" to "squash" for commits to combine
24+
# editor opens — change "pick" to "squash" (or "s") for commits to fold
25+
# save and close — a second editor opens to combine the messages
2226
```
2327

28+
If conflicts arise during the squash, resolve them and run
29+
`git rebase --continue`.
30+
2431
### Abort a conflicted rebase
2532

33+
Restores the branch to its exact state before the rebase started.
34+
Use this when conflicts are too tangled to resolve cleanly.
35+
2636
```text
2737
$ git rebase --abort
2838
```
2939

40+
Any conflict resolutions you made during the rebase are discarded.
41+
3042
### Continue after resolving a rebase conflict
3143

3244
```text

chapters/recipes/stashing.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,16 @@ order: 77
99

1010
### Save work in progress
1111

12+
Stashing saves your modified and staged files without creating a
13+
commit — useful when you need to switch branches mid-task.
14+
1215
```text
1316
$ git stash push -m "description"
1417
```
1518

19+
Without `-m`, Git generates a message from the current HEAD commit,
20+
which makes it harder to find the right stash later.
21+
1622
### Save including untracked files
1723

1824
```text
@@ -28,8 +34,14 @@ $ git stash apply # restore but keep in stash
2834

2935
### List and drop stash entries
3036

37+
Entries are numbered starting at 0 (most recent). Use the
38+
`stash@{N}` syntax to target a specific entry.
39+
3140
```text
3241
$ git stash list # show all entries
3342
$ git stash drop stash@{0} # delete a specific entry
3443
$ git stash clear # delete all entries
3544
```
45+
46+
`stash@{0}` is always the latest stash. After dropping an entry,
47+
the remaining entries are renumbered.

chapters/recipes/submodules.md

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -9,11 +9,18 @@ order: 79
99

1010
### Add a submodule
1111

12+
A submodule embeds an external repository at a fixed commit inside
13+
your project. Use submodules when you need to track an upstream
14+
library or shared component while keeping its history separate.
15+
1216
```text
1317
$ git submodule add <url> <path>
1418
$ git commit -m "Add submodule"
1519
```
1620

21+
This creates a `.gitmodules` file (or appends to it) and records the
22+
pinned commit in the index.
23+
1724
### Clone a repo with submodules
1825

1926
```text
@@ -36,9 +43,6 @@ $ git commit -m "Update submodule"
3643

3744
### Remove a submodule
3845

39-
```text
40-
$ git submodule deinit <path>
41-
$ git rm <path>
42-
$ rm -rf .git/modules/<path>
43-
$ git commit -m "Remove submodule"
44-
```
46+
See [Remove a Submodule](remove-submodule.md) for a full
47+
walkthrough — the three cleanup steps, what each does, and common
48+
gotchas.

0 commit comments

Comments
 (0)