From 4e86fd9713feca634bbddd67197691d919f65423 Mon Sep 17 00:00:00 2001 From: Kasumi Null Date: Sun, 17 Aug 2025 11:07:18 +0800 Subject: [PATCH 1/6] ok --- git-commitai.1 | 36 ------------------------------------ 1 file changed, 36 deletions(-) diff --git a/git-commitai.1 b/git-commitai.1 index 87587d9..cf7483f 100644 --- a/git-commitai.1 +++ b/git-commitai.1 @@ -238,9 +238,6 @@ $ git commitai -m "Refactored auth system for JWT" # Auto-stage and commit tracked files $ git commitai -a - -# Preview without committing -$ git commitai --dry-run .fi .SS Advanced Usage @@ -270,39 +267,6 @@ $ git commitai --date "2 weeks ago" $ git commitai --author "Bot " --date "@1705329000" .fi -.SS Dry-Run Mode -.nf -# Preview what would be committed without actually committing -$ git commitai --dry-run - -# Combine dry-run with other options -$ git commitai --dry-run -a -m "Added new feature" -$ git commitai --dry-run --amend -$ git commitai --dry-run --allow-empty - -# Debug dry-run to see the full process -$ git commitai --dry-run --debug 2>&1 | tee preview.log - -# Example output: -# Dry run mode - no commit will be created -# -# On branch main -# Changes to be committed: -# M src/main.py -# A tests/test_main.py -# -# Generated commit message: -# -# Add unit tests for main module -# -# - Created comprehensive test suite -# - Added edge case handling -# - Improved code coverage to 95% -# -# (git hooks would be skipped) -# To actually commit these changes, run without --dry-run -.fi - .SS API Configuration .nf # Use a different model for this commit From aab04c2a256084d770d4aa33c17e339e148e389e Mon Sep 17 00:00:00 2001 From: Kasumi Null Date: Sun, 17 Aug 2025 11:20:58 +0800 Subject: [PATCH 2/6] Add version flag and improve debug logging - Introduce --version/-V flag to show version information - Add version display in debug mode startup message - Update help text and examples to include version flag - Early detection of version flag before argument parsing --- git_commitai.py | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/git_commitai.py b/git_commitai.py index b1cbf85..981a212 100755 --- a/git_commitai.py +++ b/git_commitai.py @@ -16,6 +16,9 @@ from typing import Dict, List, Optional, Tuple, Any, Union +# Version information +__version__ = "0.1.0" + # Global debug flag DEBUG: bool = False @@ -97,6 +100,12 @@ def debug_log(message: str) -> None: print(f"DEBUG: {safe_message}", file=sys.stderr) +def show_version() -> None: + """Show version information and exit.""" + print(f"git-commitai version {__version__}") + sys.exit(0) + + def show_man_page() -> bool: """Try to show the man page, fall back to help text if not available. @@ -1404,6 +1413,10 @@ def main() -> None: """Main entry point for git-commitai.""" global DEBUG + # Check for --version flag early + if "--version" in sys.argv or "-V" in sys.argv: + show_version() + # Check for --help flag early and show man page if available if "--help" in sys.argv or "-h" in sys.argv: if show_man_page(): @@ -1424,6 +1437,7 @@ def main() -> None: git-commitai --author "Name " # Override author git-commitai --date "2024-01-01T12:00:00" # Override date git-commitai --debug # Enable debug logging + git-commitai --version # Show version information Configuration: Create a .gitcommitai file in your repository root to customize the AI prompt. @@ -1515,6 +1529,12 @@ def main() -> None: action="store_true", help="Enable debug logging to stderr", ) + parser.add_argument( + "--version", + "-V", + action="store_true", + help="Show version information and exit", + ) # Debug section arguments debug_group = parser.add_argument_group('debug options', 'Override API configuration (requires --debug)') @@ -1524,11 +1544,15 @@ def main() -> None: args: argparse.Namespace = parser.parse_args() + # Handle version flag (though this should have been caught earlier) + if args.version: + show_version() + # Enable debug mode if flag is set if args.debug: DEBUG = True debug_log("=" * 60) - debug_log("Git Commit AI started with --debug flag") + debug_log(f"Git Commit AI v{__version__} started with --debug flag") debug_log(f"Python version: {sys.version}") debug_log(f"Arguments: {sys.argv[1:]}") if args.dry_run: From 5bce50fe4a054d83dcdcab8be8eaac2fe0fba7f9 Mon Sep 17 00:00:00 2001 From: Kasumi Null Date: Sun, 17 Aug 2025 11:22:40 +0800 Subject: [PATCH 3/6] Add documentation for dry-run mode and preview functionality - Document --dry-run flag usage with examples - Show how to combine dry-run with other options - Include sample output and debugging tips - Explain that hooks are skipped during dry-run --- git-commitai.1 | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/git-commitai.1 b/git-commitai.1 index cf7483f..87587d9 100644 --- a/git-commitai.1 +++ b/git-commitai.1 @@ -238,6 +238,9 @@ $ git commitai -m "Refactored auth system for JWT" # Auto-stage and commit tracked files $ git commitai -a + +# Preview without committing +$ git commitai --dry-run .fi .SS Advanced Usage @@ -267,6 +270,39 @@ $ git commitai --date "2 weeks ago" $ git commitai --author "Bot " --date "@1705329000" .fi +.SS Dry-Run Mode +.nf +# Preview what would be committed without actually committing +$ git commitai --dry-run + +# Combine dry-run with other options +$ git commitai --dry-run -a -m "Added new feature" +$ git commitai --dry-run --amend +$ git commitai --dry-run --allow-empty + +# Debug dry-run to see the full process +$ git commitai --dry-run --debug 2>&1 | tee preview.log + +# Example output: +# Dry run mode - no commit will be created +# +# On branch main +# Changes to be committed: +# M src/main.py +# A tests/test_main.py +# +# Generated commit message: +# +# Add unit tests for main module +# +# - Created comprehensive test suite +# - Added edge case handling +# - Improved code coverage to 95% +# +# (git hooks would be skipped) +# To actually commit these changes, run without --dry-run +.fi + .SS API Configuration .nf # Use a different model for this commit From a593c9bf7b9cf4c895e5385b4bba58897f1eb2f8 Mon Sep 17 00:00:00 2001 From: Kasumi Null Date: Sun, 17 Aug 2025 11:34:17 +0800 Subject: [PATCH 4/6] Refactor version handling to use argparse built-in version action - Removed custom show_version() function - Simplified --version flag processing by using argparse's native support - Eliminated redundant version check in main() since argparse now handles it This change reduces code duplication and leverages argparse's standard version functionality for better maintainability. --- git_commitai.py | 18 ++---------------- 1 file changed, 2 insertions(+), 16 deletions(-) diff --git a/git_commitai.py b/git_commitai.py index 981a212..2b8166d 100755 --- a/git_commitai.py +++ b/git_commitai.py @@ -100,12 +100,6 @@ def debug_log(message: str) -> None: print(f"DEBUG: {safe_message}", file=sys.stderr) -def show_version() -> None: - """Show version information and exit.""" - print(f"git-commitai version {__version__}") - sys.exit(0) - - def show_man_page() -> bool: """Try to show the man page, fall back to help text if not available. @@ -1413,10 +1407,6 @@ def main() -> None: """Main entry point for git-commitai.""" global DEBUG - # Check for --version flag early - if "--version" in sys.argv or "-V" in sys.argv: - show_version() - # Check for --help flag early and show man page if available if "--help" in sys.argv or "-h" in sys.argv: if show_man_page(): @@ -1531,8 +1521,8 @@ def main() -> None: ) parser.add_argument( "--version", - "-V", - action="store_true", + action="version", + version=f"%(prog)s {__version__}", help="Show version information and exit", ) @@ -1544,10 +1534,6 @@ def main() -> None: args: argparse.Namespace = parser.parse_args() - # Handle version flag (though this should have been caught earlier) - if args.version: - show_version() - # Enable debug mode if flag is set if args.debug: DEBUG = True From 6fd92c98ecae8a55aaaa64b800e2efb7295abd37 Mon Sep 17 00:00:00 2001 From: Kasumi Null Date: Sun, 17 Aug 2025 11:34:50 +0800 Subject: [PATCH 5/6] Refactor manpage structure and content - Reorganized sections for better flow and clarity - Removed redundant descriptions and simplified explanations - Consolidated configuration and template sections - Updated examples to focus on essential use cases - Streamlined option documentation while maintaining completeness --- git-commitai.1 | 310 +++++++++++-------------------------------------- 1 file changed, 65 insertions(+), 245 deletions(-) diff --git a/git-commitai.1 b/git-commitai.1 index 87587d9..3903dff 100644 --- a/git-commitai.1 +++ b/git-commitai.1 @@ -40,7 +40,6 @@ Unlike standard \fBgit commit\fR where this sets the entire message, in \fBgit-c .TP .BR \-\-debug Enable debug mode. Outputs detailed logging information to stderr for troubleshooting. -Shows git commands, API requests, and decision points. Redirect stderr to a file to capture debug output. .TP .BR \-\-api\-key " " \fIkey\fR @@ -50,7 +49,6 @@ Overrides the \fBGIT_COMMIT_AI_KEY\fR environment variable. .TP .BR \-\-api\-url " " \fIurl\fR Override the API endpoint URL for this commit. -Useful for testing different providers or local models. Overrides the \fBGIT_COMMIT_AI_URL\fR environment variable. .TP @@ -58,17 +56,15 @@ Overrides the \fBGIT_COMMIT_AI_URL\fR environment variable. Override the AI model name for this commit. Overrides the \fBGIT_COMMIT_AI_MODEL\fR environment variable. -.SS Standard Git Commit Options (Supported) +.SS Standard Git Commit Options .TP .BR \-a ", " \-\-all Automatically stage all tracked, modified files before committing. -Equivalent to running \fBgit add -u\fR before the commit. Cannot be used with \fB--amend\fR. .TP .BR \-\-amend Replace the tip of the current branch by creating a new commit with a new message. -The previous commit's changes are included. .TP .BR \-n ", " \-\-no\-verify @@ -77,12 +73,10 @@ Skip pre-commit and commit-msg hooks. .TP .BR \-v ", " \-\-verbose Show the diff of changes in the commit message editor. -The diff is displayed as comments after the commit message template. .TP .BR \-\-allow\-empty Allow creating a commit with no changes. -Useful for triggering CI/CD pipelines or creating marker commits. .TP .BR \-\-dry\-run @@ -92,32 +86,11 @@ Don't actually create a commit, just show what would be committed. .BR \-\-author " " \fIauthor\fR Override the commit author. Format: \fI"Name "\fR -The standard git formats are accepted, including: -.RS -.IP \(bu 2 -\fIName \fR - Full format -.IP \(bu 2 -\fI\fR - Email only (uses configured name) -.IP \(bu 2 -\fIName\fR - Name only (uses configured email) -.RE .TP .BR \-\-date " " \fIdate\fR Override the author date used in the commit. -Accepts various date formats: -.RS -.IP \(bu 2 -ISO 8601: \fI2024-01-15T14:30:00\fR -.IP \(bu 2 -RFC 2822: \fIMon, 15 Jan 2024 14:30:00 +0000\fR -.IP \(bu 2 -Unix timestamp: \fI@1705329000\fR -.IP \(bu 2 -Relative: \fI2 days ago\fR, \fIlast week\fR -.IP \(bu 2 -Simple: \fI2024-01-15 14:30:00\fR -.RE +Accepts various formats: ISO 8601, RFC 2822, Unix timestamp, relative dates. .TP .BR \-h ", " \-\-help @@ -133,99 +106,17 @@ Can be overridden with \fB--api-key\fR. .B GIT_COMMIT_AI_URL The API endpoint URL. Default: \fIhttps://openrouter.ai/api/v1/chat/completions\fR -Can be overridden with \fB--api-url\fR. .TP .B GIT_COMMIT_AI_MODEL The AI model to use for generation. Default: \fIqwen/qwen3-coder\fR -Can be overridden with \fB--model\fR. .TP .B GIT_EDITOR, EDITOR The editor to use for editing commit messages. Falls back to git's configured editor or \fBvi\fR. -.SH TEMPLATE FILES -Git Commit AI automatically detects and uses \fB.gitmessage\fR template files to understand your project's commit conventions. - -.SS Precedence Order -The tool looks for templates in this order (first found wins): - -.IP 1. 4 -\fBRepository template\fR: \fB.gitmessage\fR in your repository root -.IP 2. 4 -\fBGit config template\fR: Set via \fBgit config commit.template\fR -.IP 3. 4 -\fBGlobal template\fR: \fB~/.gitmessage\fR in your home directory - -.P -Repository-specific \fB.gitmessage\fR files take precedence over configured templates. -This ensures teams can enforce project-specific conventions by including a \fB.gitmessage\fR file in their repository, -regardless of individual developer configurations. - -When a template is found, it's used as additional context to help generate messages that follow your project's conventions. - -.SS Template Configuration Examples -.nf -# Create a repository-specific template -$ cat > .gitmessage << 'EOF' -# Format: (): -# Types: feat, fix, docs, style, refactor, test, chore -EOF - -# Configure a template via git config -$ git config --global commit.template ~/.my-template -$ git config commit.template .github/commit-template - -# Create a global fallback template -$ cp template.txt ~/.gitmessage -.fi - -.SH CONFIGURATION FILES -.SS .gitcommitai File -You can customize the AI prompt used for generating commit messages by creating a \fB.gitcommitai\fR file in your repository root. - -The file can optionally start with a model specification: -.nf -model: gpt-4 -.fi - -Then include your prompt template with placeholders: -.IP \(bu 2 -\fB{CONTEXT}\fR - User-provided context via -m flag -.IP \(bu 2 -\fB{DIFF}\fR - The git diff of changes -.IP \(bu 2 -\fB{FILES}\fR - The modified files with their content -.IP \(bu 2 -\fB{GITMESSAGE}\fR - Content from .gitmessage template if exists - -.SS Configuration Precedence -For the model setting, the precedence order is: -.IP 1. 4 -CLI flag (\fB--model\fR) -.IP 2. 4 -Environment variable (\fBGIT_COMMIT_AI_MODEL\fR) -.IP 3. 4 -\fB.gitcommitai\fR file model specification -.IP 4. 4 -Default (\fIqwen/qwen3-coder\fR) - -.SS Example .gitcommitai File -.nf -model: gpt-4 - -You are a commit message generator for our project. -Use conventional commits format. - -Context: {CONTEXT} -Changes: {DIFF} -Files: {FILES} - -Generate the commit message: -.fi - .SH EXAMPLES .SS Basic Usage .nf @@ -270,67 +161,14 @@ $ git commitai --date "2 weeks ago" $ git commitai --author "Bot " --date "@1705329000" .fi -.SS Dry-Run Mode -.nf -# Preview what would be committed without actually committing -$ git commitai --dry-run - -# Combine dry-run with other options -$ git commitai --dry-run -a -m "Added new feature" -$ git commitai --dry-run --amend -$ git commitai --dry-run --allow-empty - -# Debug dry-run to see the full process -$ git commitai --dry-run --debug 2>&1 | tee preview.log - -# Example output: -# Dry run mode - no commit will be created -# -# On branch main -# Changes to be committed: -# M src/main.py -# A tests/test_main.py -# -# Generated commit message: -# -# Add unit tests for main module -# -# - Created comprehensive test suite -# - Added edge case handling -# - Improved code coverage to 95% -# -# (git hooks would be skipped) -# To actually commit these changes, run without --dry-run -.fi - -.SS API Configuration +.SS Using Different Models .nf # Use a different model for this commit -$ git commitai --model "gpt-4o" --api-key "sk-..." +$ git commitai --model "gpt-4o" # Use a local LLM $ git commitai --api-url "http://localhost:11434/v1/chat/completions" \\ --model "codellama" - -# Test with Claude via Anthropic -$ git commitai --api-url "https://api.anthropic.com/v1/messages" \\ - --model "claude-3-opus" \\ - --api-key "sk-ant-..." -.fi - -.SS Debugging -.nf -# Enable debug mode (outputs to stderr) -$ git commitai --debug - -# Capture debug output to a file -$ git commitai --debug 2> debug.log - -# View debug output on screen and save to file -$ git commitai --debug 2>&1 | tee debug.log - -# Debug with other options -$ git commitai --debug -a -v --author "Test " 2> debug.log .fi .SS Using Templates @@ -345,64 +183,86 @@ EOF $ git add . $ git commitai # Generated message follows template format +.fi + +.SH CONFIGURATION FILES +.SS .gitcommitai File +You can customize the AI prompt used for generating commit messages by creating a \fB.gitcommitai\fR file in your repository root. -# Note: The repository .gitmessage overrides any configured -# templates or global ~/.gitmessage file +The file can optionally start with a model specification: +.nf +model: gpt-4 .fi -.SS Custom .gitcommitai Configuration +Then include your prompt template with placeholders: +.IP \(bu 2 +\fB{CONTEXT}\fR - User-provided context via -m flag +.IP \(bu 2 +\fB{DIFF}\fR - The git diff of changes +.IP \(bu 2 +\fB{FILES}\fR - The modified files with their content +.IP \(bu 2 +\fB{GITMESSAGE}\fR - Content from .gitmessage template if exists + +.SS Configuration Precedence +For the model setting, the precedence order is: +.IP 1. 4 +CLI flag (\fB--model\fR) +.IP 2. 4 +Environment variable (\fBGIT_COMMIT_AI_MODEL\fR) +.IP 3. 4 +\fB.gitcommitai\fR file model specification +.IP 4. 4 +Default (\fIqwen/qwen3-coder\fR) + +.SS Example .gitcommitai File .nf -# Create a .gitcommitai file with custom prompt -$ cat > .gitcommitai << 'EOF' model: gpt-4 You are a commit message generator for our project. Use conventional commits format. -{CONTEXT} +Context: {CONTEXT} +Changes: {DIFF} +Files: {FILES} -Changes: -{DIFF} +Generate the commit message: +.fi -Files: -{FILES} +.SH TEMPLATE FILES +Git Commit AI automatically detects and uses \fB.gitmessage\fR template files to understand your project's commit conventions. -Generate the commit message: -EOF +.SS Precedence Order +The tool looks for templates in this order (first found wins): -# Use with context -$ git commitai -m "Performance improvements" -# The AI will use your custom prompt template -.fi +.IP 1. 4 +\fBRepository template\fR: \fB.gitmessage\fR in your repository root +.IP 2. 4 +\fBGit config template\fR: Set via \fBgit config commit.template\fR +.IP 3. 4 +\fBGlobal template\fR: \fB~/.gitmessage\fR in your home directory -.SH DEBUGGING -When the \fB--debug\fR flag is enabled, detailed logging information is output to stderr. This includes: +.P +Repository-specific \fB.gitmessage\fR files take precedence over configured templates. +This ensures teams can enforce project-specific conventions by including a \fB.gitmessage\fR file in their repository. -.IP \(bu 2 -All git commands executed -.IP \(bu 2 -API request and response details -.IP \(bu 2 -File processing information -.IP \(bu 2 -Configuration and environment details -.IP \(bu 2 -Template file detection and loading (shows which template was chosen and why) -.IP \(bu 2 -Error messages and stack traces +When a template is found, it's used as additional context to help generate messages that follow your project's conventions. -To capture debug output, redirect stderr to a file: +.SS Template Configuration Examples .nf -$ git commitai --debug 2> debug.log -.fi +# Create a repository-specific template +$ cat > .gitmessage << 'EOF' +# Format: (): +# Types: feat, fix, docs, style, refactor, test, chore +EOF -Or view it on screen while saving to a file: -.nf -$ git commitai --debug 2>&1 | tee debug.log -.fi +# Configure a template via git config +$ git config --global commit.template ~/.my-template +$ git config commit.template .github/commit-template -The debug output for template detection will show the precedence order and which template was selected. -When reporting bugs, include relevant portions of the debug output. +# Create a global fallback template +$ cp template.txt ~/.gitmessage +.fi .SH FILES .TP @@ -415,10 +275,6 @@ Repository \fB.gitmessage\fR files take precedence over all other templates. Project-specific AI prompt configuration file. Can include custom prompt templates with placeholders for context, diff, and files. -.TP -.B .git/COMMIT_EDITMSG -Temporary file containing the commit message being edited. - .SH EXIT STATUS .TP .B 0 @@ -432,42 +288,6 @@ General error or commit aborted .B 128 Not in a git repository -.SH SUPPORTED PROVIDERS -Git Commit AI works with any OpenAI-compatible API endpoint: - -.IP \(bu 2 -\fBOpenRouter\fR (recommended) - Access to multiple models -.IP \(bu 2 -\fBLocal LLMs\fR - Ollama, LM Studio, etc. -.IP \(bu 2 -\fBOpenAI\fR - GPT-4, GPT-3.5 -.IP \(bu 2 -\fBAnthropic\fR - Claude models -.IP \(bu 2 -Any OpenAI-compatible API - -.SH LIMITATIONS -The following standard \fBgit commit\fR options are not yet supported: - -.IP \(bu 2 -\fB--interactive\fR, \fB--patch\fR - Interactive staging -.IP \(bu 2 -\fB-s\fR, \fB--signoff\fR - Signed-off-by trailer -.IP \(bu 2 -\fB-c\fR, \fB-C\fR - Reuse commit messages -.IP \(bu 2 -\fB--squash\fR, \fB--fixup\fR - Autosquash commits -.IP \(bu 2 -\fB-F\fR, \fB--file\fR - Read message from file -.IP \(bu 2 -\fB--reset-author\fR - Reset author information (use \fB--author\fR instead) -.IP \(bu 2 -\fB--cleanup\fR - Commit message cleanup mode -.IP \(bu 2 -\fB-S\fR, \fB--gpg-sign\fR - GPG signing -.IP \(bu 2 -Path specifications after \fB--\fR - .SH SEE ALSO .BR git (1), .BR git-commit (1) From 6777afa163891eecf30ea4b552d5924ec304c2b7 Mon Sep 17 00:00:00 2001 From: Kasumi Null Date: Sun, 17 Aug 2025 11:47:08 +0800 Subject: [PATCH 6/6] Update manpage for version 0.1.0 and add --version flag - Update copyright year to 2025 - Add --version flag documentation - Revise API key requirement wording - Update example model usage to openai/gpt-4o --- git-commitai.1 | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/git-commitai.1 b/git-commitai.1 index 3903dff..456c87d 100644 --- a/git-commitai.1 +++ b/git-commitai.1 @@ -1,6 +1,6 @@ .\" Manpage for git-commitai .\" Contact: https://github.com/semperai/git-commitai -.TH GIT-COMMITAI 1 "2024" "1.0.0" "Git Commit AI Manual" +.TH GIT-COMMITAI 1 "2025" "0.1.0" "Git Commit AI Manual" .SH NAME git-commitai \- Generate AI-powered git commit messages @@ -21,6 +21,7 @@ git-commitai \- Generate AI-powered git commit messages [\fB\-\-api\-url\fR \fIurl\fR] [\fB\-\-model\fR \fIname\fR] [\fB\-h\fR|\fB\-\-help\fR] +[\fB\-\-version\fR] .SH DESCRIPTION .B git-commitai @@ -56,6 +57,10 @@ Overrides the \fBGIT_COMMIT_AI_URL\fR environment variable. Override the AI model name for this commit. Overrides the \fBGIT_COMMIT_AI_MODEL\fR environment variable. +.TP +.BR \-\-version +Display version information and exit. + .SS Standard Git Commit Options .TP .BR \-a ", " \-\-all @@ -99,7 +104,7 @@ Display help information and exit. .SH ENVIRONMENT .TP .B GIT_COMMIT_AI_KEY -Your API key for the AI service (required). +Your API key for the AI service (if your provider requires one). Can be overridden with \fB--api-key\fR. .TP @@ -164,7 +169,7 @@ $ git commitai --author "Bot " --date "@1705329000" .SS Using Different Models .nf # Use a different model for this commit -$ git commitai --model "gpt-4o" +$ git commitai --model "openai/gpt-4o" # Use a local LLM $ git commitai --api-url "http://localhost:11434/v1/chat/completions" \\