This guide provides comprehensive documentation for end users of the git-merged-branches CLI tool. It covers installation, configuration, command-line usage, and common workflows. This guide assumes you have basic familiarity with Git and command-line tools.
For installation details, see Installation and Setup. For configuration options, see Configuration. For developer documentation, see Architecture and Development.
The git-merged-branches tool identifies Git branches that have been merged into a base branch (typically master or main) and provides options to list or delete them README.md8-11 The tool integrates with issue tracking systems by generating clickable URLs from branch names containing issue identifiers README.md54-61
The tool executes a sequence of operations when invoked, starting from the entry point defined in package.json package.json26-29
High-Level Execution Flow
Sources: src/index.ts package.json25-29 README.md27-52
| Component | Location | Purpose |
|---|---|---|
| CLI executable | dist/index.mjs | Compiled entry point invoked by git-merged-branches or gmb commands package.json27-28 |
| Main orchestrator | src/index.ts | Coordinates all operations and handles command-line arguments |
| Git operations | src/repo.ts | Interfaces with Git commands to query repository state |
| Output formatter | src/output.ts | Formats branch lists and generates issue tracker URLs |
| Configuration | package.json | User-defined settings under git-merged-branches key package.json66-79 |
Sources: package.json25-29 README.md8-11
The tool can be installed globally or run on-demand via npx. Both methods provide access to two command aliases defined in the bin field of the package manifest package.json26-29
| Command | Description |
|---|---|
git-merged-branches | Full command name |
gmb | Shortened alias for convenience |
After global installation, both commands are available system-wide README.md15-19
The npx method downloads and executes the tool without permanent installation README.md21-25
For detailed installation instructions and prerequisites, see Installation and Setup.
Sources: README.md13-25 package.json26-29
The default behavior lists branches merged into the target branch README.md27-30:
The tool automatically selects master or main as the target branch if either exists README.md29-30
The --delete flag removes both local and remote branches README.md41-52:
For comprehensive usage examples and behavior details, see Basic Usage.
Sources: README.md27-52 package.json25-29
Configuration is defined in package.json under the git-merged-branches key README.md54-56 The system supports two primary settings for issue tracker integration.
Configuration Structure
Sources: package.json66-79 README.md54-93
| Option | Type | Description | Example |
|---|---|---|---|
issueUrlFormat | string | URL template with {{prefix}} and {{id}} placeholders README.md58-60 | "https://jira.com/browse/{{prefix}}{{id}}" |
issueUrlPrefix | string[] | Array of prefixes to match in branch names README.md61 | ["TOKEN-", "PROJECT-", "#"] |
For JIRA-style issue trackers where the prefix is part of the issue key README.md63-70:
For GitHub-style issues where the prefix is just # README.md72-79:
Sources: README.md54-79
The configuration is loaded at runtime. Invalid configurations trigger warnings and disable URL formatting README.md93-94
For complete configuration documentation, see Configuration.
Sources: README.md93-94
The tool supports a single command-line flag:
| Flag | Effect |
|---|---|
--delete | Executes branch deletion instead of just displaying them README.md41-44 |
Without --delete, the tool displays the merged branches but takes no destructive action. With --delete, it performs local and remote branch deletion operations README.md44-52
Behavior Comparison
Sources: README.md41-52
For detailed command-line option documentation, see Command Line Options.
The tool produces structured output with branch names and optional issue tracker links README.md81-91:
The tool processes branch names through this pipeline to generate links README.md81-91:
Issue URL Generation Pipeline
Sources: README.md58-91
The tool performs validation before executing operations, ensuring it is run within a valid Git repository and not in a detached HEAD state README.md29-132
Validation Sequence
Sources: README.md29-132
| Error | Cause | Resolution |
|---|---|---|
| Not a Git repository | Executed outside Git repository | Navigate to Git repository directory |
| Detached HEAD | Repository in detached HEAD state | Check out a branch |
| No target branch | Neither master nor main exists README.md29-30 | Ensure one of these branches exists |
| Invalid configuration | Malformed issueUrlFormat README.md93-94 | Fix configuration in package.json |
Sources: README.md1-149 package.json1-79
Refresh this wiki