# paulirish/git-open architecture

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

- Interactive diagram: https://gitdiagram.com/paulirish/git-open
- Repository: https://github.com/paulirish/git-open

## Overview

#### Purpose and Entry Points

`git-open` is a shell-based Git subcommand that resolves the current repository, remote, branch, commit, or issue into a hosted-repository URL and opens it in the system browser. The primary executable is `git-open`; Git discovers it as `git open` when it is on `PATH`.

- `git-open`
- `git-open.1.md`
- `package.json`

#### CLI Dispatch and Git Context Resolution

The executable parses positional remote/branch arguments and mode flags including commit, issue, print-only, and URL suffix behavior. It interrogates the local Git repository for its tracked/default remote, branch, and commit state. `--print` is the output boundary: it emits the resolved URL without launching a browser.

- `git-open`
- `git-open.1.md`

#### Remote Normalization and Provider Routing

Remote URLs may be SSH or HTTPS and are normalized into host, owner/project, and provider-specific path information. The central routing responsibility selects URL conventions for GitHub/Gist, GitLab including custom instances, Bitbucket Cloud/Server, VSTS/TFS, AWS CodeCommit, and cnb.cool. Provider differences determine branch, commit, issue, and suffix paths.

- `git-open`
- `README.md`

#### URL Construction Modes

After remote/provider resolution, the command builds a repository-web URL for one of four primary targets: a branch page (default), current commit, issue inferred from an issue-style branch name, or a caller-provided suffix such as `pulls`. Issue opening is intentionally limited to providers with supported issue URL formats.

- `git-open`
- `git-open.1.md`

#### Browser Launch Boundary

The final URL is either printed or delegated to platform-appropriate browser-opening behavior. This isolates OS/runtime concerns from Git parsing and URL construction, including shell environments and Windows/WSL installation paths.

- `git-open`
- `git-open.plugin.sh`
- `git-open.plugin.zsh`

#### Distribution and Shell Integration

The project ships as a standalone executable, an npm global package, and Bash/Zsh plugin entry files. Shell plugins expose the command within plugin managers, while npm packaging distributes the same command-line artifact rather than a Node runtime application.

- `package.json`
- `git-open.plugin.sh`
- `git-open.plugin.zsh`

#### Verification and Automation

Behavior is validated with BATS shell tests, including assertion/support dependencies included as Git submodules. GitHub Actions runs repository CI; Node/npm is used primarily to expose test scripts and package distribution metadata.

- `test/git-open.bats`
- `test/test_helper/bats-assert`
- `.github/workflows/ci.yml`

Main entry points: [`git-open`](https://github.com/paulirish/git-open/blob/master/git-open) (git-open executable), [`test/git-open.bats`](https://github.com/paulirish/git-open/blob/master/test/git-open.bats) (BATS behavior tests), [`package.json`](https://github.com/paulirish/git-open/blob/master/package.json) (npm package), [`git-open.1.md`](https://github.com/paulirish/git-open/blob/master/git-open.1.md) (CLI manual)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["CLI Runtime"]
  node_git[("Git / local repository<br/>external context")]
  node_cli["git-open executable<br/>shell CLI"]
  node_dispatch["Argument dispatch<br/>CLI parser"]
  node_git_context["Git context resolution<br/>Git integration"]
  node_remote_normalizer["Remote normalization<br/>URL parser"]
  node_provider_router{{"Provider routing<br/>provider adapter"}}
  node_url_modes["Target URL construction<br/>URL builder"]
  node_print["Print-only output<br/>output boundary"]
  node_browser["Browser launcher<br/>platform integration"]
  node_manual["CLI manual<br/>documentation<br/>[git-open.1.md]"]
end

subgraph group_distribution["Distribution"]
  node_npm["npm package<br/>package distribution<br/>[package.json]"]
  node_bash_plugin["Bash plugin entry<br/>shell integration<br/>[git-open.plugin.sh]"]
  node_zsh_plugin["Zsh plugin entry<br/>shell integration"]
end

subgraph group_verification["Verification"]
  node_bats_tests["BATS behavior tests<br/>shell tests<br/>[git-open.bats]"]
  node_bats_assert["BATS assertion support<br/>test dependency"]
  node_ci["GitHub Actions CI<br/>automation workflow<br/>[ci.yml]"]
end

node_cli -->|"parses"| node_dispatch
node_dispatch -->|"requests context"| node_git_context
node_git -->|"remote and HEAD state"| node_git_context
node_git_context -->|"remote URL"| node_remote_normalizer
node_remote_normalizer -->|"host and project"| node_provider_router
node_dispatch -->|"selected mode"| node_url_modes
node_git_context -->|"branch or commit"| node_url_modes
node_provider_router -->|"provider paths"| node_url_modes
node_url_modes -->|"--print"| node_print
node_url_modes -->|"default URL opening"| node_browser
node_npm -->|"distributes"| node_cli
node_bash_plugin -->|"exposes"| node_cli
node_zsh_plugin -->|"exposes"| node_cli
node_manual -.->|"documents"| node_cli
node_bats_tests -->|"validates"| node_cli
node_bats_tests -->|"uses"| node_bats_assert
node_ci -->|"runs"| node_bats_tests
node_npm -.->|"test script"| node_bats_tests

click node_cli "https://github.com/paulirish/git-open/blob/master/git-open"
click node_dispatch "https://github.com/paulirish/git-open/blob/master/git-open"
click node_git_context "https://github.com/paulirish/git-open/blob/master/git-open"
click node_remote_normalizer "https://github.com/paulirish/git-open/blob/master/git-open"
click node_provider_router "https://github.com/paulirish/git-open/blob/master/git-open"
click node_url_modes "https://github.com/paulirish/git-open/blob/master/git-open"
click node_print "https://github.com/paulirish/git-open/blob/master/git-open"
click node_browser "https://github.com/paulirish/git-open/blob/master/git-open"
click node_manual "https://github.com/paulirish/git-open/blob/master/git-open.1.md"
click node_npm "https://github.com/paulirish/git-open/blob/master/package.json"
click node_bash_plugin "https://github.com/paulirish/git-open/blob/master/git-open.plugin.sh"
click node_zsh_plugin "https://github.com/paulirish/git-open/blob/master/git-open.plugin.zsh"
click node_bats_tests "https://github.com/paulirish/git-open/blob/master/test/git-open.bats"
click node_bats_assert "https://github.com/paulirish/git-open/tree/master/test/test_helper/bats-assert"
click node_ci "https://github.com/paulirish/git-open/blob/master/.github/workflows/ci.yml"

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_git,node_cli,node_dispatch,node_git_context,node_remote_normalizer,node_provider_router,node_url_modes,node_print,node_browser,node_manual toneBlue
class node_npm,node_bash_plugin,node_zsh_plugin toneAmber
class node_bats_tests,node_bats_assert,node_ci toneMint
```

## Components

### CLI Runtime

- **Git / local repository**: external context · Supplies remotes, branch, and commit state.
- [git-open executable](https://github.com/paulirish/git-open/blob/master/git-open): shell CLI · Git-discoverable git-open command. · `git-open`
- [Argument dispatch](https://github.com/paulirish/git-open/blob/master/git-open): CLI parser · Selects remote, target mode, print behavior, and suffix. · `git-open`
- [Git context resolution](https://github.com/paulirish/git-open/blob/master/git-open): Git integration · Finds tracked/default remote, branch, and commit. · `git-open`
- [Remote normalization](https://github.com/paulirish/git-open/blob/master/git-open): URL parser · Converts SSH or HTTPS remotes into host and project data. · `git-open`
- [Provider routing](https://github.com/paulirish/git-open/blob/master/git-open): provider adapter · Applies GitHub, GitLab, Bitbucket, VSTS/TFS, CodeCommit, and cnb.cool conventions. · `git-open`
- [Target URL construction](https://github.com/paulirish/git-open/blob/master/git-open): URL builder · Builds branch, commit, supported issue, or suffix URLs. · `git-open`
- [Print-only output](https://github.com/paulirish/git-open/blob/master/git-open): output boundary · Emits the URL when --print is selected. · `git-open`
- [Browser launcher](https://github.com/paulirish/git-open/blob/master/git-open): platform integration · Opens the resolved URL with OS and WSL-aware behavior. · `git-open`
- [CLI manual](https://github.com/paulirish/git-open/blob/master/git-open.1.md): documentation · `git-open.1.md`

### Distribution

- [npm package](https://github.com/paulirish/git-open/blob/master/package.json): package distribution · Publishes the shell executable and npm scripts. · `package.json`
- [Bash plugin entry](https://github.com/paulirish/git-open/blob/master/git-open.plugin.sh): shell integration · `git-open.plugin.sh`
- [Zsh plugin entry](https://github.com/paulirish/git-open/blob/master/git-open.plugin.zsh): shell integration · `git-open.plugin.zsh`

### Verification

- [BATS behavior tests](https://github.com/paulirish/git-open/blob/master/test/git-open.bats): shell tests · `test/git-open.bats`
- [BATS assertion support](https://github.com/paulirish/git-open/tree/master/test/test_helper/bats-assert): test dependency · Assertion and support dependency included as a Git submodule. · `test/test_helper/bats-assert`
- [GitHub Actions CI](https://github.com/paulirish/git-open/blob/master/.github/workflows/ci.yml): automation workflow · `.github/workflows/ci.yml`

## Connections

- git-open executable → Argument dispatch: parses
- Argument dispatch → Git context resolution: requests context
- Git / local repository → Git context resolution: remote and HEAD state
- Git context resolution → Remote normalization: remote URL
- Remote normalization → Provider routing: host and project
- Argument dispatch → Target URL construction: selected mode
- Git context resolution → Target URL construction: branch or commit
- Provider routing → Target URL construction: provider paths
- Target URL construction → Print-only output: --print
- Target URL construction → Browser launcher: default URL opening
- npm package → git-open executable: distributes
- Bash plugin entry → git-open executable: exposes
- Zsh plugin entry → git-open executable: exposes
- CLI manual → git-open executable: documents
- BATS behavior tests → git-open executable: validates
- BATS behavior tests → BATS assertion support: uses
- GitHub Actions CI → BATS behavior tests: runs
- npm package → BATS behavior tests: test script
