Command Reference

gitaiflow has a single-command surface — every feature is a flag on the root gitaiflow invocation rather than a subcommand.

text

usage: gitaiflow [--path PATH] [--remote REMOTE] [--base-branch BASE_BRANCH]
                  [--skip [PATH_OR_PATTERN ...]] [-o OUTPUT_DIR] [--markdown]
                  [--no-chunk] [--change-summary] [--show-analysis]
                  [--last-summary] [--regenerate-summary] [--allow-billing]
                  [--changelog] [--since DATE] [--until DATE] [--release-notes]
                  [--list-models] [--free-only] [--json]
                  [--version] [--usage [current|VERSION]]
                  [--telemetry {enable,disable,status,history}] [--uninstall]

An AI provider must be configured before any summary-generating flag will run — see configuration.md. --list-models, --usage, --telemetry, and --version are exceptions: they exit immediately and never require provider configuration or touch Git.

Target selection

bash

gitaiflow --path mailer/                # summarize a directory
gitaiflow --path users/views/logout.py  # summarize a single file
gitaiflow --path .                      # summarize the whole repo (default)

Defaults to the current directory when --path is omitted.

`--remote` / `--base-branch`

bash

gitaiflow --path . --remote upstream --base-branch develop

--remote defaults to the current branch's upstream remote if it has one, else the GITAIFLOW_REMOTE environment variable if set, else origin if present, else the only remote if there's exactly one. If none of those resolve, gitaiflow fails with an explicit error listing the available remotes rather than guessing. --base-branch defaults to the remote's detected default branch (its HEAD), falling back to main.

`--skip`

bash

gitaiflow --path . --skip dist/ "*.svg" "*.json"

Accepts three kinds of entries, space-separated (not comma-separated — each is a distinct CLI argument):

A directory (e.g. dist/, build/vendor) — skips everything under it.
An exact file path (e.g. src/generated.py).
A file-type pattern like *.svg or *.json — skips every matching file wherever it is. Quote these so your shell doesn't expand the *.

Paths are relative to --path unless given as absolute paths.

`-o`, `--output-dir`

bash

gitaiflow --path . -o artifacts/

Root artifact output directory (default: change-summary). With --changelog, pass the same value used when the change-summary was generated so the changelog reads from the right place.

`--markdown`

bash

gitaiflow --path . --markdown

Also writes a human-facing Markdown view derived from the same canonical JSON payload.

`--no-chunk`

bash

gitaiflow --path . --no-chunk

By default, when --path points at a directory, gitaiflow groups changed files by their top-level subdirectory and generates one commit summary per group — keeping individual AI requests small enough to avoid provider context-length limits and free-tier token quotas on large diffs. --no-chunk forces a single AI request covering the entire diff instead.

With --change-summary, each chunk's title/body is printed under a === <chunk-name> === header.

`--change-summary` / `--show-analysis`

bash

gitaiflow --path . --change-summary
gitaiflow --path . --change-summary --show-analysis

--change-summary prints just the commit title/body to stdout — pipeable straight into git commit -F - (this flag was previously named --print-commit). --show-analysis additionally prints the model's raw reasoning/analysis text (if any) that preceded its final TITLE:/BODY: answer; off by default, useful for debugging odd or truncated commit messages.

`--last-summary`

bash

gitaiflow --path . --last-summary

Prints the most recently generated change-summary straight from disk — no git diff, no AI call, no new run. Reads only the single latest saved change-summary/ JSON file, across any past run or day, and says so instead of generating one if none exists yet.

`--regenerate-summary`

bash

gitaiflow --path . --regenerate-summary

Forces a fresh AI summary for every group even if its diff exactly matches one already summarized before (on any previous day, not just today). Normally a matching diff skips the AI call and reuses the earlier summary to save cost; this flag forces regeneration anyway — useful after change-summary/ was deleted by mistake, or when you just want a fresh take.

`--allow-billing`

bash

gitaiflow --path . --allow-billing

Skips the pre-flight free-model check. For OpenRouter, this bypasses the catalog check that normally blocks non-free/unverifiable model IDs. For other providers (Gemini, OpenAI, Ollama, xAI-via-custom, ...) it also silences the passive reminder that gitaiflow can't verify their pricing.

Changelog generation

bash

gitaiflow --changelog --since 2026/08/01 --path .                # exact date, through today
gitaiflow --changelog --since "3 days ago" --path .               # relative, through right now
gitaiflow --changelog --since "2 weeks ago" --until "3 days ago" --path .
gitaiflow --changelog --since 2026/08/01 --path . -o artifacts/   # match a custom -o used to generate change-summary

--since (required with --changelog, defaults to the start of today when omitted) and --until (optional) each accept either an exact date (YYYY/MM/DD) or a relative expression — <N> minute(s)/hour(s)/day(s)/week(s)/month(s) ago. Years aren't a supported unit — use an exact date for anything that wide.

A range that resolves entirely before the repository's first commit, or into the future, is rejected upfront with an error instead of silently producing an empty changelog.

gitaiflow resolves <remote>/<base-branch> the same way a normal summary run does, then builds the changelog primarily from change-summary JSON artifacts already generated for that range. If more than one artifact touches the same file within the range, only the newest one is used. An artifact generated against a different base than the one resolved for this run is not counted; if no artifacts exist for the range, gitaiflow falls back to git log on the resolved base ref. Commits are grouped by conventional-commit type and prepended above any existing CHANGELOG.md content — existing entries are never modified, and a re-run for the same version replaces that version's block rather than duplicating it.

--changelog doesn't call an AI provider — it either reads already-generated JSON or falls back to git log — so it never touches the local usage log or telemetry either way; those are only recorded on a normal summary run.

`--release-notes`

bash

gitaiflow --release-notes

(Re)writes RELEASE_NOTES.md at the repo root, generated by the AI from the CHANGELOG.md entry for the current resolved project version — run --changelog first if that entry doesn't exist yet. Always a full overwrite describing the release currently being cut, not a rolling history; uses the same AI provider/model and error handling as a normal summary run.

Model discovery

bash

gitaiflow --list-models
gitaiflow --list-models --free-only
gitaiflow --list-models --json

See model-selection.md for the full model-discovery and selection workflow.

`--usage`

bash

gitaiflow --usage                    # most recent run
gitaiflow --usage current            # same as bare --usage
gitaiflow --usage 1.0.6              # aggregate for runs recorded under this gitaiflow version
gitaiflow --usage --since "1 week ago" --until "2 days ago"   # custom date range

Shows local usage stats (tokens in/out, duration, success) from ~/.gitaiflow/usage.jsonl and exits — never runs a summary.

`--telemetry`

bash

gitaiflow --telemetry enable
gitaiflow --telemetry disable
gitaiflow --telemetry status
gitaiflow --telemetry history

Durably sets or checks anonymous usage telemetry consent, independent of the current terminal session (unlike GITAIFLOW_TELEMETRY, which only affects the current process). history shows every recorded answer with its version and timestamp. Each of these exits immediately — see telemetry.md for the full consent model.

`--version`

bash

gitaiflow --version

`--uninstall`

bash

gitaiflow --uninstall

Removes the gitaiflow binary and its local state files, and warns if any AI_*/GITAIFLOW_* environment variables are still exported in your current shell.

Output

Every summary run writes one JSON file to change-summary/<YYYY>/<MM>/<DD>/json/<target>-<timestamp>.json, partitioned by the date of the run so history from previous days is never touched or re-scanned by a later run:

json

{
  "generated_at": "2026-08-19T14:32:07+05:30",
  "target": "mailer",
  "target_type": "directory",
  "repository": "paystream",
  "branch": "feature/mailer-retry",
  "base": "origin/main",
  "author": { "name": "Chandrashekhar Bhosale", "email": "shekhar@djangoplay.org" },
  "change_window": {
    "first_change_at": "2026-08-18 09:12:03",
    "last_change_at": "2026-08-19 14:30:11"
  },
  "files_changed": [
    { "path": "mailer/tasks.py", "status": "modified" },
    { "path": "mailer/retry.py", "status": "added" }
  ],
  "model": { "provider": "gemini", "name": "gemini-flash-lite-latest" },
  "commit": {
    "title": "mailer: add retry backoff for failed sends",
    "body": "- Added exponential backoff retry logic in retry.py\n- tasks.py now retries send_mail up to 3 times on failure\n- No changes to public function signatures"
  },
  "summary": "(same content as commit.body)"
}

author, branch, base, change_window, and files_changed come straight from Git — never from the model — so they're accurate even if the AI call fails or hallucinates. commit.title / commit.body are the only model-generated fields, and they're the ones designed to be commit-ready as-is. base is also what --changelog matches against — it only includes an artifact whose base equals the <remote>/<base-branch> resolved for that run.

--markdown renders a second, human-facing view from the same JSON into change-summary/<YYYY>/<MM>/<DD>/markdown/ — the JSON is always the source of truth.

Local usage log

Every summary run appends one line to ~/.gitaiflow/usage.jsonl — timestamp, repo name, target type, model used, estimated token counts, duration, success. This file never leaves your machine. It exists so you can see your own usage (--usage) and, optionally, set soft daily limits:

bash

export GITAIFLOW_MAX_RUNS_PER_DAY=20
export GITAIFLOW_MAX_TOKENS_PER_DAY=50000

When set, gitaiflow prints a warning once you've crossed the threshold for the day. This is a courtesy guardrail against accidentally running up a cloud-model bill, not enforcement — it's a local file, and any user can clear it.

README.md — user-guide index
configuration.md — AI provider environment variables
telemetry.md — the full opt-in telemetry consent model
../api/README.md — the flag surface as a stable contract

#Target selection

#--remote / --base-branch

#--skip

#-o, --output-dir

#--markdown

#--no-chunk

#--change-summary / --show-analysis

#--last-summary

#--regenerate-summary

#--allow-billing

#Changelog generation

#--release-notes

#Model discovery

#--usage

#--telemetry

#--version

#--uninstall

#Output

#Local usage log

#Related

Target selection

`--remote` / `--base-branch`

`--skip`

`-o`, `--output-dir`

`--markdown`

`--no-chunk`

`--change-summary` / `--show-analysis`

`--last-summary`

`--regenerate-summary`

`--allow-billing`

Changelog generation

`--release-notes`

Model discovery

`--usage`

`--telemetry`

`--version`

`--uninstall`

Output

Local usage log

Related