git-commit-helper

This Python script simplifies Git workflows by enabling structured commit messages, automated version bumps during merges, and customizable options via a YAML configuration file.

Features

• Template-Based Commit Messages: Fully customizable commit message format via template
• Interactive Commit Workflow: Select commit type, scope, and description interactively
• Automatic Version Bump: Automatically increments version numbers during merges from develop to master
• YAML Configuration File: Customize options via a .gccfg/config.yml file
• Configuration Initialization: Easily generate a default .gccfg/config.yml file
• Repository Management: Fetch updates, pull changes, and push commits with simple commands
• Smart Action Suggestions: Automatically suggests pushing or pulling based on repository state
• Soft Reset: Reset local unpushed commits while preserving changes

Installation

1. Clone the Repository

Clone the repository to a directory of your choice, e.g., ~/scripts:

git clone https://codeberg.org/Tealk/git-commit-helper.git ~/scripts/git-commit-helper

2. Make the Python Script Executable

Ensure the script is executable:

chmod +x ~/scripts/git-commit-helper/app.py

3. Make the Script Globally Accessible

Add the script to your PATH by creating an alias in your shell configuration file (e.g., ~/.bashrc, ~/.zshrc, or ~/.bash_profile):

# Alias for the script
alias git-helper="python3 ~/scripts/git-commit-helper/app.py"

Reload your shell configuration:

source ~/.bashrc   # or ~/.zshrc, depending on your shell

Now you can run the script anywhere using the command git-helper.

Usage

Syntax

git-helper [OPTIONS]

Options

• --commit: Start the commit workflow (default if no option provided)
• --merge: Merge develop into master with an automatic version bump
• --fetch: Fetch updates from all remote repositories
• --pull: Pull changes from the current branch's remote
• --push: Push local commits to the remote repository
• --reset: Perform a soft reset on unpushed commits
• --init-config: Create or overwrite a .gccfg/config.yml configuration file with default values
• -h, --help: Display a help message with all available options

Examples

1. Create a commit:

git-helper --commit
# or simply
git-helper

2. Merge with version bump:

git-helper --merge

3. Initialize a configuration file:

git-helper --init-config

Smart Repository Management

When you run the script without changes to commit, it intelligently suggests actions:

• If you have unpushed commits, it offers to push them to the remote
• If your working directory is clean, it offers to update your repository by fetching and pulling changes

This helps ensure your repository stays in sync with remote changes without requiring manual commands.

Configuration File

The script uses a .gccfg/config.yml file located in the same directory as the script. The configuration is template-driven, meaning the commit message structure is defined by the template.

Example .gccfg/config.yml

# Commit message template
# Available placeholders: {type}, {scope}, {message}
commit_template: "{type}({scope}): {message}"

# Scopes for commit messages
scopes:
- name: API
  short: api
- name: Frontend
  short: front
- name: Backend
  short: back
- name: Documentation
  short: docs
- name: Testing
  short: test
- name: CI/CD
  short: ci
- name: Refactoring
  short: refactor
- name: Dependencies
  short: deps

# Commit types
commit_types:
- Added
- Changed
- Removed
- Fixed
- Deprecated
- Security

# Version bump types
version_changes:
- major
- minor
- patch

Template Customization

The commit message format is controlled by the commit_template setting. You can customize it using these placeholders:

• {type}: The type of commit (e.g., Added, Fixed)
• {scope}: The scope of changes (e.g., api, front)
• {message}: The commit description

Example templates:

commit_template: "{type}({scope}): {message}"  # Output: Added(api): new feature
commit_template: "{type}: {message}"           # Output: Added: new feature
commit_template: "[{type}] {scope}: {message}" # Output: [Added] api: new feature

The script will automatically handle missing placeholders and clean up any empty brackets or unnecessary spacing.

Prerequisites

• Git: Git must be installed and available in your PATH
• Python: The script requires Python 3.7 or higher
• PyYAML: The script uses the pyyaml Python module. Install it with:

pip install pyyaml

License

This project is licensed under the AGPL-3.0 License. See the LICENSE file for details.