Usage Guide¶

Comprehensive guide to all Conventional Commits Generator commands and features.

Basic Command¶

Interactive Commit¶

The most common way to use CCG is the interactive mode:

ccg

This starts the interactive prompt that guides you through creating a conventional commit.

Command-Line Flags¶

CCG supports various flags to customize its behavior:

--commit: Generate Message Only¶

Generate a commit message without actually creating a commit:

ccg --commit

Use Cases:

• Preview commit message format
• Test your commit message before committing
• Generate messages for documentation or examples

--push: Push Without Committing¶

Push existing commits to remote without creating a new commit:

ccg --push

Use Cases:

• Push commits you've already created
• Retry a failed push
• Push to a new branch that doesn't exist remotely

Features:

• Automatically detects if branch exists on remote
• Offers to create remote branch with --set-upstream if needed
• Checks remote access before pushing

--edit: Edit Existing Commits¶

Edit commit messages of existing commits:

ccg --edit

Features:

• Select from recent commits or enter commit hash
• Validates new message against conventional commits format
• Uses git commit --amend for latest commit (fast)
• Uses git filter-branch for older commits (rewrites history)
• Offers force push for commits already on remote

Workflow:

1. Choose how many recent commits to display
2. Select commit by number or hash
3. View current commit details
4. Enter new commit message and body
5. Review changes
6. Confirm edit
7. Optionally push with force flag

--delete: Delete Existing Commits¶

Delete commits from history:

ccg --delete

Features:

• Interactive commit selection
• Shows full commit details before deletion
• Uses git reset --hard HEAD~1 for latest commit
• Uses interactive rebase for older commits
• Requires explicit confirmation
• Offers force push for commits already on remote

Workflow:

1. Choose how many recent commits to display
2. Select commit by number or hash
3. View commit details
4. Confirm deletion (with warnings)
5. Commit is permanently removed
6. Optionally force push

--tag: Create and Push Tags¶

Create semantic version tags:

ccg --tag

Features:

• Validates tag format (Semantic Versioning)
• Supports annotated tags with messages
• Checks remote access before pushing
• Pushes tag to remote automatically

Workflow:

1. Enter tag name (validated against SemVer)
2. Choose between annotated or lightweight tag
3. Enter tag message (for annotated tags)
4. Confirm push to remote

--reset: Discard Changes and Pull¶

Reset local changes and pull latest from remote:

ccg --reset

Features:

• Discards all uncommitted changes
• Removes untracked files
• Pulls latest from remote
• Requires explicit confirmation

Workflow:

1. Check for local changes
2. Show destructive warning
3. Require user confirmation
4. Discard changes with git reset HEAD, git checkout ., git clean -fd
5. Pull latest with git pull

--analyze: Analyze Commit Compliance¶

Analyze all commits in the repository to check Conventional Commits compliance:

ccg --analyze

Features:

• Analyzes all commits or recent N commits
• Validates each commit against Conventional Commits format
• Color-coded output (green ✓ for valid, red ✗ for invalid)
• Shows numbered list for easy identification
• Provides summary statistics (total, valid %, invalid %)
• Suggests using --edit to fix invalid commits

Workflow:

1. Choose how many commits to analyze (or all)
2. View analysis results with validation status
3. Review summary statistics
4. Use suggested commit numbers with --edit to fix issues

Example Output:

┌──────────────────────┐
│ Analyze Commits      │
└──────────────────────┘

How many commits to analyze? (Enter for all, or a number): 5

Analyzing last 5 commits...

┌──────────────────────┐
│ Analysis Results     │
└──────────────────────┘

1. ✓ [a3c6dbc] feat(ux): improvements in usability and responsiveness
2. ✓ [97c2e52] chore: removing unnecessary comments
3. ✗ [2812ed3] update bump version workflow
4. ✓ [fa6a6df] feat: adding improvements
5. ✓ [a5309a3] chore: add CODE_IMPROVEMENTS.md
┌──────────────────────┐
│ Summary              │
└──────────────────────┘

Total commits analyzed: 5
Valid commits: 4 (80%)
Invalid commits: 1 (20%)
How to fix invalid commits:
  • Use 'ccg --edit' to edit a specific commit message
  • You can select commits by number or hash prefix
  • Example: 'ccg --edit' then select the commit to fix
⚠ Tip: Run 'ccg --edit' now to fix invalid commits

Use Cases:

• Audit repository for Conventional Commits compliance
• Identify commits that need fixing before a release
• Validate commit history after team adoption of conventional commits
• Check compliance across all branches
• Find and fix non-compliant commits systematically

Combined with Other Flags:

# Analyze commits in different repository
ccg --path /path/to/repo --analyze

# Analyze with verbose logging
ccg --verbose --analyze
ccg -v --analyze

--path: Work with Specific Paths¶

Specify files, directories, or repository paths:

ccg --path <path1> [path2] [...]

Two Modes:

Mode 1: Change Working Directory¶

When providing a single directory, CCG changes to that directory and operates there:

ccg --path /path/to/another/repo

Mode 2: Stage Specific Files¶

When providing multiple paths or files, CCG stages only those paths:

ccg --path src/app.py tests/test_app.py
ccg --path src/ docs/

Combined with Other Flags:

# Edit commit in different repository
ccg --path /path/to/repo --edit

# Push from different repository
ccg --path /path/to/repo --push

# Create tag in specific repository
ccg --path /path/to/repo --tag

Validation:

• Paths must exist
• Paths must be within a git repository
• Invalid paths show helpful error messages

--verbose: Enable Debug Logging¶

Enable verbose logging for debugging and troubleshooting:

ccg --verbose
ccg -v

Features:

• Logs all operations to ~/.ccg/ccg.log (always enabled)
• Shows debug output in console when --verbose is used
• Logs include timestamps, module names, function names, and line numbers
• Rotating log files (10MB max, keeps 5 backups)

Use Cases:

• Debugging issues with git commands
• Troubleshooting authentication problems
• Understanding what CCG is doing behind the scenes
• Reporting bugs with detailed logs

Combined with Other Flags:

# Debug push issues
ccg --verbose --push

# Debug commit editing
ccg -v --edit

# Debug with specific paths
ccg --verbose --path /path/to/repo

Log Format:

2025-10-13 23:58:34 - ccg.cli - INFO - main:123 - CCG started (version 2.2.8)
2025-10-13 23:58:35 - ccg.git - DEBUG - run_git_command:145 - Executing git command: git status
2025-10-13 23:58:35 - ccg.git - INFO - git_commit:289 - Creating commit with message: feat: add...

Log Location:

• Linux/Mac: ~/.ccg/ccg.log
• Windows: %USERPROFILE%\.ccg\ccg.log

--version: Show Version¶

Display CCG version information:

ccg --version

--help: Show Help¶

Display usage information and available flags:

ccg --help

Error Handling¶

CCG provides clear error messages for common issues:

Not a Git Repository¶

✗ Not a git repository. Please initialize one with 'git init'.

Solution: Run git init or cd to a git repository.

No Remote Configured¶

✗ No remote repository configured

Solution: Add a remote: git remote add origin <url>

No Changes to Commit¶

✗ No changes to commit in the specified path(s). Make some changes before running the tool.

Solution: Make changes to files, then run CCG.

Access Denied¶

✗ ACCESS DENIED: You don't have permission to access this repository.
✗ Please check:
   You have push access to this repository
   The repository URL is correct
   You're logged in with the correct account

Solution: Check your git credentials and repository permissions.