giv (pronounced “give”) is a POSIX-pure CLI that turns raw Git history into polished commit messages, summaries, changelogs, release notes, and announcements. It follows the Keep a Changelog spec and Semantic Versioning rules, and it works equally well with local Ollama models or any OpenAI-compatible endpoint—no Python, Node, or Docker required.

Key Features

• Subcommand workflow – message, summary, changelog, release-notes, announcement, plus update & available-releases helpers.
• Flexible AI engine – Offline with Ollama or remote via Chat-Completions API, switchable through --model-mode.
• Native Git targeting – Accepts any revision specifier or range defined in gitrevisions, and any pathspec (including :(exclude) and !*.md). (revision selection, git revisions, gitglossary)
• Version & TODO intelligence – Detects SemVer bumps and scans only the files you specify for TODOs using regex patterns. (semver.org)
• Zero-dependency, cross-platform – Runs in Bash, Zsh, Dash, or Ash on Linux, macOS, and Windows (WSL / Git Bash).
• One-line install & self-update – Secure curl | sh installer; rerun giv --update anytime for the newest release.

How it Works

1. Collect Git data – revisions, diffs, and optional TODO context. (git revisions, gitglossary)
2. Detect versions – matches SemVer strings in files indicated by --version-file or via --version-pattern. (semver.org)
3. Build prompt – merges data with your --prompt-file, following Keep-a-Changelog guidelines. (keepachangelog.com)
4. Call the model – local Ollama or any OpenAI-style endpoint.
5. Write output – inserts or updates according to --output-mode.

Examples

# Commit message for working tree
giv message

# Commit staged changes with a generated commit message
git commit -m "$(giv message --cached)"

# Create/update a changelog, scanning TODOs in *.ts files only
giv changelog --todo-files '*.ts' --todo-pattern 'TODO\\(\\w+\\):'

# Create release notes for changes from v1.2.0 to HEAD with a remote endpoint
giv release-notes v1.2.0..HEAD \
    --model-mode remote \
    --api-model some-new-model \
    --api-url https://api.example.com/v1/chat/completions

Installation

curl -fsSL https://raw.githubusercontent.com/giv-cli/giv/main/install.sh | sh

The script downloads the latest binary links it in $PATH

Usage Overview

giv <subcommand> [revision] [pathspec] [OPTIONS]

| Element | Meaning | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | revision | Any Git revision or revision-range (HEAD, v1.2.3, abc123, HEAD~2..HEAD, origin/main...HEAD, --cached, --current). (revision selection, git revisions) | | pathspec | Standard Git pathspec to narrow scope—supports magic prefixes, negation (! or :(exclude)), and case-insensitive :(icase). (git pathspec, gitglossary) |

Option Groups

1 General

| Flag | Description | | -------------------- | ------------------------------- | | -h, --help | Show help and exit | | -v, --version | Show giv version | | --verbose | Debug / trace output | | --dry-run | Preview only; write nothing | | --config-file PATH | Shell config sourced before run |

2 Revision & Path Selection (what to read)

| Flag | Description | | ------------------------- | --------------------- | | (positional) revision | Git revision or range | | (positional) pathspec | Git pathspec filter |

3 Diff & Content Filters (what to keep)

| Flag | Description | | ------------------------- | ------------------------------------------------------ | | --todo-files PATHSPEC | Pathspec that marks files to scan for TODOs | | --todo-pattern REGEX | Regex evaluated inside files matched by --todo-files | | --version-file PATHSPEC | Pathspec of file(s) to inspect for version bumps | | --version-pattern REGEX | Custom regex that identifies version strings |

4 AI / Model (how to think)

| Flag | Description | | ------------------- | ------------------------------------------- | | --model MODEL | Local Ollama model name | | --model-mode MODE | auto (default), local, remote, none | | --api-model MODEL | Remote model when --model-mode remote | | --api-url URL | Remote API endpoint |

5 Output Behaviour (where to write)

| Flag | Description | | ----------------------- | ------------------------------------------------ | | --output-mode MODE | auto, prepend, append, update, none | | --output-version NAME | Overrides section header / tag | | --output-file PATH | Destination file (default depends on subcommand) | | --prompt-file PATH | Markdown prompt template to use |

6 Maintenance Subcommands

available-releases · update

Environment Variables

| Variable | Purpose | | ---------------- | -------------------------------------------------- | | GIV_API_KEY | API key for remote model | | GIV_API_URL | Endpoint default if --api-url is omitted | | GIV_MODEL | Default local model | | GIV_MODEL_MODE | auto, local, remote, none (overrides flag) |

Subcommands

| Subcommand | Action | | --------------------- | ------------------------------------ | | message (default) | Draft an AI commit message | | summary | Human-readable summary of changes | | changelog | Create or update CHANGELOG.md | | release-notes | Longer notes for a tagged release | | announcement | Marketing-style release announcement | | available-releases | List script versions | | update | Self-update giv |

Requirements

• Git ≥ 2.25 (git-scm.com)
• curl
• POSIX-compliant shell (Bash, Zsh, Dash, Ash)
• (Optional) Ollama for offline LLMs (github.com)

License

CC-BY. If giv helps you give better releases, please ⭐ the repo and spread the word!

Contributing

I'll help you fill in the "Contributing" section with the requested information. Here's a suggestion:

Contributing

We welcome contributions from everyone! If you'd like to contribute, please follow these steps:

1. Clone the repository and update submodules:

   git clone https://github.com/giv-cli/giv.git
   cd giv
   git submodule update --init --recursive

2. Create a new branch for your changes:

   git checkout -b my-feature-branch

3. Make your changes and commit them:

   # Make changes...
   
   # Verify all tests pass
   bats tests/*.bats
      
   git add .
   git commit -m "$(giv message --staged)"

4. Push your changes to GitHub:

   git push origin my-feature-branch

5. Create a pull request on GitHub.

Please ensure that your contributions adhere to the existing code style and include appropriate tests if necessary.