GCT

Repository

Features

• Conversational AI Commits: Generate a commit message and then "chat" with the AI to refine it until it's perfect.
• Multi-Provider Support: Works with over 10 AI providers, including OpenAI, Anthropic, Google (AI Studio & Vertex AI), Mistral, Amazon Bedrock, and any OpenAI-compatible endpoint.
• Git Hosting Integration: Explains pull/merge requests and proposes solutions for issues from GitHub, GitLab, and Forgejo.
• AI-Generated Changelogs: Automatically create user-facing changelogs from any set of git changes (gct ai log).
• AI-Powered Diff Analysis: Get a high-level explanation of any commit, branch, or staged changes (gct ai diff).
• Guided Setup: An interactive wizard (gct init) makes setup for any provider simple and fast.
• Automated Changelog Workflows: Generate and commit changelogs automatically on new tags with gct setup.
• Custom Guidelines: Enforce project-specific styles for commits and changelogs by providing your own guide files.

Getting Started

The easiest way to get started is with the model preset wizard. It provides a curated list of popular, high-performance models and configures the provider for you. In your project directory, run:

gct init model

For a fully manual setup where you enter the provider and model name yourself, run gct init.

Configuration

GCT can be configured via a local gct.yaml file, a global config file, or environment variables. The init command will help you create the local gct.yaml file, which holds the primary configuration for all AI commands.

Security Note: This file contains your API key. The gct init command will automatically add gct.yaml to your .gitignore file to prevent accidentally committing secrets.

Supported AI Providers

GCT supports a wide range of AI providers: Google AI Studio, Google Vertex AI, OpenAI, OpenAI Compatible, Azure OpenAI, Anthropic, OpenRouter, DeepSeek, Mistral, Alibaba, Hugging Face, Amazon Bedrock, and xAI.

Supported Git Hosting Providers

The ai pr and ai issue commands integrate with the following platforms (via their respective CLIs):

• GitHub (via gh)
• GitLab (via glab)
• Forgejo and other Gitea forks (via fj)

Configuration Fields

• provider: The AI service you want to use.
• model: The specific model/deployment name from your chosen provider.
• api: Your secret API key.
• commits.guides & changelogs.guides: Lists of local files containing formatting rules.
• endpoint: (Optional) The base URL, only for the "OpenAI Compatible" provider.
• gcp_project_id, gcp_region: (Optional) Required only for "Google Vertex AI".
• aws_region, aws_access_key_id, aws_secret_access_key: (Optional) Required only for "Amazon Bedrock".
• azure_resource_name: (Optional) Required only for "Azure OpenAI".
• cache.enabled: (Optional) To store generated responses locally and reduce costs.

Model Recommendations

Choosing a model can be tough. Here are some recommended starting points for GCT's use case:

Commands

GCT is a command-line tool. Here are the available commands, grouped by category:

Core Commands

Manual Git Commands

AI Git Commands

Installation

GCT must be built from source. To do so, you need to have go installed.

# For Linux/macOS
./build/build-all.sh

# For Windows
./build/build-all.ps1

Usage

GCT (Git Commit Tool) is a command-line interface designed to streamline your Git workflow with interactive forms and powerful AI integrations.

Getting Started: The init Command

The first and most important step is to configure GCT for your project. This is required for all AI-powered commands. GCT offers two ways to create your configuration file:

Recommended: gct init model

This is the easiest way to get started. The model command launches a wizard that shows a curated list of high-performance, popular models. Simply choose a model, and GCT will configure the provider and model for you.

gct init model

Manual Setup: gct init

This command launches a fully manual, step-by-step setup wizard. It will ask you for every detail, including the provider name, the specific model ID, and any provider-specific information (like API endpoints or cloud project IDs).

gct init

Both commands will create a gct.yaml file in your project's root directory. For more details on the configuration options, please see the gct.yaml Configuration Reference page.

Command Categories

GCT's commands are divided into three main categories:

• Core Commands: For managing the GCT application and configuration.
• Manual Git Commands: Interactive forms for common Git tasks that do not require AI.
• AI-Powered Git Commands: Commands that leverage AI to automate and enhance your workflow.

Core Commands

• gct init model
  • Starts a guided setup wizard with a list of recommended models.
• gct init
  • Starts a fully manual setup wizard to create or overwrite the gct.yaml file.
• gct setup <github|gitlab>
  • Generates a CI/CD workflow file to automate changelog generation. When you push a new version tag (e.g. v1.2.3), the workflow will run, generate a changelog for the new version, and commit it to a Changelogs.md file in your repository.
  • Usage:
    • gct setup github (Creates .github/workflows/changelog.yml)
    • gct setup gitlab (Creates .gitlab-ci.yml)
• gct version
  • Shows the currently installed GCT version and build details.
• gct about
  • Displays information about the GCT project.
• gct help
  • Shows the detailed help message listing all available commands.

Manual Git Commands

• gct commit

  • Launches a full-screen interactive form to guide you through creating a well-structured commit message. It prompts for a Type, Subject, and Body, then asks for confirmation before committing.

• gct commit edit

  • Allows you to easily amend the most recent commit's message. It fetches the last message and pre-populates the same interactive form from gct commit.

AI-Powered Git Commands

• gct ai commit [context]

  • This is the flagship feature. It automatically generates a commit message from your staged changes and then allows you to perfect it conversationally.
  • Workflow:
    1. The AI generates a commit message based on your staged code and any guidelines in your gct.yaml.
    2. The message is displayed for your review.
    3. You are prompted with options:
       • [c] to chat/change: Provide a follow-up instruction (e.g. "add a co-author," "make the subject shorter") and the AI will revise the message.
       • [e] to edit: Open the generated message in the manual TUI editor for full control.
       • [Enter] to commit: Accept the message and commit it directly.
       • [q] to quit: Cancel the operation.
  • Providing Context: You can give the AI extra information by passing it as an argument:

    gct ai commit "This change was co-authored by Jane Doe and fixes issue #123."

• gct ai diff [arguments]

  • Asks an AI to act as an expert code reviewer, providing a high-level explanation of code changes. The output is displayed in a clean, scrollable TUI.
  • Usage Examples:
    • gct ai diff (Explains unstaged changes)
    • gct ai diff --staged (Explains staged changes)
    • gct ai diff <commit-hash> (Explains a specific commit)
    • gct ai diff <branch-name> (Explains changes relative to another branch)

• gct ai log [arguments]

  • Generates a user-facing changelog entry from a set of code changes. It uses the same arguments as gct ai diff but provides output formatted for release notes.
  • Usage Examples:
    • gct ai log (Creates a changelog for unstaged changes)
    • gct ai log --staged (Creates a changelog for staged changes)
    • gct ai log <commit-hash> (Creates a changelog for a specific commit)
    • gct ai log <branch-name> (Creates a changelog for changes on a branch)
    • gct ai log v1.0.0 v1.1.0 (Creates a changelog for changes between two tags)
  • Non-Interactive Output:
    • For use in CI/CD pipelines or scripts, add the -c flag to print the raw markdown output directly to the console without the interactive viewer.
    • gct ai log -c v1.0.0 v1.1.0

• gct ai pr <number>

  • Summarizes a pull request or merge request from a supported git hosting provider (GitHub, GitLab, Forgejo). It provides a high-level overview of the changes, the purpose, and the solution.
  • Usage:
    • gct ai pr 123

• gct ai issue <number>

  • Proposes a technical implementation plan for an issue from a supported git hosting provider. It outlines the "why", the "how", and the "solution".
  • Usage:
    • gct ai issue 456

Global Flags

• gct -v, gct --version
  • A global alternative to the gct version command.

FAQ

Frequently Asked Questions