Installation and Setup

Relevant source files

• README.md
• package.json

This document covers the installation and initial setup of the git-merged-branches CLI tool. It explains the different installation methods, system requirements, and verification steps.

For information about configuring issue URL formatting, see Configuration. For usage examples and command-line options, see Basic Usage and Command Line Options.

---

Prerequisites

Node.js Version Requirement

The tool requires Node.js version 22.18.0 or higher. This constraint is enforced by the engines field in package.json35-37

If your Node.js version is below 22.18.0, update Node.js before proceeding with installation.

Git Repository Requirement

The tool must be executed within a Git repository directory. It operates on the local Git repository state to identify merged branches.

Sources: package.json35-37

---

Installation Methods

The following diagram illustrates the three primary installation methods and how they map to the executable artifacts:

Sources: package.json26-29 README.md13-26

---

Global Installation

Global installation makes the git-merged-branches and gmb commands available system-wide.

This installation method:

1. Downloads the package from the NPM registry.
2. Installs it to the global node_modules directory.
3. Creates symbolic links for both binary aliases defined in package.json26-29

Binary Name	Alias Type	Command
git-merged-branches	Primary	Full command name
gmb	Shorthand	Abbreviated alias

Both commands execute the same compiled artifact at dist/index.mjs.

When to use: Recommended for regular use when you want the tool available across all projects.

Sources: package.json26-29 README.md15-19

---

One-time Execution with npx

For occasional use without permanent installation, execute the tool via npx:

The npx command:

1. Downloads the latest version from the NPM registry (if not cached).
2. Executes the tool.
3. Removes it after execution (unless cached).

This method is useful for:

• Testing the tool before committing to global installation.
• CI/CD environments where temporary execution is preferred.
• Ensuring you always run the latest version.

When to use: Best for one-time or infrequent usage, or in automated environments.

Sources: README.md21-25

---

Local Development Setup

For contributors or local testing, link a locally built version:

Step-by-step process:

1. Clone the repository:

2. Install dependencies using pnpm:

   The project uses pnpm as its package manager package.json10 with specific dependency overrides defined to replace common polyfills with @nolyfill equivalents in package.json57-78

3. Build the project:

   This executes the build script defined in package.json39 which runs the tsdown bundler to compile TypeScript sources into dist/index.mjs.

4. Create a local symlink:

   This creates symbolic links for git-merged-branches and gmb that point to your local build directory.

When to use: Required for development, testing changes, or contributing to the project.

Sources: README.md100-128 package.json10 package.json39 package.json57-78

---

Post-Installation Verification

Verify successful installation by checking the tool's version and availability:

Expected output format: 0.5.0 (version number from package.json4)

Verifying Binary Resolution

The following table shows how to verify each binary is correctly resolved:

Command	Verification	Expected Result
which git-merged-branches	Locate binary path	/usr/local/bin/git-merged-branches or similar
which gmb	Locate alias path	/usr/local/bin/gmb or similar
git-merged-branches --version	Check version	Current version number

Testing Basic Functionality

Execute the tool in any Git repository to verify it runs:

If no merged branches exist, you should see output indicating zero merged branches. If the tool cannot find a base branch (neither master nor main exists), it will display an appropriate message README.md29-30

Sources: package.json4 package.json26-29 README.md29-30

---

Installation Architecture

The following diagram maps the installation artifacts to their code entities:

The files array in package.json30-34 explicitly defines which files are included in the published NPM package. Only the essential runtime files are distributed:

• LICENSE.md - MIT license terms
• README.md - User documentation
• dist/ - Compiled executable code

Source TypeScript files are excluded from the published package, keeping the distribution lean.

Sources: package.json26-34

---

System Requirements Summary

Requirement	Specification	Verification Command
Node.js	>= 22.18.0	node --version
Package Manager	npm (built-in) or pnpm (development)	npm --version
Git	Any modern version	git --version
Operating System	Cross-platform (Linux, macOS, Windows)	N/A

The tool is a pure JavaScript/TypeScript CLI application with no native dependencies, making it fully cross-platform. The only hard requirement is the Node.js version constraint enforced by package.json35-37

Sources: package.json35-37