gcom-cli

An interactive, dependency-free Bash wrapper around git commit that helps you produce well-formed Conventional Commits messages of the form:

<type>(<scope>): <description>

It guides you through picking a type (feat, fix, docs, ...), an optional scope, and a short description, then runs git commit for you.

---

Features

• Verifies you are inside a Git repository before doing anything.
• Detects when nothing is staged and offers to run git add -A for you.
• Numbered menu of standard Conventional Commit types: feat, fix, docs, style, refactor, chore, perf, test, build, ci, revert.
• Optional scope (e.g. api, ui, auth) wrapped automatically in parentheses.
• Rejects empty descriptions.
• Shows a final preview before committing.
• Colored output that gracefully degrades when piped to a file.
• Pure Bash, no external dependencies beyond git and a POSIX shell.

---

Requirements

• Bash 4 or newer (any modern Linux distribution ships with this).
• git available on your PATH.

Check your versions:

bash --version
git --version

---

Quick start

From the repository where you cloned this project:

chmod +x gcom-cli/gcom-cli
./gcom-cli/gcom-cli

You will be walked through staging (if needed), choosing a type, entering an optional scope, and writing a description. Example session:

Git Commit Helper (Conventional Commits)

Select a commit type:
1) feat       4) style     7) perf      10) ci
2) fix        5) refactor  8) test      11) revert
3) docs       6) chore     9) build
Enter number: 1

Scope (optional, press Enter to skip):
api

Short description:
add user login endpoint

Commit message preview:
  feat(api): add user login endpoint

[main 1a2b3c4] feat(api): add user login endpoint
Commit created successfully.

---

Installation

The script is a single file with no build step. The recommended approach is to place it on a directory that is already in your PATH and make it executable.

Option 1 — System-wide install (recommended)

Works on every distribution. Requires sudo.

sudo install -m 0755 gcom-cli/gcom-cli /usr/local/bin/gcom-cli

Verify the installation:

gcom-cli --version

To uninstall:

sudo rm /usr/local/bin/gcom-cli

Option 2 — Per-user install (no sudo required)

Install into ~/.local/bin, which is on $PATH by default on most modern distributions:

mkdir -p ~/.local/bin
install -m 0755 gcom-cli/gcom-cli ~/.local/bin/gcom-cli

If gcom-cli is not found after installing, add ~/.local/bin to your PATH. For Bash users:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

For Zsh users (default on macOS and many distributions):

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Option 3 — Symlink from the repository

Useful when developing the script — edits in the repo are picked up immediately.

chmod +x gcom-cli/gcom-cli
sudo ln -sf "$(pwd)/gcom-cli/gcom-cli" /usr/local/bin/gcom-cli

Distro-specific notes

Debian / Ubuntu / Linux Mint / Pop!_OS

sudo apt update
sudo apt install -y git bash
sudo install -m 0755 gcom-cli/gcom-cli /usr/local/bin/gcom-cli

/usr/local/bin is in PATH by default on Debian-based systems.

Fedora / RHEL / CentOS Stream / Rocky / AlmaLinux

sudo dnf install -y git bash
sudo install -m 0755 gcom-cli/gcom-cli /usr/local/bin/gcom-cli

Arch Linux / Manjaro / EndeavourOS

sudo pacman -S --needed git bash
sudo install -m 0755 gcom-cli/gcom-cli /usr/local/bin/gcom-cli

openSUSE (Leap / Tumbleweed)

sudo zypper install -y git bash
sudo install -m 0755 gcom-cli/gcom-cli /usr/local/bin/gcom-cli

Alpine Linux

Alpine ships BusyBox ash as /bin/sh, but bash is required. Install it first:

sudo apk add --no-cache bash git
sudo install -m 0755 gcom-cli/gcom-cli /usr/local/bin/gcom-cli

macOS (bonus)

/usr/local/bin may not exist on Apple Silicon if you have not installed anything via Homebrew. Either use Homebrew's prefix or ~/.local/bin:

mkdir -p ~/.local/bin
install -m 0755 gcom-cli/gcom-cli ~/.local/bin/gcom-cli
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

---

Usage

gcom-cli              Run the interactive commit wizard
gcom-cli -h, --help   Show help and exit
gcom-cli -v, --version
                      Show version information and exit

Run gcom-cli from inside any Git repository. The wizard will:

1. Verify the current directory is a Git working tree.
2. If nothing is staged, offer to run git add -A.
3. Ask you to pick a type from a numbered menu.
4. Ask for an optional scope.
5. Ask for a short description (required).
6. Show a preview, then run git commit.

Exit codes

Code	Meaning
0	Commit created successfully
1	User cancelled, nothing staged, empty desc.
2	Not inside a Git repository

---

Conventional Commit types

Type	When to use it
feat	A new feature for the user
fix	A bug fix for the user
docs	Documentation only changes
style	Formatting, whitespace, missing semicolons (no code change)
refactor	Code change that neither fixes a bug nor adds a feature
chore	Maintenance tasks (build tooling, deps, housekeeping)
perf	A code change that improves performance
test	Adding or correcting tests
build	Changes that affect the build system or external dependencies
ci	Changes to CI configuration files and scripts
revert	Reverts a previous commit

---

Tips

• Pair this with a Git alias for one-letter access:

  git config --global alias.c '!gcom-cli'

  Then use git c to launch the wizard.

• Combine with a commit-message linter such as commitlint to enforce the format on every commit, even when contributors do not use this tool.

---

Troubleshooting

gcom-cli: command not found The install directory is not on your PATH. Either install to /usr/local/bin or add the directory you used to your PATH (see Option 2 above).

Permission denied The script is not executable. Run chmod +x /path/to/gcom-cli.

Not inside a Git repository. You are not running the command from inside a Git working tree. cd into your project (or run git init) first.

---

License

MIT