# github/gh-stack architecture

> Architecture diagram of the GitHub repository github/gh-stack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/github/gh-stack
- Repository: https://github.com/github/gh-stack

## Overview

gh-stack is a GitHub CLI extension for managing ordered stacks of branches and their pull requests. The typical workflow initializes a stack, adds branches, rebases and pushes the stack, then submits linked PRs to GitHub; users can also inspect, navigate, check out, or modify stacks. Local stack metadata tracks branch order and PR associations, while Git and GitHub operations are exposed through internal adapters. The graph follows README-documented behavior and sampled interfaces; several command implementations were not sampled, so uncertain internal wiring is omitted.

Main entry points: [`internal/stack/stack.go`](https://github.com/github/gh-stack/blob/main/internal/stack/stack.go) (Stack metadata), [`internal/git/gitops.go`](https://github.com/github/gh-stack/blob/main/internal/git/gitops.go) (Git operations), [`internal/github/github.go`](https://github.com/github/gh-stack/blob/main/internal/github/github.go) (GitHub client), [`cmd/submit.go`](https://github.com/github/gh-stack/blob/main/cmd/submit.go) (Submit PRs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflows"]
  node_init["Initialize stack<br/>[init.go]"]
  node_add["Add branch<br/>[add.go]"]
  node_rebase["Rebase stack<br/>[rebase.go]"]
  node_push["Push branches<br/>[push.go]"]
  node_submit["Submit PRs<br/>[submit.go]"]
  node_checkout["Check out stack<br/>[checkout.go]"]
  node_modify["Modify stack<br/>[modify.go]"]
  node_view["View stack<br/>[view.go]"]
  node_navigate["Navigate stack<br/>[navigate.go]"]
  node_merge["Merge stack<br/>[merge.go]"]
  node_sync["Sync stack<br/>[sync.go]"]
end

subgraph group_local["Local stack"]
  node_git["Git operations<br/>[gitops.go]"]
  node_metadata[("Stack metadata<br/>[stack.go]")]
  node_config["Configuration<br/>[config.go]"]
  node_modify_apply["Apply modifications<br/>[apply.go]"]
end

subgraph group_remote["GitHub integration"]
  node_github["GitHub client<br/>[github.go]"]
  node_github_merge["Async merge<br/>[merge_async.go]"]
end

subgraph group_ui["Terminal interfaces"]
  node_submit_ui["Submit editor<br/>[model.go]"]
  node_checkout_ui["Stack picker<br/>[model.go]"]
  node_modify_ui["Stack editor<br/>[model.go]"]
  node_stack_ui["Stack display<br/>[model.go]"]
end

node_user(("CLI user"))
node_github_service["GitHub"]

node_user -->|"runs"| node_init
node_user -->|"runs"| node_add
node_user -->|"runs"| node_rebase
node_user -->|"runs"| node_push
node_user -->|"runs"| node_submit
node_user -->|"runs"| node_checkout
node_user -->|"runs"| node_modify
node_user -->|"runs"| node_view
node_user -->|"runs"| node_navigate
node_user -->|"runs"| node_merge
node_user -->|"runs"| node_sync
node_init -->|"creates branches"| node_git
node_init -->|"records stack"| node_metadata
node_add -->|"creates branch"| node_git
node_add -->|"updates stack"| node_metadata
node_rebase -->|"rebases branches"| node_git
node_rebase -->|"checks PR state"| node_github
node_push -->|"pushes branches"| node_git
node_submit -->|"pushes branches"| node_git
node_submit -->|"reads stack"| node_metadata
node_submit -->|"creates PRs"| node_github
node_submit -->|"syncs remote stack"| node_github
node_submit -->|"opens editor"| node_submit_ui
node_checkout -->|"checks local stacks"| node_metadata
node_checkout -->|"finds remote stacks"| node_github
node_checkout -->|"opens picker"| node_checkout_ui
node_checkout -->|"fetches branches"| node_git
node_checkout -->|"saves stack"| node_metadata
node_modify -->|"loads stack"| node_metadata
node_modify -->|"opens editor"| node_modify_ui
node_modify -->|"applies plan"| node_modify_apply
node_modify_apply -->|"changes branches"| node_git
node_modify_apply -->|"updates stack"| node_metadata
node_view -->|"reads stack"| node_metadata
node_view -->|"renders stack"| node_stack_ui
node_navigate -->|"reads stack"| node_metadata
node_navigate -->|"switches branch"| node_git
node_merge -->|"requests merge"| node_github
node_github -->|"dispatches merge"| node_github_merge
node_github -->|"calls API"| node_github_service
node_github_merge -->|"polls merge"| node_github_service
node_sync -->|"syncs PR stack"| node_github
node_sync -->|"reads stack"| node_metadata
node_git -->|"reads settings"| node_config

click node_init "https://github.com/github/gh-stack/blob/main/cmd/init.go"
click node_add "https://github.com/github/gh-stack/blob/main/cmd/add.go"
click node_rebase "https://github.com/github/gh-stack/blob/main/cmd/rebase.go"
click node_push "https://github.com/github/gh-stack/blob/main/cmd/push.go"
click node_submit "https://github.com/github/gh-stack/blob/main/cmd/submit.go"
click node_checkout "https://github.com/github/gh-stack/blob/main/cmd/checkout.go"
click node_modify "https://github.com/github/gh-stack/blob/main/cmd/modify.go"
click node_view "https://github.com/github/gh-stack/blob/main/cmd/view.go"
click node_navigate "https://github.com/github/gh-stack/blob/main/cmd/navigate.go"
click node_merge "https://github.com/github/gh-stack/blob/main/cmd/merge.go"
click node_sync "https://github.com/github/gh-stack/blob/main/cmd/sync.go"
click node_git "https://github.com/github/gh-stack/blob/main/internal/git/gitops.go"
click node_metadata "https://github.com/github/gh-stack/blob/main/internal/stack/stack.go"
click node_config "https://github.com/github/gh-stack/blob/main/internal/config/config.go"
click node_github "https://github.com/github/gh-stack/blob/main/internal/github/github.go"
click node_submit_ui "https://github.com/github/gh-stack/blob/main/internal/tui/submitview/model.go"
click node_checkout_ui "https://github.com/github/gh-stack/blob/main/internal/tui/checkoutview/model.go"
click node_modify_ui "https://github.com/github/gh-stack/blob/main/internal/tui/modifyview/model.go"
click node_stack_ui "https://github.com/github/gh-stack/blob/main/internal/tui/stackview/model.go"
click node_modify_apply "https://github.com/github/gh-stack/blob/main/internal/modify/apply.go"
click node_github_merge "https://github.com/github/gh-stack/blob/main/internal/github/merge_async.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_init,node_add,node_rebase,node_push,node_submit,node_checkout,node_modify,node_view,node_navigate,node_merge,node_sync,node_user toneBlue
class node_git,node_metadata,node_config,node_modify_apply toneAmber
class node_github,node_github_merge toneMint
class node_submit_ui,node_checkout_ui,node_modify_ui,node_stack_ui toneRose
class node_github_service toneIndigo
```

## Components

### CLI workflows

- [Initialize stack](https://github.com/github/gh-stack/blob/main/cmd/init.go): `cmd/init.go`
- [Add branch](https://github.com/github/gh-stack/blob/main/cmd/add.go): `cmd/add.go`
- [Rebase stack](https://github.com/github/gh-stack/blob/main/cmd/rebase.go): `cmd/rebase.go`
- [Push branches](https://github.com/github/gh-stack/blob/main/cmd/push.go): `cmd/push.go`
- [Submit PRs](https://github.com/github/gh-stack/blob/main/cmd/submit.go): `cmd/submit.go`
- [Check out stack](https://github.com/github/gh-stack/blob/main/cmd/checkout.go): `cmd/checkout.go`
- [Modify stack](https://github.com/github/gh-stack/blob/main/cmd/modify.go): `cmd/modify.go`
- [View stack](https://github.com/github/gh-stack/blob/main/cmd/view.go): `cmd/view.go`
- [Navigate stack](https://github.com/github/gh-stack/blob/main/cmd/navigate.go): `cmd/navigate.go`
- [Merge stack](https://github.com/github/gh-stack/blob/main/cmd/merge.go): `cmd/merge.go`
- [Sync stack](https://github.com/github/gh-stack/blob/main/cmd/sync.go): `cmd/sync.go`

### Local stack

- [Git operations](https://github.com/github/gh-stack/blob/main/internal/git/gitops.go): `internal/git/gitops.go`
- [Stack metadata](https://github.com/github/gh-stack/blob/main/internal/stack/stack.go): `internal/stack/stack.go`
- [Configuration](https://github.com/github/gh-stack/blob/main/internal/config/config.go): `internal/config/config.go`
- [Apply modifications](https://github.com/github/gh-stack/blob/main/internal/modify/apply.go): `internal/modify/apply.go`

### GitHub integration

- [GitHub client](https://github.com/github/gh-stack/blob/main/internal/github/github.go): `internal/github/github.go`
- [Async merge](https://github.com/github/gh-stack/blob/main/internal/github/merge_async.go): `internal/github/merge_async.go`

### Terminal interfaces

- [Submit editor](https://github.com/github/gh-stack/blob/main/internal/tui/submitview/model.go): `internal/tui/submitview/model.go`
- [Stack picker](https://github.com/github/gh-stack/blob/main/internal/tui/checkoutview/model.go): `internal/tui/checkoutview/model.go`
- [Stack editor](https://github.com/github/gh-stack/blob/main/internal/tui/modifyview/model.go): `internal/tui/modifyview/model.go`
- [Stack display](https://github.com/github/gh-stack/blob/main/internal/tui/stackview/model.go): `internal/tui/stackview/model.go`

### Other components

- **CLI user**
- **GitHub**

## Connections

- CLI user → Initialize stack: runs
- CLI user → Add branch: runs
- CLI user → Rebase stack: runs
- CLI user → Push branches: runs
- CLI user → Submit PRs: runs
- CLI user → Check out stack: runs
- CLI user → Modify stack: runs
- CLI user → View stack: runs
- CLI user → Navigate stack: runs
- CLI user → Merge stack: runs
- CLI user → Sync stack: runs
- Initialize stack → Git operations: creates branches
- Initialize stack → Stack metadata: records stack
- Add branch → Git operations: creates branch
- Add branch → Stack metadata: updates stack
- Rebase stack → Git operations: rebases branches
- Rebase stack → GitHub client: checks PR state
- Push branches → Git operations: pushes branches
- Submit PRs → Git operations: pushes branches
- Submit PRs → Stack metadata: reads stack
- Submit PRs → GitHub client: creates PRs
- Submit PRs → GitHub client: syncs remote stack
- Submit PRs → Submit editor: opens editor
- Check out stack → Stack metadata: checks local stacks
- Check out stack → GitHub client: finds remote stacks
- Check out stack → Stack picker: opens picker
- Check out stack → Git operations: fetches branches
- Check out stack → Stack metadata: saves stack
- Modify stack → Stack metadata: loads stack
- Modify stack → Stack editor: opens editor
- Modify stack → Apply modifications: applies plan
- Apply modifications → Git operations: changes branches
- Apply modifications → Stack metadata: updates stack
- View stack → Stack metadata: reads stack
- View stack → Stack display: renders stack
- Navigate stack → Stack metadata: reads stack
- Navigate stack → Git operations: switches branch
- Merge stack → GitHub client: requests merge
- GitHub client → Async merge: dispatches merge
- GitHub client → GitHub: calls API
- Async merge → GitHub: polls merge
- Sync stack → GitHub client: syncs PR stack
- Sync stack → Stack metadata: reads stack
- Git operations → Configuration: reads settings