CLI for AI-assisted Conventional Commits, issue/PR text, and Git Flow versioning on GitHub and Azure DevOps.
Requires Python 3.12, Git, and uv. Install GnuPG too if you need GPG signing.
Choose a directory outside your application repository. This example uses $HOME/projects. Replace YOUR_GIT_TOOLS_SOURCE_URL with the clone URL copied from this git-tools repository's Code button, not your application repository's URL:
mkdir -p "$HOME/projects"
cd "$HOME/projects"
git clone YOUR_GIT_TOOLS_SOURCE_URL git-tools
cd git-tools
./scripts/install.shAlready cloned the tool? Run ./scripts/install.sh from that checkout instead. Keep the checkout in place: the installation is editable. The URL above is the upstream tool source, not your application's repository.
Restart your shell, then check git-tools --version. If the command is not on PATH, run uv tool update-shell, restart, then run git-tools --install-completion. For dependency or package-metadata changes, rerun ./scripts/install.sh --reinstall from the tool checkout.
Use your own dedicated automation keys, not someone else's key ID or everyday personal private keys. Run the commands one at a time in a private local terminal. After listing keys, select your automation key and replace YOUR_GPG_KEY_ID with its long ID or full fingerprint. Replace the SSH filename with your own automation key's filename.
In your application repository → Settings → Secrets and variables → Actions → New repository secret, create the two secrets named beside these commands:
gpg --list-secret-keys --keyid-format=long
gpg --export-secret-key -a YOUR_GPG_KEY_ID # → BOT_GPG_SECRETKEY
cat "$HOME/.ssh/YOUR_AUTOMATION_SSH_KEY" # → BOT_SSH_SECRETKEY (not the .pub file)Paste each complete private-key block, including its BEGIN/END markers, into the corresponding secret. No export file is needed. Never paste the private output into chat, logs, or source files; terminal/clipboard history can retain it.
Already registered the matching public keys and write access? Keep that setup. Missing a key or public-key registration? The GitHub setup guide shows how to create only what you need. The supplied workflows have no GPG/SSH passphrase configured; protected keys need a secure workflow adaptation.
In Pipelines → your pipeline → Edit → Variables → New variable, name the variable BOT_GPG_SECRETKEY and enable Keep this value secret:
gpg --list-secret-keys --keyid-format=long
gpg --export-secret-key -a YOUR_GPG_KEY_ID # → BOT_GPG_SECRETKEY (secret pipeline variable)Paste the complete armored private-key block with its original line breaks. Azure's examples need no SSH secret or exported key file; the Build Service identity authenticates pushes. They have no GPG passphrase input. See Azure setup for creating a missing key, permissions, and updating older Secure File-based templates.
Use your own details: your name/email for local commits, your GitHub owner/repository or Azure organization/project/repository for the application remote, and your chosen automation name/email in CI. Keep the upstream git-tools source URL unchanged unless you intentionally use a fork.
Switch to the repository you want to work on, not the git-tools source checkout:
cd /path/to/your/application
git-tools --help
git-tools log # Print read-only history once; compares with develop.
git-tools settings # Optional: configure a provider for AI generation.
git-tools commit --no-commit --no-copy # Preview a message for changes you already staged.Direct git-tools commit creates a commit by default. git-tools pr generates text; it does not open a hosted PR. log, init, bump, and versioning CI need no LLM key.
git-tools log shows a colored terminal graph, ahead/behind counts against develop, and local/cached remote branch counts, then exits by default. Launch git-tools and select Log, or run git-tools log -i, to browse interactively. The browser separates View, History mode, and Base settings from Show more and Refresh actions; first-parent traversal is the default. Redirected output prints once as plain text, and NO_COLOR=1 disables colors. It never fetches or switches branches.
| What you need | GitHub | Azure DevOps |
|---|---|---|
| Keys, secrets, CI settings, and permissions | Setup · Branch rulesets | Setup |
| Returning-user command checklist | Quickstart | Quickstart |
| Complete release/hotfix process | Choose a guide | Choose a guide |
Each complete guide includes the key-copy commands and its flow policy. Fresh-project bootstrap is clearly marked: do not rerun it in an existing repository. git-tools init creates .cz.toml; it does not install workflows or configure hosting. Enable only one versioning adapter per application.
- CLI reference: commands, options, interactive operation, and side effects.
- Configuration: providers, credentials, models, and settings. Verify provider endpoints before supplying new keys or starting model discovery, and recheck after switching: discovery can use a newly entered key before setup is saved. Missing endpoints are rejected, but saved-profile reset limitations can reactivate an older configured URL. Read the current limitations before provider use.
- Versioning:
.cz.tomlis the version/tag authority; supported Python, Node, and Rust files sync on a best-effort basis. Review the current limitations before custom selectors or bump planning. - Publication and recovery: inspect failed publication rather than force-pushing or repeating bootstrap.
- Documentation index: all guides, including optional DVC.
See contributing, code layout, style conventions, and code of conduct. Licensed under MIT.