gitFlow/readme.md

gitflow

gitflow is a CLI tool written in Go that explores every Git repository under a parent directory, scans each one's status, and presents the findings. It can rescan on a schedule — flagging repositories as they change — and, when enabled, uses an integrated AI agent to suggest the next actions for repositories that need attention.

Features

• Repo discovery — walks a directory tree and finds working trees, linked worktrees/submodule checkouts, and bare repositories, without descending into .git internals
• Status scanning — parses git status --porcelain=v2 for each repo: branch, detached HEAD, staged/modified/untracked files, ahead/behind counts, stash count, and remote URL; scans run concurrently with a bounded worker pool
• Three output formats — aligned colorized table (default), indented JSON for scripting, and a compact one-line-per-repo view
• Watch mode — rescan on an interval with change detection, desktop notifications, and graceful Ctrl-C shutdown
• AI agent — OpenAI, Ollama (local), or Anthropic providers suggest concrete next steps (commit, push, pull, …) for repositories that need attention
• Custom rules — user-defined threshold rules flag repositories (e.g. "behind ≥ 10 commits" ⇒ stale)
• Light/dark themes, NO_COLOR support, and shell completions

Installation

Requires Go 1.24+ and git on the PATH.

go install gitea.oblak.solutions/dimitar/gitFlow/cmd/gitflow@latest
# or build from a checkout:
make build

Usage

gitflow scan [flags]          Scan repositories under a directory once
gitflow watch [flags]         Repeatedly scan on an interval
gitflow config                Show the effective configuration
gitflow completion [shell]    Generate shell completions (bash/zsh/fish/powershell)
gitflow version               Print version information

When no --dir is given and stdin is a terminal, gitflow asks for the parent directory to scan, per the README's original design.

Examples

# One-shot scan of ~/projects (prompts for the directory if omitted)
gitflow scan

# JSON output for scripting
gitflow scan -d ~/projects -f json

# Skip dependency directories and cap traversal depth
gitflow scan -d ~ --exclude node_modules --exclude vendor --max-depth 3

# Watch every 30 seconds, notifying when repositories change
gitflow watch -d ~/projects -i 30s --notify

# AI suggestions via OpenAI (exports OPENAI_API_KEY or ai.api_key_env)
gitflow scan -d ~/projects --ai

# AI suggestions via a local Ollama server
gitflow scan -d ~/projects --ai --ai-provider ollama --ai-model llama3.2

# Custom rules
gitflow scan -d ~/projects   # with rules: in ~/.gitflow.yaml

# Shell completion
eval "$(gitflow completion bash)"

Flags

Flag	Default	Description
-d, --dir	.	Parent directory to scan
-i, --interval	0	Rescan interval (e.g. 30s, 5m); 0 runs once
-f, --format	table	Output format: table, json, or compact
--color	auto	Color output: auto, always, or never
--theme	dark	Color theme: dark or light
--exclude	–	Glob patterns of directories to skip (repeatable)
--max-depth	0	Maximum directory depth to scan (0 = unlimited)
--workers	8	Number of concurrent git scans
--notify	false	Desktop notifications on watch changes
--ai	false	Enable AI suggestions
--ai-provider	openai	openai, ollama, or anthropic
--ai-model	gpt-4o	Model name (provider default when empty)
--ai-execute	false	Run confirmed AI-suggested commands (experimental)

Status classes

clean · modified · ahead · behind · diverged · detached · bare · error

Configuration

Settings are resolved with the precedence flags > environment > ~/.gitflow.yaml > defaults. Environment variables use a GITFLOW_ prefix with dots as underscores (e.g. GITFLOW_FORMAT=json, GITFLOW_AI_PROVIDER=ollama). Use GITFLOW_CONFIG=/path/to/file.yaml to point at a specific config file.

# ~/.gitflow.yaml
dir: ~/projects
interval: 5m
format: table
color: auto
theme: dark
notify: true
max_depth: 3
workers: 8
exclude:
  - node_modules
  - vendor
ai:
  enabled: true
  provider: openai        # openai | ollama | anthropic
  model: gpt-4o
  api_key_env: OPENAI_API_KEY
  base_url: ""            # provider endpoint override
  execute: false          # run confirmed AI-suggested commands
rules:
  - name: stale
    field: behind         # ahead | behind | stash | changes
    op: ">="              # == | != | < | <= | > | >=
    value: 10
    label: stale

AI agent

With --ai (or ai.enabled), gitflow renders a summary of the scan to the configured provider and displays a AI SUGGESTIONS section below the table, color-coded by priority:

AI SUGGESTIONS
REPOSITORY      ACTION   PRIORITY  MESSAGE                    COMMAND
~/projects/web  commit   high      commit the untracked file  git add -A && git commit -m wip

Suggestions include repo_path, action, message, a concrete command when one is safe, and a priority (low/medium/high). AI failures degrade to a warning — a scan result is always shown. In watch mode the agent is consulted only on the first frame and when something changed, so the provider is not called on every interval.

--ai-execute (experimental)

Runs the commands of AI suggestions only after explicit per-command confirmation (y/N) and only for actions on an allowlist (commit, push, pull, stash, checkout) — LLM output can never run arbitrary shell commands. Treat this feature as experimental.

Development

make build    # build the binary (VERSION=... to stamp the version)
make test     # run the full test suite
make lint     # golangci-lint

Layout:

cmd/gitflow/       CLI commands (scan, watch, config, version, completion)
internal/ai/       AI providers (OpenAI, Ollama, Anthropic) + prompt + execution
internal/app/      orchestration: discovery → scan → result
internal/config/   flags, env, and config-file resolution
internal/git/      porcelain v2 git wrapper
internal/notify/   desktop notifications (Linux/macOS; Windows no-op)
internal/presenter/ table / json / compact output + colors + themes
internal/rules/    user-defined threshold rules
internal/scanner/  repository discovery + concurrent status scanning
internal/scheduler/ interval loop with graceful shutdown
internal/version/  ldflags-injectable version
pkg/status/        shared domain model (RepoInfo, RepoStatus, ScanResult)

CI runs build, vet, and tests (with -race) on Go 1.24/1.26 plus golangci-lint.

Future work

• Interactive TUI (bubbletea) for navigating repositories and triggering AI suggestions
• Webhook alerts (Slack/Discord) instead of desktop notifications
• ai_execute hardening and a wider command allowlist
• Fetch-history tracking to populate per-repo last_fetch metadata