gitmeup

gitmeup leverages popular LLMs to organize changes into atomic, semantic batches, and generates precise git add and git commit commands following the Conventional Commits 1.0.0 specification.

Important

It does not push anything, it just helps you decide what to commit and how to phrase it. It is designed for strict safety: it runs in dry-run mode by default, never pushes to remotes, and handles complex file paths with POSIX-compliant quoting.

Navigation

• What problem does it solve?
• How does it work?
• Installation
• Configuration
• Usage
• Examples
• Behaviour
• License
• Maintainer

What problem does it solve?

The typical workflow for complex changes involves significant manual overhead:

• Manually reviewing git status and git diff to determine logical split points.
• Crafting specific git add commands, risking missing files or including unrelated changes.
• Spending time formatting commit messages to adhere to Conventional Commits standards.
• Handling files with spaces, brackets, or special characters that require careful shell escaping.

gitmeup automates the staging and committing process:

• Groups changes into atomic, semantically focused commits (e.g., separating feat from refactor or docs).
• Generates precise git add sequences followed by git commit -m "type(scope): description".
• Enforces strict path quoting to prevent shell expansion errors with complex filenames.
• Operates safely via a default dry-run mode, requiring explicit confirmation to execute.

How it works (in practice)

From inside a git repository, gitmeup aggregates the following context:

• git diff --stat HEAD
• git status --short
• git diff HEAD with high-noise/low-value files excluded from the context body:
  • Images: *.png, *.jpg, *.svg, etc.
  • Lockfiles: package-lock.json, yarn.lock, Cargo.lock, etc. (to prevent token exhaustion).
  • Minified assets and map files.

This sanitized context is transmitted to an LLM model (default: Gemini), which returns a single code block containing:

• Batches of git add, git rm, or git mv commands.
• Corresponding git commit -m "..." commands following the Conventional Commits specification.

You can then:

• Inspect the proposed command plan (default behavior).
• Execute the plan using --apply.

No git push or remote operations are ever generated.

Installation

From PyPI (recommended)

pip install gitmeup

This installs the gitmeup CLI into your environment.

From source (editable dev install)

git clone [https://github.com/ikramagix/gitmeup](https://github.com/ikramagix/gitmeup)
cd gitmeup

python3 -m venv .venv
source .venv/bin/activate

pip install --upgrade pip
pip install -e .

Configuration

gitmeup interacts with Google Gemini via google-genai. It needs:

• A Gemini API key
• A model name (default is gemini-2.0-flash-lite unless overridden)

1. Secrets via env file (recommended)

gitmeup will automatically load:

1. ~/.gitmeup.env (global, for secrets and defaults)
2. ./.env in the current repo (for local overrides, optional)

Values in the environment override file values, and CLI flags override both.

Example global config:

# ~/.gitmeup.env
GEMINI_API_KEY=your-gemini-key-here
GITMEUP_MODEL=gemini-2.0-flash-lite

Keep ~/.gitmeup.env out of any git repo. It lives only in your home directory.

Optional per-repo overrides:

# ./.env (inside a project, usually without secrets if repo is shared)
GITMEUP_MODEL=gemini-2.0-pro

If you use a local .env with secrets, ensure .env is listed in that repo’s .gitignore.

2. Environment variables

You can also configure via plain env vars:

export GEMINI_API_KEY="your-gemini-key"
export GITMEUP_MODEL="gemini-2.0-flash-001"

3. CLI overrides (use sparingly)

The CLI accepts overrides:

gitmeup --model gemini-2.0-pro        # override model for this run only
gitmeup --api-key "you-can-but-should-not-add-your-key-here"     # override key (not recommended; leaks to history!)

Warning

For security, prefer ~/.gitmeup.env or environment variables over --api-key.

Usage

Run the tool from the root of any git repository with uncommitted changes:

gitmeup

The tool performs the following checks:

• Verifies the current directory is a git repository.
• Checks git status --porcelain for changes.
• If changes exist, generates and displays proposed commands.

Dry run (default)

gitmeup

Example output:

Proposed commands:

git add -- gitmeup/utils.py README.md
git commit -m 'docs: update README with configuration details'

Dry run: not executing commands. Re-run with --apply to execute.

No commands are executed in this mode.

Apply mode

To execute the proposed git add and git commit commands:

gitmeup --apply

gitmeup will:

• Print each command to stdout as it executes.
• Terminate immediately upon any command failure (non-zero exit code).
• Display the final git status upon completion:

Final git status:

## main...origin/main
 M src/api_client.py
?? tests/new_test.py

Review your history with:
  git log --oneline --graph --decorate -n 10

Examples

Standard workflow using environment configuration:

# Review suggested batches
gitmeup

# Execute the plan
gitmeup --apply

# Verify history
git log --oneline --graph --decorate -n 10

Override the model for a specific run:

gitmeup --model gemini-2.0-flash-lite

Behaviour

• No pushing: gitmeup never outputs git push or remote commands.
• No invented files: it only operates on files present in git status / git diff.
• Strict quoting: paths containing spaces, brackets, unicode, etc. are double-quoted; safe paths are not over-quoted.
• Atomic commits: model is instructed to group changes into small, semantic batches (e.g. refactor, docs, assets), rather than one huge “misc” commit.

You still review and decide when to run --apply.

License

This project is distributed under a dual license model.

1. Individuals & personal use: Free to use under the terms of the MIT License.
2. Organizations & businesses: A commercial license is required.

Please contact [email protected] for commercial licensing details.

See LICENSE for the full legal text.

Maintainer

Created and maintained by @ikramagix.