Grove

Semantic Git helper for commits, branches, push, and pull.

Grove is based on the ideas behind Conventional Commits and Conventional Branch.

$ grove -c src/main.py README.md
$ grove -cp src/main.py 20 "change auth contract"
$ grove -b 6 observability-pipeline
$ grove push

Features

Core behavior of Grove for semantic commits, branches, push, and pull.

Strict Conventional Commit header

Builds commit messages as `<type>[optional scope][optional !]: <description>` instead of using a custom Grove-specific header.

Interactive scope and breaking flag

Lets you add an optional scope and mark breaking changes with `!` while keeping the flow guided and fast.

Custom commit and branch types

The last menu option is `Custom`, so you can create headers like `system(api)!: test` and branches like `system/observability`.

Interactive commits

Guides you through semantic commits when arguments are missing and keeps the flow fast when they are present.

Interactive branches

Creates semantic branch names from a guided prompt and switches to the branch automatically.

Explicit staging only

Stages only the files you passed to the command instead of adding unrelated changes from the repository.

Commit and push

Supports one-step commit and push with `-cp` or `-c -p`, using the current branch as the remote target.

Smart remote behavior

Pushes and pulls against the matching branch on `origin`, setting upstream automatically when needed.

Safer confirmation flow

All `git add` and `git commit` actions happen only after the final confirmation prompt.

Installation

Install Grove with the helper script or set it up manually.

Using install.py

The easiest way is to use the installer script from the repository root.

curl -o install.py https://github.com/viniciusnevescosta/grove/blob/main/install.py
python install.py

Manual installation

You can also download the main script directly:

curl -O https://github.com/viniciusnevescosta/grove/blob/main/main.py

Windows

Install Python 3.
Download main.py.
Save it locally.
Run it with python main.py.

You can optionally create a grove.bat file so the command is available as grove.

@echo off
python C:\path\to\main.py %*

macOS / Linux

Make sure Python 3 is installed.
Save the script as grove.
Add the shebang below at the top of the file.
Make it executable.
Move it to a directory in your PATH.

#!/usr/bin/env python3

chmod +x grove
mv grove ~/.local/bin/grove

Usage

Grove keeps the flow interactive when you provide only part of the command.

Commit

grove -c <files...>
grove -c <files...> <type-number> <description> [body]

# standard type
feat(parser): add array support

# breaking change
feat(api)!: remove legacy endpoint

# custom type
system(api)!: change auth contract

After confirmation, Grove stages only the provided files and creates a Conventional Commit header in the format <type>[optional scope][optional !]: <description>.

The scope is optional.
Breaking changes are marked with ! before the colon.
Use /br in the optional body to create line breaks or footer blocks.

Commit and push

grove -cp <files...>
grove -cp <files...> <type-number> <description> [body]

grove -c -p <files...>
grove -c -p <files...> <type-number> <description> [body]

grove -cp src/main.py README.md
grove -cp src/main.py README.md 1 "add login page"
grove -c -p src/main.py 20 "change auth contract" "BREAKING CHANGE: token payload changed"

After the commit succeeds, Grove automatically pushes the current local branch to the corresponding remote branch. If the branch does not yet have an upstream, Grove uses git push -u origin <current-branch>.

Branch

grove -b
grove -b <type-number> [description]

grove -b
grove -b 1 add-login-page
grove -b 6 observability-pipeline

Branch descriptions are normalized to slug format before the branch name is created, and the last menu option lets you provide a custom type such as system.

Push

grove push

Pushes the current local branch to the matching branch on origin.

If no upstream is configured yet, Grove uses git push -u origin <current-branch>.

Pull

grove pull

Pulls remote changes from the matching branch on origin into the current local branch.

grove pull pulls from the branch with the same name on origin.

Behavior

Grove completes missing pieces interactively and only performs Git actions after confirmation.

If you provide only part of the command, Grove completes the remaining steps interactively.

If you provide files only, it asks for the commit type, optional scope, breaking flag, description, and optional body.
If you provide files and type, it keeps the missing Conventional Commit pieces interactive.
If you provide branch type only, it asks only for the missing description, and custom types are supported in the last option.
If you use -cp or -c -p, Grove commits first and then pushes automatically.

All git add and git commit actions only happen after the final confirmation.

Commit types

Grove provides a numeric menu of common types and a final Custom option for your own Conventional Commit noun.

feat

Adds a new feature.

fix

Represents a bug fix.

docs

Documentation changes.

test

Test additions or updates.

build

Build system or dependency changes.

perf

Performance improvements.

style

Formatting or style-only changes.

refactor

Code restructuring without changing behavior.

chore

Routine maintenance tasks.

ci

CI/CD configuration changes.

revert

Reverts a previous change.

security

Security-related changes.

wip

Work in progress.

raw

Raw data updates.

cleanup

Cleanup or dead code removal.

remove

Files or code removals.

locale

Localization updates.

access

Accessibility improvements.

ux

User interface or user experience changes.

custom

Provide your own type, such as `system`.

Example output

system(api)!: change auth contract

Branch types

The generated branch name follows a semantic format, with a final Custom option for your own type prefix.

feat

For new features.

fix

For bug fixes.

hotfix

For urgent fixes.

release

For release preparation.

chore

For maintenance tasks.

custom

Provide your own branch type, such as `system`.

Format

<type>/<description>

Example

system/observability-pipeline