Metadata-Version: 2.4
Name: commitsync
Version: 0.1.6
Summary: CommitSync — autonomous CLI agent for context-aware git commit messages
Author: Debonik
License-Expression: MIT
Project-URL: Homepage, https://github.com/Debonik/git-commit-agent
Project-URL: Repository, https://github.com/Debonik/git-commit-agent
Project-URL: Issues, https://github.com/Debonik/git-commit-agent/issues
Project-URL: Documentation, https://github.com/Debonik/git-commit-agent#readme
Project-URL: Changelog, https://github.com/Debonik/git-commit-agent/releases
Keywords: git,commit,cli,anthropic,conventional-commits,llm
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: anthropic>=0.40.0
Requires-Dist: tomli>=2.0; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"

# CommitSync

Autonomous CLI agent that reads staged git changes and writes context-aware, convention-compliant commit messages using the Claude API.

PyPI package: **`commitsync`** · CLI commands: **`commitsync`**, **`gitcommit`**, **`git-commit`**, **`gc`**

> **Note:** Do not run `pip install gitcommit` — that installs an unrelated, outdated PyPI package. Use `commitsync` or install from GitHub (below).

## Quick start

```bash
pipx install commitsync
export ANTHROPIC_API_KEY="sk-ant-..."
cd my-repo
git add .
commitsync --dry-run
commitsync
```

## Install

### pipx (recommended)

Isolated install, works from any directory:

```bash
pipx install commitsync
```

From GitHub (latest `main`):

```bash
pipx install git+https://github.com/Debonik/git-commit-agent.git
```

From a local checkout:

```bash
pipx install .
```

### pip

```bash
pip install commitsync
```

Or from GitHub:

```bash
pip install git+https://github.com/Debonik/git-commit-agent.git
```

### From source

```bash
git clone https://github.com/Debonik/git-commit-agent.git
cd git-commit-agent
pip install .
```

### Development

```bash
python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
```

## Commands

All entry points invoke the same CLI:

| Command | Notes |
|---------|-------|
| `commitsync` | Primary command |
| `gitcommit` | Legacy alias |
| `git-commit` | Hyphenated alias |
| `gc` | Short alias |
| `python -m gitcommit` | Module invocation |

```bash
commitsync --help
commitsync --dry-run
commitsync --yes
```

Run from inside any git repository with staged changes.

## Shell examples

### bash / zsh

```bash
export ANTHROPIC_API_KEY="sk-ant-..."
cd my-repo
git add .
commitsync
```

### fish

```fish
set -x ANTHROPIC_API_KEY "sk-ant-..."
cd my-repo
git add .
commitsync
```

### PowerShell

```powershell
$env:ANTHROPIC_API_KEY = "sk-ant-..."
Set-Location my-repo
git add .
commitsync
```

### cmd

```cmd
set ANTHROPIC_API_KEY=sk-ant-...
cd my-repo
git add .
commitsync
```

## Git alias

Add a `commit-ai` subcommand that delegates to CommitSync:

```bash
git config --global alias.commit-ai '!commitsync'
```

Usage:

```bash
git add .
git commit-ai
```

For `git-commit` or `gc`, point the alias at your preferred entry point:

```bash
git config --global alias.commit-ai '!git-commit'
```

## Configuration

User config: `~/.config/gitcommit/config.toml`

Optional repo config: `.gitcommit.toml` (overrides user settings)

Example `~/.config/gitcommit/config.toml`:

```toml
model = "claude-sonnet-4-6"
recent_commits = 10
max_diff_tokens = 6000
convention = "auto"          # or "conventional"
include_ticket = true
exclude_patterns = [".env", "secrets/*", "*.pem"]

[cli]
extra_commands = ["git-commit", "gc"]
```

### Environment variables

| Variable | Required | Description |
|----------|----------|-------------|
| `ANTHROPIC_API_KEY` | Yes | Claude API key for message generation |
| `EDITOR` / `VISUAL` | No | External editor for `[e]dit` (falls back to nano/vi/vim/notepad, then stdin) |

### Flags

| Flag | Description |
|------|-------------|
| `--dry-run` | Preview the message without committing |
| `--yes` / `-y` | Auto-accept and commit |
| `--model` | Override the configured model for this run |
| `--no-body` | Generate subject line only |
| `--verbose` | Print gathered context metadata and reasoning on stderr |
| `--benchmark` | Print estimated token costs for typical diffs and exit |

## Split suggestions

When staged changes span clearly unrelated areas (for example auth code and documentation), CommitSync prints a split suggestion on stderr before proposing a message. Use `git reset -p` or partial staging to split the work into focused commits.

## Regenerate variants

In the interactive prompt:

```
[a]ccept  [e]dit  [r]egenerate  [rc]oncise  [rd]etailed  [c]ancel
```

- **rc** — regenerate a shorter message
- **rd** — regenerate a more detailed message

## Data privacy

- **What leaves your machine:** staged diff metadata, recent commit subjects, branch name, and (when needed) small file snippets are sent to the Anthropic Claude API to generate a message.
- **What stays local:** your API key is read from the environment or config and sent only to Anthropic over HTTPS; it is never printed by default.
- **Redaction:** configure `exclude_patterns` to omit sensitive paths (e.g. `.env`, `*.pem`) from diffs and file reads before they reach the model.
- **Verbose mode:** `--verbose` prints context metadata (branch, style, diff size) on stderr — never the full diff or API key.
- **No telemetry:** CommitSync does not phone home or collect usage analytics.

Review [Anthropic's data policies](https://www.anthropic.com/policies) before use in regulated environments.

## Interactive flow

When attached to a TTY, CommitSync prompts:

```
[a]ccept  [e]dit  [r]egenerate  [rc]oncise  [rd]etailed  [c]ancel
```

- **Accept** — commit with the proposed message
- **Edit** — open `$EDITOR` (or inline stdin fallback)
- **Regenerate** — request a new message with the same context
- **Cancel** — exit without committing (staged changes unchanged)

Use `--yes` in CI or scripts to skip the prompt.

## Releasing (maintainers)

1. Set `PYPI_API_TOKEN` in GitHub repository secrets ([pypi.org](https://pypi.org/manage/account/token/)).
2. Bump `version` in `pyproject.toml` and merge to `main`.
3. Tag and push:

```bash
git tag v0.1.0
git push origin v0.1.0
```

The [release workflow](.github/workflows/release.yml) builds the package, publishes **`commitsync`** to PyPI, and creates a GitHub Release.

## License

MIT — see [LICENSE](LICENSE).
