Skip to content

README.md

Latest commit

 

History

History
179 lines (127 loc) · 7.58 KB

README.md

File metadata and controls

179 lines (127 loc) · 7.58 KB

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 with local Ollama models or any OpenAI-compatible.

Key Features

  • Subcommand workflow – message, summary, changelog, release-notes, announcement, plus update & available-releases helpers.
  • Flexible AI engine – Supports both local and remote AI models.
  • 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)
  • 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, or the default prompt for that command.
  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 \
    --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

Requirements

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

Usage Overview

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

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

Revision & Path Selection

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

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

Output Behaviour

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

Diff & Content Filters

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

AI / Model

Flag Description
--model MODEL Local Ollama model name
--api-model MODEL Remote model when --model-mode remote
--api-url URL Remote API endpoint

Environment Variables

Variable Purpose
GIV_API_KEY API key for remote model
GIV_API_URL Endpoint default if --api-url is omitted

License

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

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.