Skip to content

Rename the “stack” diff layout to “unified” across Hunk #915

Description

@benvinegar

Summary

Hunk currently calls its single-column diff presentation the stack or stacked layout. That terminology is incorrect: the implemented presentation is a unified diff.

Rename this layout to unified throughout the product, public APIs, implementation, tests, documentation, examples, and maintained media.

This is a terminology change only. Rendering, navigation, responsive behavior, wrapping, copying, notes, and scrolling should behave exactly as they do today.

Look at the implementation plan before starting. It contains the investigated file map, compatibility policy, rename guidance, test coverage, media audit, and validation checklist.

Desired vocabulary

Current Replacement
Stack layout Unified layout
Stacked view Unified view
Canonical stack value Canonical unified value
Internal Stack* / stack* names Unified* / unified*

Apply these replacements only where “stack” describes the diff layout. Do not rename unrelated uses such as call stacks, stack traces, parser stacks, STML’s <stack> container, stacked pull requests, or CSS elements that genuinely stack content.

Compatibility requirements

Make unified canonical while preserving existing public inputs through deprecated aliases:

  • --mode stack remains accepted and normalizes to unified.
  • mode = "stack" remains accepted; saved config writes unified.
  • hunk.view.layoutStack remains a deprecated alias of hunk.view.layoutUnified, including for existing keybindings and extension command invocation.
  • Public OpenTUI components continue accepting layout="stack" as a deprecated input alias.
  • Extension-facing layout types retain deprecated legacy vocabulary where needed for source compatibility.
  • Extension layout_changed events emit the canonical unified value; document this emitted-value migration and follow the repository’s extension API versioning policy.

Keep compatibility handling at narrow public boundaries. Once normalized, internal state and rendering should use only the unified vocabulary.

Acceptance criteria

  • Every normal user-facing use of “stack” or “stacked” for the diff layout is replaced with “unified.”
  • --mode unified is the documented CLI value across applicable input paths and help output.
  • Deprecated --mode stack remains accepted and behaves identically.
  • mode = "unified" is the documented and persisted config value.
  • Deprecated mode = "stack" remains accepted but normalizes to unified.
  • Saving view preferences never writes the deprecated value.
  • Narrow responsive auto mode resolves to the unified layout; wide behavior remains unchanged.
  • The View menu shows Unified view, and 2 continues to select it.
  • hunk.view.layoutUnified is the canonical command ID.
  • hunk.view.layoutStack remains a deprecated compatibility alias.
  • Public OpenTUI components accept unified canonically and continue accepting the deprecated input alias.
  • Public extension types document the legacy literal as deprecated compatibility vocabulary.
  • Extension layout_changed events emit canonical unified values.
  • Internal discriminants, row types, functions, constants, variables, comments, keys, benchmark names, fixtures, and normal tests use unified, Unified, or UNIFIED as appropriate.
  • Compatibility handling is confined to clearly named boundary adapters, deprecated declarations, migration documentation, and focused compatibility tests.
  • README content, current documentation, generated references, examples, website copy, accessibility labels, and relevant media use the new terminology.
  • Screenshots or videos that visibly contain the old menu label are refreshed or replaced.
  • Split, unified, and auto layouts retain existing rendering and interaction behavior.
  • A repository-wide audit confirms remaining diff-layout uses of stack are intentional compatibility or historical records; unrelated uses remain untouched.
  • Generated artifacts are updated through their generators rather than edited independently.
  • An appropriate Changeset for hunkdiff is included; do not edit CHANGELOG.md directly.
  • Required unit, integration, TTY, documentation, and website checks pass.
  • A real-TTY smoke check verifies split, unified, deprecated input compatibility, and responsive auto layouts.

Non-goals

  • Changing how either layout renders
  • Changing shortcut assignments
  • Reworking responsive width thresholds
  • Renaming legitimate call-stack, parser-stack, STML, CSS-stacking, or pull-request-stack terminology
  • Rewriting historical release or benchmark records solely to modernize terminology

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions