A lightweight global CLI for conventional commits. Install once, use in any repo.
committy (gcv) is a global CLI tool that brings structure to your git commits without locking you into a project setup. You install it once and it works everywhere — with or without a config file.
Run gcv for an interactive prompt, or commit inline in one line. When you're working with a team, drop a .gc.json in the repo root to share types, scopes, and team prefixes — and committy picks it up automatically.
Guided prompt when you need it. One-liner when you don't. Falls back gracefully when args are partial.
No per-project config required. Works in any git repo the moment you install it.
Share commit types, scopes, and team prefixes via a single .gc.json config file.
Walks up from your current directory to find the nearest config. Sensible defaults if none found.
What's shipped and what's coming next.
gcv commit — interactive + inline with graceful fallbackgcv init — scaffolds .gc.json with commits sectiongcv branch — interactive + inlineallowed configgcv init extended with branches sectiongcv changelog — generates from git log--from, --dry-run flagsgcv bump — semver auto-detect from commits--minor, --dry-run flagsYou need Node 18+ and a git repo with staged files.
# 1. Install globally
npm install -g committy
# 2. Stage your changes
git add .
# 3. Run the interactive prompt
gcvYou'll be guided through type → scope → message. committy runs git commit for you.
Run gcv with no arguments to open the guided prompt. Scope is always optional — skipping it produces feat: message, not feat(): message.
gcv
# Prompt:
? Type: feat
? Scope: (optional, press Enter to skip)
? Message: fix svg images not loading
# Result:
git commit -m "feat: fix svg images not loading"Pass type, scope, and message directly as arguments for a fast one-liner. If args are partial or invalid, committy drops into the prompt with valid fields pre-filled.
# type + scope + message
gcv feat auth fix svg images not loading
→ git commit -m "feat(auth): fix svg images not loading"
# type + message (no scope)
gcv fix update readme
→ git commit -m "fix: update readme"Argument parsing rules:
| Args | Parsed as |
|---|---|
| 1 arg | message only — prompts for type and scope |
| 2 args | type + scope (if scope matches config), or type + message |
| 3+ args | type + scope + message (rest joined with spaces) |
Run gcv init to scaffold a .gc.json in the current directory. Commit this file so the whole team shares the same types and scopes.
gcv initIf you're not at the repo root, committy warns you before writing. If .gc.json already exists, it asks before overwriting.
.gc.json is optional. When present it must be valid JSON — malformed config prints an error and exits. No silent fallback.
{
"types": ["feat", "fix", "chore", "docs", "refactor", "test"],
"scopes": [
{ "name": "auth", "team": "PCUST" },
{ "name": "payment", "team": "PCUST" },
{ "name": "dashboard", "team": "PINT" },
{ "name": "deps" }
]
}| Field | Type | Required | Description |
|---|---|---|---|
| types | string[] | Yes | Non-empty list of allowed commit types |
| scopes | object[] | Yes | List of scope definitions (can be empty []) |
| scopes[].name | string | Yes | Scope identifier used in commits |
| scopes[].team | string | No | Team prefix inserted before the message |
Scope names must be unique. Scopes without team produce no prefix.
When a scope has a team value, the commit message becomes:
type(scope): TEAM message
# Example with { "name": "auth", "team": "PCUST" }:
feat(auth): PCUST fix svg images not loadingUsed when no config is present. Follows Conventional Commits v1.0.0.
feat fix chore docs refactor test style perf ci build revert| Command | Description |
|---|---|
| gcv | Interactive commit prompt |
| gcv <type> [scope] <message> | Inline commit |
| gcv init | Scaffold .gc.json in current directory |
| gcv --help / -h | Print usage |
| gcv --version / -v | Print installed version |