gitgrow 0.1.0a1

AI developer agent for clean commits, docs, changelogs, and GitHub progress.

GitGrow

Build daily. Commit cleanly. Grow visibly.

GitGrow is a Python-first AI developer CLI agent that converts real coding work into clean commits, updated documentation, changelogs, dev logs, and meaningful GitHub activity.

Status: v0.1.0-alpha — Python CLI MVP

---

Why GitGrow?

Most developers do real work but lose track of it. Commit messages are vague, documentation falls behind, and progress feels invisible. GitGrow fixes this by sitting between your editor and Git — scanning what changed, generating professional commit messages, keeping docs in sync, and creating daily progress records.

This is not a fake activity bot. GitGrow only commits real changes you approve.

---

Installation

pip install gitgrow

Requirements:

• Python 3.10 or higher
• Git
• Optional: GitHub CLI for GitHub authentication
• Optional: OpenAI API key for AI-powered commit messages (fallback works without it)

---

Quick Start

cd my-project
gitgrow init
gitgrow auth github
gitgrow scan
gitgrow commit

---

Commands

Command	Description
gitgrow init	Initialize GitGrow inside any git repository
gitgrow auth github	Connect to GitHub using the GitHub CLI
gitgrow scan	Scan current changes and classify their impact
gitgrow commit	Generate a commit message, preview it, and commit
gitgrow docs	Sync README, CHANGELOG, and docs with changes
gitgrow daily	Create a dated daily progress devlog
gitgrow sync	Run docs and daily together

---

Example Workflow

# One-time setup
cd my-project
gitgrow init
gitgrow auth github

# Daily workflow
# ... make some code changes ...
gitgrow scan        # see what changed and how it's classified
gitgrow commit      # generate → preview → approve → commit
gitgrow daily       # create today's progress log

What gitgrow commit does

Scan git diff
    ↓
Classify change type (feat / fix / docs / test / refactor / ...)
    ↓
Run safety checks (tests, linters, secret scan)
    ↓
Generate commit message (AI or deterministic fallback)
    ↓
Show preview for review
    ↓
Confirm → stage → commit
    ↓
Optional push

---

Commit Messages

GitGrow generates Conventional Commit style messages:

feat(auth): add JWT authentication flow
fix(api): handle missing token errors
docs(readme): update setup instructions
test(auth): add login validation tests

Messages are always shown for review before commit. You can edit or cancel at any point.

---

AI and Fallback Mode

GitGrow works in two modes:

AI mode (requires OPENAI_API_KEY):

export OPENAI_API_KEY=sk-...
gitgrow commit

Uses GPT-4o-mini to generate context-aware commit messages, doc updates, changelog entries, and devlogs.

Fallback mode (no API key needed):

gitgrow commit  # works without OPENAI_API_KEY

Uses deterministic, rule-based generation from the diff. Always produces valid Conventional Commit messages. No API calls, no network required.

---

DocSync

When GitGrow detects significant changes (new features, API routes, env vars, dependencies), gitgrow docs updates your documentation safely using controlled blocks:

<!-- GITGROW:FEATURES:START -->
(GitGrow updates only this section)
<!-- GITGROW:FEATURES:END -->

<!-- GITGROW:SETUP:START -->
<!-- GITGROW:SETUP:END -->

<!-- GITGROW:API:START -->
<!-- GITGROW:API:END -->

Content outside these blocks is never touched unless you use --no-safe-only.

---

Safety Principles

• Nothing commits without your approval. Every commit requires explicit confirmation by default.
• No secrets committed. GitGrow scans diffs for API keys, tokens, and credentials and blocks them.
• No empty commits. Blocked at the pre-commit stage.
• No token storage. GitHub authentication uses the GitHub CLI — no raw tokens are saved anywhere.
• Tests run first. Configure check commands in .gitgrow/config.yml and they run before every commit.
• You can always skip checks with gitgrow commit --skip-checks but you will be warned.

---

GitHub Authentication

GitGrow uses the GitHub CLI for MVP authentication:

gitgrow auth github

This runs gh auth login if needed, reads your username, and stores only connection metadata (no tokens) in .gitgrow/config.yml.

---

Configuration

After gitgrow init, a config file is created at .gitgrow/config.yml:

project:
  name: my-project
  type: python

git:
  remote: origin
  default_branch: main
  auto_push: false

checks:
  enabled: true
  before_commit:
    - pytest
    - ruff check .

safety:
  require_confirmation: true
  block_secrets: true
  allow_empty_commits: false

ai:
  enabled: true
  provider: openai
  model: gpt-4o-mini

---

DevLog

gitgrow daily creates a dated progress log at devlog/YYYY/MM/YYYY-MM-DD.md:

# Progress Log - 2025-01-15

## Today's Momentum
Implemented JWT authentication and added test coverage for login flow.

## What Changed
- src/auth/login.py
- tests/test_auth.py

## What I Learned
JWT expiry handling needs to account for clock skew.

## Next Small Step
Add refresh token support.

---

Files Created by gitgrow init

gitgrow.md              # human-readable project instructions for GitGrow
.gitgrow/config.yml     # machine config (YAML)
.gitgrowignore          # files GitGrow won't scan
devlog/                 # dated progress logs

---

Current Status

v0.1.0-alpha — Python CLI MVP

This is the first alpha release. The local CLI workflow is fully functional. The following are not yet implemented:

• GitHub App (planned for Phase 10)
• npm wrapper (planned for later)
• Hosted dashboard or team mode
• PyPI distribution (TestPyPI verification in progress)

---

Roadmap

Phase	Status	Description
Phase 0	Done	Product definition
Phase 1	Done	Python CLI foundation
Phase 2	Done	gitgrow init
Phase 3	Done	gitgrow auth github
Phase 4	Done	Project scanner
Phase 5	Done	Smart commit writer
Phase 6	Done	DocSync
Phase 7	Done	Safety checks
Phase 8	Done	DevLog
Phase 9	Done	Git executor
Phase 10	Planned	GitHub App
Phase 11	In progress	PyPI release
Phase 12	Planned	Public launch

---

Contributing

Issues and pull requests are welcome. See docs/security.md for security notes.

---

License

MIT