System Overview

Relevant source files

• src/index.ts
• src/output.ts
• src/repo.ts
• src/types.ts

Purpose and Scope

This document provides a technical overview of the git-merged-branches architecture, including its modular structure, dependency relationships, and data flow. It describes how the TypeScript source modules interact to deliver CLI functionality, from validating the repository state to executing Git operations and formatting terminal output.

For detailed information about individual modules and their functions, see:

• CLI entry point orchestration: CLI Entry Point
• Git operations implementation: Git Repository Operations
• Output formatting logic: Output Formatting System
• Utility functions: Utilities and Helpers

Sources: package.json1-79 src/index.ts6-31

---

Module Structure

The codebase is organized into modular TypeScript files within the src/ directory, each with a specific responsibility:

Module	Purpose	Key Exports
index.ts	Entry point and execution orchestration	main()
repo.ts	Git repository interaction and configuration loading	isGitRepo(), getMergedBranches(), deleteBranches(), getConfig()
output.ts	Branch list formatting, remote detection, and display logic	outputMergedBranches(), formatTaskBranches()
helpers.ts	Text styling, pluralization, and error logging utilities	style, logError(), pluralize()
validate.ts	URL validation for configuration settings	isValidURL()
types.ts	Shared TypeScript type definitions	GitMergedConfig, GitMergedOptions

The build process produces a single executable bundle at dist/index.mjs.

Module Responsibilities Diagram:

Sources: package.json25-28 src/index.ts1-31 src/repo.ts1-101 src/output.ts1-68 src/types.ts1-9

---

Module Dependencies

The following diagram illustrates the import relationships between modules, showing how dependencies flow through the system:

Import Analysis:

• index.ts imports from helpers, output, and repo to orchestrate the entire workflow src/index.ts2-4
• output.ts imports from helpers, repo, and validate for formatting and display logic src/output.ts1-4
• repo.ts imports from helpers for error logging and types for configuration structure src/repo.ts5-6
• types.ts has no dependencies and provides interfaces for configuration and options src/types.ts1-9

Sources: src/index.ts1-4 src/output.ts1-4 src/repo.ts1-6

---

Execution Flow

The system follows a structured flow through validation, Git operations, configuration loading, and output formatting:

Step-by-Step Process:

1. Validation Phase src/index.ts7-14

   • isGitRepo() verifies the current directory is a Git repository src/repo.ts8-15
   • isDetachedHead() ensures HEAD points to a branch to prevent execution in a detached state src/repo.ts17-24

2. Target Branch Detection src/index.ts16-20

   • getDefaultTargetBranch() identifies main or master as the comparison base src/repo.ts35-42

3. Merged Branch Discovery src/index.ts22

   • getMergedBranches() executes git branch --merged and filters out the target branch itself by comparing commit hashes src/repo.ts44-56

4. Configuration Loading src/index.ts24

   • getConfig() reads issue tracker settings from the git-merged-branches field in package.json src/repo.ts72-81

5. Output Generation src/index.ts24

   • outputMergedBranches() formats results and determines which branches also exist on the remote src/output.ts39-67
   • formatTaskBranches() uses regex to find issue IDs and append URLs src/output.ts24-37

6. Optional Deletion src/index.ts23

   • If the --delete flag is present, deleteBranches() removes branches locally and remotely src/repo.ts89-100

Sources: src/index.ts6-28 src/repo.ts8-100 src/output.ts39-67

---

Key Abstractions

The system defines two primary interfaces in src/types.ts that govern configuration and runtime behavior:

Type Definitions

GitMergedConfig src/types.ts1-4

• issueUrlFormat: A template string (e.g., https://jira.com/{{prefix}}{{id}}) src/output.ts18
• issueUrlPrefix: An array of strings used to identify task IDs in branch names src/output.ts11-15

GitMergedOptions src/types.ts6-8

• deleteBranches: A boolean flag derived from the --delete CLI argument src/index.ts23

Configuration Resolution

Sources: src/types.ts1-9 src/repo.ts72-81 src/output.ts24-37

---

Runtime Architecture

The system operates in two distinct modes based on user input:

Display Mode (Default)

Lists merged branches, identifies which ones exist on the remote origin, and prints the specific Git commands required to delete them manually src/output.ts60-66

Delete Mode

Triggered by the --delete flag. It programmatically executes local and remote deletion commands src/repo.ts83-88 It uses fetchRemoteBranches to ensure remote deletion is only attempted for branches that actually exist on the server src/output.ts52-55

Sources: src/index.ts23-24 src/output.ts39-67 src/repo.ts83-100

---

Build Architecture

The system compiles TypeScript source files into a single executable JavaScript module:

Build Configuration:

• Compiler: tsdown is used to bundle and minify the source package.json38
• Output Format: The bundle is an ES module (.mjs) targeting Node.js environments package.json26-27
• Binary Registration: The bin field in package.json maps both gmb and git-merged-branches to the same entry point package.json25-28

Sources: package.json25-38