Archived
simonfrankenandClaude Opus 5.5
c9932932bb
For developers new to submodules (notes/usability-plan.md, D32): - x and X read "restore to pin" and "restore committed pins" - problems only, filter and fetch are shown in the footer - ? shows every key in titled columns, then a legend of the status words, symbols and spine roles; esc closes it - u reads "pull (fast-forward)" on the superproject - the detail pane suggests f when the last fetch is old - a hint above the footer until the first key - the header says "staged", like the tree Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
49 lines
2.2 KiB
Markdown
49 lines
2.2 KiB
Markdown
# submarine — documentation
|
|
|
|
submarine is a terminal UI for git repositories with many (recursively nested)
|
|
submodules. It shows **the submodules**, as a collapsible tree (plus the state
|
|
of the superproject itself in the header), and
|
|
describes each pin as a **branch plus distance** (`origin/main ↓1`) instead of a
|
|
bare commit hash.
|
|
|
|
## Documents
|
|
|
|
| Document | Contents |
|
|
|---|---|
|
|
| [requirements.md](requirements.md) | What the tool must do: functional and non-functional requirements |
|
|
| [state-model.md](state-model.md) | How a submodule's state is determined, summarized into issues, and how pins are resolved to refs |
|
|
| [ux-guide.md](ux-guide.md) | Layout, attention hierarchy, colors, wording, navigation and key bindings |
|
|
| [architecture.md](architecture.md) | Package layout, the provider boundary, async loading, testing |
|
|
| [actions.md](actions.md) | the write actions restore, switch branch and update pin |
|
|
| [decisions.md](decisions.md) | Decision log with rationale (ADR style) |
|
|
|
|
## Install
|
|
|
|
```sh
|
|
curl -fsSL https://git.simon-franken.de/simonfranken/submarine/raw/branch/main/install.sh | sh
|
|
```
|
|
|
|
Installs `submarine` and the alias `sub` (linux/macOS, amd64/arm64) to
|
|
`~/.local/bin`. Update with `submarine update`. Maintainers publish with
|
|
`GITEA_TOKEN=… make release` (see [architecture](architecture.md#distribution)).
|
|
|
|
## Status
|
|
|
|
**Prototype.** The UI is complete for browsing. It reads real repositories
|
|
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 (`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:
|
|
|
|
1. (done) Write actions: restore, switch branch, update pin, see
|
|
[actions.md](actions.md). Stage pin was dropped (D29).
|
|
2. (done) "Problems only" (`!`) view, reusing the tree's filter.
|
|
3. Usability pass for users new to submodules, see
|
|
[notes/usability-plan.md](../notes/usability-plan.md). The low-effort
|
|
items are done (D31, D32); next are the issue hints and the palette
|
|
that fits the selection.
|