Hard restore with X drops staged pins at every depth

X restores the selection to the committed pins without the staged or
committed question, and resets every restored repository's index to
HEAD, so staged pins below are dropped too. Dropped staged pins alone
don't make it ask; they are listed if something else is lost.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/README.md

@@ -33,7 +33,8 @@ Installs `submarine` and the alias `sub` (linux/macOS, amd64/arm64) to
 through a git provider (`internal/submodule/git`): `submarine [dir]`. It
 fetches only when asked (`f`) and follows changes made in other shells. `submarine --mock` shows
 the built-in mock data (`internal/submodule/mock`). `!` shows only
-submodules with problems. `x` restores the selection, `b` switches its
+submodules with problems. `x` restores the selection (`X` also drops
+staged pins), `b` switches its
 branch and `u` updates a pin that is behind ([actions.md](actions.md)).
 
 Next steps, roughly in order:

docs/actions.md

@@ -1,6 +1,7 @@
 # Actions (draft)
 
-**Status:** [Restore](#restore) (key `x`, [D23](decisions.md)),
+**Status:** [Restore](#restore) (key `x`, [D23](decisions.md); hard restore
+`X`, [D30](decisions.md)),
 [Switch branch](#switch-branch) (key `b`, [D24](decisions.md)) and
 [Update pin](#update-pin) (key `u`, [D29](decisions.md)) are implemented.
 Stage pin was dropped ([D29](decisions.md)).
@@ -13,7 +14,7 @@ a difference in one of two directions:
 
 | Action | Direction | Key |
 |---|---|---|
-| [Restore](#restore) | The worktree follows the recorded state | `x` |
+| [Restore](#restore) | The worktree follows the recorded state | `x`, `X` (hard) |
 | [Switch branch](#switch-branch) | Both: the branch tip is recorded, then restored to | `b` |
 | [Update pin](#update-pin) | Both: a switch to the tip of the pin's ref | `u` |
 
@@ -66,6 +67,32 @@ Two exceptions, where a staged pin is not kept:
   `.gitmodules` entry is reset with the other files. Its directory then
   counts as an untracked file.
 
+### Hard restore
+
+`X` restores to the **committed** pins, at every depth: what the commits
+record, without any staged pin.
+
+- The selected submodule goes to the committed pin, without the `s` / `c`
+  question; a staged pin of it is unstaged (as with `c`). A submodule that
+  was added but not committed yet has no committed pin and goes to the one
+  in the index.
+- Every restored repository's index is reset to its `HEAD`, the superproject
+  included: its staged pins are dropped, and the submodules below follow the
+  committed tree.
+
+So `x` and `X` differ in the staged pins of repositories that the restore
+does not move: `x` (`s` or `c`) keeps them, `X` drops them. This matters
+for the superproject, for a selected submodule without a staged pin of its
+own, and for nested repositories that are on their pin. A repository that
+moves loses its staged pins either way (see above); then `x` → `c` and `X`
+end the same, but `c` asks first.
+
+The dropped staged pins are counted in the loss (`2 staged pins`), but
+alone they don't make restore ask: pressing `X` is the choice to drop them.
+If something else would be lost, the question lists them with it. The
+commits of a dropped pin stay in the submodule; if HEAD leaves them and no
+ref reaches them, they count as `commits on no branch`, as always.
+
 ### Postconditions
 
 After a successful restore of repository R with target T:
@@ -132,7 +159,7 @@ Restore discards work. The things it can lose:
 | Untracked files | `changed` (untracked) |
 | Conflicts and in-progress operations | `conflict`; merge, rebase, cherry-pick, revert state |
 | Commits | A detached HEAD off the pin whose commits are on no branch, tag or remote ref (only the reflog still has them) |
-| Staged pins | Staged pins in a repository that restore moves to another commit (see [Target](#target)) |
+| Staged pins | Staged pins in a repository that restore moves to another commit (see [Target](#target)); with `X` all staged pins |
 | Repositories | An untracked directory that is a repository with its **own** `.git` directory (a clone that was never added as a submodule). Its commits may exist nowhere else. A removed submodule whose git directory is absorbed into `.git/modules` loses only its worktree. Its objects stay |
 
 Nothing else is lost. Branches, stashes, remote refs, ignored files and
@@ -214,8 +241,10 @@ is resolved like `Status` does, and the first candidate (see
 accepts wins. The branch checked out before the restore is passed to the
 ref resolution. A child's `.gitmodules` branch is read once per parent.
 
-With `c` the parent's index gets the committed pin first (`update-index
---cacheinfo` in the parent).
+With `c` and `X` the parent's index gets the committed pin first
+(`update-index --cacheinfo` in the parent). With `X` (`RestoreHard`) the
+staged pins are not put back, and the loss check takes the children's
+targets from `HEAD`'s tree instead of the index.
 
 `RestoreLoss` (`lossOf`) follows the repositories on disk: per repository
 `status` (without submodules), the in-progress state files, and

docs/decisions.md

@@ -567,3 +567,29 @@ the branch.
 its own rule. No new provider interface: `u` is `Branches`, `SwitchLoss` and
 `Switch`. Since `Status.Tip.SHA` is abbreviated, the UI compares it as a
 prefix of the branch's full SHA.
+
+## D30 — Hard restore drops staged pins at every depth
+
+**Context.** `x` keeps staged pins at every depth (D23), except in a
+repository the restore moves. Its `c` answer unstages only the selected
+submodule's pin. Staged pins of the superproject, or of nested repositories
+that stay on their pin, could only be dropped one by one.
+**Decision.** Amends D23. `X` is a hard restore: the selected submodule goes
+to its committed pin without the `s` / `c` question, and every restored
+repository's index is reset to `HEAD` (the superproject's too), so all
+staged pins below are dropped and the submodules follow the committed
+trees. Dropped staged pins are counted in the loss and listed if the
+question appears, but alone they don't make it appear. `x` and its question
+stay as they are.
+**Rationale.** A separate key keeps the common `x` free of a further
+question and makes the stronger action deliberate. A staged pin is only a
+recorded SHA; its commit stays in the submodule, and if HEAD leaves a
+commit no ref reaches, `commits on no branch` still asks.
+**Alternatives.** A third answer in the `s` / `c` question: only reachable
+for a submodule with a staged pin itself, not for the superproject or a
+clean parent. Dropping the question from `x`: rejected, the choice between
+staged and committed pin is still useful there.
+**Consequences.** `RestoreTarget` gets `RestoreHard`, which also matters for
+the superproject. `restoreRepo` and `lossOf` take whether to keep staged
+pins; switch always keeps them. Without a committed pin (an added
+submodule), `X` uses the index pin.

docs/requirements.md

@@ -148,6 +148,10 @@ commit hashes. It doesn't answer the questions users actually have:
   staged or the committed pin (the latter unstages it). A restored submodule
   whose pin is a branch tip ends on that branch, not detached. It asks for
   confirmation only if something would be lost. See [actions.md](actions.md#restore).
+  `X` is a hard restore: it goes to the committed pins at every depth,
+  without the pin question, and drops all staged pins below the selection
+  too. Dropped staged pins alone don't make it ask. See
+  [actions.md](actions.md#hard-restore).
 
 - **F57** `b` opens a popup in the middle of the screen with a search line
   and the local and remote branches of the selection (a submodule, or the

docs/ux-guide.md

@@ -295,6 +295,7 @@ colors in components.
 | `/` | Open the filter, see [Filter](#filter) |
 | `!` | Toggle problems only, see [Problems only](#problems-only) |
 | `x` | Restore the selection, see [Restore](#restore) |
+| `X` | Hard restore the selection: committed pins, staged pins dropped at every depth, see [Restore](#restore) |
 
 "First child" always means the first child **as displayed** (children are
 grouped by directory).
@@ -361,7 +362,9 @@ the term*.
 | failed | red `restore of src/app failed: <git's message>`, until the next key |
 
 `y` restores, any other key cancels; the keys are not passed on while a
-question is open. After `c` the name reads `src/app to the committed pin`. Without a loss there is no question. Success flashes
+question is open. After `c` the name reads `src/app to the committed pin`.
+`X` (hard restore) never asks for the pin; its name reads `src/app to the
+committed pins`, and dropped staged pins alone don't make it ask. Without a loss there is no question. Success flashes
 `restored src/app` in the footer. For the header the name is `the
 superproject`. This line takes precedence over the filter line and the
 problems-only notice.
@@ -424,6 +427,7 @@ where the palette can't be shown, see [Key bar and palette](#key-bar-and-palette
 | `u` | Update pin to the tip of its ref (superproject: fast-forward to upstream) | Submodule | Palette, Help |
 | `b` | Switch branch (popup) | Submodule | Palette, Help |
 | `x` | Restore | Submodule | Palette, Help |
+| `X` | Hard restore | Submodule | Palette, Help |
 | `f` | Fetch all repositories | Global | Help |
 | `r` | Reload everything | Global | Help |
 | `/` | Filter | Global | Help |