gitforge-cli 0.1.0

A practical Git workflow automation tool for branches, snapshots, releases, and repository hygiene.

GitForge

Practical Git workflow automation for branches, snapshots, releases, and repository hygiene.

---

GitForge is a terminal-first Git workflow assistant for developers who want repeatable branch naming, safer commits, fast repository health checks, release tags, changelogs, branch cleanup, and ref comparisons without memorizing a pile of shell snippets. It uses the real Git executable, prints clean Rich tables, and keeps every operation explicit so it fits normal local and CI workflows.

• Repository health checks - inspect branch, upstream, dirty state, remotes, conflicts, and local Git identity.
• Branch automation - turn ticket titles into consistent branch names and optionally switch to them.
• Snapshot commits - stage tracked or all files, commit with guardrails, and optionally push.
• Release tagging - create annotated semantic-version tags with dirty-tree protection.
• Changelog generation - group commit history into Markdown or JSON output.
• Cleanup and compare tools - remove merged branches safely and summarize ref differences.

Installation

pip install gitforge-cli

The installed console command is:

gitforge --help

Usage

Inspect a repository:

gitforge status --repo .
gitforge doctor --repo .

Create a workflow branch:

gitforge branch "Add OAuth callback validation" --ticket AUTH-42 --prefix feature

Commit a snapshot:

gitforge snapshot -m "Implement OAuth callback validation"

Generate a changelog:

gitforge changelog --since v0.1.0 --output CHANGELOG.md

Create a release tag:

gitforge release 1.2.0 --push

Commands

Command	Description	Example
gitforge status	Show branch, upstream, dirty state, remote, and last tag.	gitforge status --json
gitforge doctor	Check Git availability, repo state, identity, remote, upstream, and conflicts.	gitforge doctor
gitforge branch <title>	Create a normalized branch name from a ticket/title.	gitforge branch "Fix login" --ticket WEB-7
gitforge snapshot	Stage changes and commit with safety checks.	gitforge snapshot -m "Fix login"
gitforge sync	Fetch, pull with rebase or merge, and optionally push.	gitforge sync --autostash
gitforge release <version>	Create an annotated release tag.	gitforge release 1.0.0
gitforge changelog	Render commit history as grouped Markdown or JSON.	gitforge changelog --max-count 25
gitforge compare <base> [head]	Compare two refs by unique commits and changed files.	gitforge compare main HEAD
gitforge cleanup	List or delete merged local branches.	gitforge cleanup --apply
gitforge ignore	Append built-in .gitignore templates.	gitforge ignore python macos

Configuration

GitForge intentionally uses standard Git configuration instead of its own config file.

git config user.name "Your Name"
git config user.email "[e-mail]"
git remote add origin [e-mail]:you/project.git
git branch --set-upstream-to origin/main main

Most commands accept --repo so they can operate on another checkout without changing directories.

License

MIT License. See LICENSE.