Extension manager (system view)

Active contributors: vilmibm, Sam Coe, Mislav

Purpose

The extension manager is the runtime that powers gh extension (see Extensions command page) and that exposes installed extensions as Cobra subcommands at startup. From a system perspective, it is the integration layer between the Factory and Cobra.

Directory layout

pkg/cmd/extension/
  manager.go               # ~24 KB: Manager type and lifecycle
  command.go               # User-facing verb dispatcher
  http.go                  # GitHub releases API for binary extensions
  git.go                   # git clone/pull for script extensions
  extension.go             # Cobra wiring for the gh extension subtree
  mocks.go                 # Public mock for downstream tests
  symlink_other.go         # Symlinks on POSIX
  symlink_windows.go       # Symlinks on Windows
  ext_tmpls/               # Scaffolding for gh extension create
  browse/                  # tview-based browse TUI
pkg/extensions/            # Public types and interfaces (Extension, OfficialExtensions)

Key abstractions

Symbol	File	Role
Manager	manager.go	Owns the install/upgrade/list/dispatch lifecycle.
Extension	pkg/extensions/extension.go	Generic extension descriptor.
binaryExtension	manager.go	Compiled-binary extension.
gitExtension	manager.go	Cloned-repo (script) extension.
localExtension	manager.go	Locally-developed extension (used by gh extension exec).
OfficialExtensions	pkg/extensions/official.go	Curated list driving the "official extension stub" feature.
NewCmdExtension	extension.go	Wires the user-facing subcommands.

How it works

At startup:

graph TD
    A[factory.New] --> B[extension.NewManager]
    B --> C[List extensions in ~/.local/share/gh/extensions]
    A --> D[root.NewCmdRoot]
    D -->|for each extension| E{Name collides with core cmd?}
    E -->|yes| F[skip]
    E -->|no| G[NewCmdExtension wraps + registers]
    D -->|for each OfficialExtensions| H{Name collides?}
    H -->|yes| I[skip]
    H -->|no| J[NewCmdOfficialExtensionStub registers a hidden cmd]

Install paths:

• Script extensions are repos cloned into ~/.local/share/gh/extensions/gh-<name> with a gh-<name> script at root. Manager.Dispatch execs the script with the user's args.
• Binary extensions look up the latest release of the source repo (via http.go), match the platform asset, download and unpack it. Dispatch execs the binary.
• Local extensions point at a local working tree, useful for gh extension exec and during development with gh extension create.

gh extension upgrade --all walks every installed extension, checks for an update through the appropriate mechanism (git fetch or new GitHub release), and applies it. Upgrades respect the --pin flag set at install time.

Integration points

• cmdutil.Factory.ExtensionManager exposes the live manager. Tests substitute mocks.go to avoid filesystem and network access.
• The browse TUI uses rivo/tview. It is the only place in the repo where tview appears.
• The "official extension stub" registration depends on Cobra command lookup ordering; stubs are added last so real extensions and aliases take priority.

Entry points for modification

• New install method: add a xExtension struct that implements the Extension interface, plus the corresponding install path in Manager.Install.
• New verb on gh extension: extend command.go and extension.go.
• Update the official stub list: edit pkg/extensions/official.go. Each entry surfaces a hidden Cobra command that prompts the user to install the matching real extension.

Key source files

File	Purpose
pkg/cmd/extension/manager.go	Manager and extension types.
pkg/cmd/extension/command.go	User-facing verb dispatch.
pkg/cmd/extension/http.go	Release lookups for binary extensions.
pkg/cmd/extension/git.go	Git operations.
pkg/extensions/extension.go	Public interfaces.
pkg/extensions/official.go	Curated official-extension list.
pkg/cmd/root/official_extension_stub.go	Hidden stub commands.

Related pages

• Extensions command.
• Factory and cmdutil.