Git Commit Messages

Introduction

Conventional Commits is a standard for structuring commit messages that provides clear rules for writing project change history. This standard facilitates automatic changelog generation, version determination (semantic versioning), and better understanding of project history.

Basic Structure

Each commit message should follow this format:

<type>(<optional scope>): <description>

[optional body]

[optional footer(s)]

Required Parts

• type - type of change (required)
• description - brief description of the change (required)

Optional Parts

• scope - area of the project affected by the change
• body - more detailed description of the change
• footer - metadata such as breaking changes or issue references

Change Types (types)

Scope - Automatic Derivation from Branch Name

Scope is an optional part of the commit message that specifies the project area. When using an AI assistant, the scope can be automatically derived from the Git branch name:

Rules for Automatic Scope

• If the branch is named with a number at the beginning (e.g., 123-add-feature):

  • The numeric value before the first dash is extracted
  • This value is used as the scope: feat(123): add feature
  • The number is then also used in the footer for a reference to the task manager

• If the branch is master or production:

  • The scope is omitted or contextual naming is used

• Scope must be a noun in parentheses

Example Integration with Freelo

When using branch 456-user-auth, the following is generated:

feat(456): add user authentication system

Implement JWT-based authentication with refresh tokens.
Add login and logout endpoints with proper session management.

Refs: https://app.freelo.io/task/456

Breaking Changes

Breaking changes (changes that break backward compatibility) are marked in two ways:

1. Exclamation Mark After Type/Scope

feat(api)!: change authentication mechanism

2. Footer with BREAKING CHANGE

feat!: redesign API response format

Change all API endpoints to return standardized response objects
with consistent error handling structure.

BREAKING CHANGE: all API responses now include data, error, and meta fields

Writing Rules

Type (REQUIRED)

• Must be one of the valid types
• For breaking changes, add ! after type/scope

Description (REQUIRED)

• Short, concise one-line summary
• Maximum 72 characters (ideally less)
• Imperative mood - "add feature" not "added feature"
• Lowercase at the beginning (English conventions)
• No period at the end
• Do NOT describe compiled files or build artifacts
• Focus on actual changes in the source code

Body (OPTIONAL but RECOMMENDED)

• Separated by one blank line from the description
• Multi-line descriptive text explaining the change
• Explain "what" and "why", not "how"
• Use imperative mood
• You can use multiple paragraphs separated by blank lines
• Do NOT describe compiled files or build artifacts

Footer (OPTIONAL)

• Separated by one blank line from the body
• Used for:
  • Breaking changes: BREAKING CHANGE: description
  • Issue references: Refs: https://app.freelo.io/task/123
  • Closing issues: Closes: #456
  • Metadata: Reviewed-by:, Signed-off-by:, etc.
• Tokens in footer use dashes instead of spaces

Examples of Correct Commit Messages

Simple Message

fix: resolve memory leak in data processing

Message with Scope from Branch

feat(456): add user authentication system

Implement JWT-based authentication with refresh tokens.
Add login and logout endpoints with proper session management.

Refs: https://app.freelo.io/task/456

Breaking Change

feat!: redesign API response format

Change all API endpoints to return standardized response objects
with consistent error handling structure.

BREAKING CHANGE: all API responses now include data, error, and meta fields

Complex Example

refactor(auth): simplify token validation logic

Remove redundant validation checks and consolidate
token verification into single method. This improves
code maintainability and reduces duplication.

The old approach had three separate validation methods
that could be simplified into one with better error handling.

Refs: https://app.freelo.io/task/789
Reviewed-by: Jan Novak

Automation in PHPStorm with AI

The AI assistant in PHPStorm can automatically generate commit messages according to the Conventional Commits standard. The AI analyzes code changes and suggests an appropriate message. Below you can find the current prompt for AI to generate commit messages.

What AI Automatically Recognizes

1. Type of change - based on the nature of changes (feat, fix, refactor, etc.)
2. Scope from branch - extracts the number from the branch name (e.g., 123-feature → scope 123)
3. Breaking changes - detects changes that break compatibility
4. Task references - automatically creates a link to the Freelo task manager

Rules for AI Generation

AI focuses only on:

• Changes in source code
• Meaningful modifications

AI ignores:

• Compiled files
• Build artifacts
• Automatically generated code

Output format:

• Plain text without formatting characters
• No markdown characters (*, `, #, _)
• Output must be readable as plain text
• Suitable for direct use as a commit message

Example Workflow

1. You create branch 456-add-login
2. You make changes in the code
3. AI analyzes the diff
4. AI generates:

feat(456): add user login functionality

Implement login form with email and password validation.
Add session management and remember me functionality.

Refs: https://app.freelo.io/task/456

Benefits of Conventional Commits

1. Automatic changelogs - can be generated from commit history
2. Semantic versioning - automatic version determination (major, minor, patch)
3. Better navigation in project history
4. Easier code review - immediately clear what the commit does
5. Automation - CI/CD tools can react to change types
6. Integration with task managers - automatic linking with Freelo, Jira, etc.
7. Team consistency - everyone writes messages in the same way

Common Mistakes

❌ Wrong

feat(456) Add new feature           // missing colon
Fix: bug in parser                  // capitalized type
added new login page                // past tense instead of imperative
feat: Add login.                    // period at the end of description
feat: update compiled files         // describing build artifacts

✅ Correct

feat(456): add new feature
fix: bug in parser
feat: add new login page
feat: add login
feat: implement user authentication

AI Prompt

Conventional Commit Message Generator Prompt

Generate a conventional commit message following the Conventional Commits 1.0.0 specification and Angular convention.

Structure

<type>(<scope>): <description>

<body>

<footer>

Rules

Type (REQUIRED)
Use one of the following types from Angular convention:
- feat: New feature
- fix: Bug fix
- docs: Documentation changes
- style: Code style changes (formatting, missing semicolons, etc.)
- refactor: Code refactoring without fixing bugs or adding features
- perf: Performance improvements
- test: Adding or updating tests
- build: Changes to build system or dependencies
- ci: Changes to CI configuration
- chore: Other changes that don't modify src or test files
- revert: Reverting a previous commit

For breaking changes, append ! after the type/scope (e.g., feat!: or feat(api)!:)

Scope (OPTIONAL)
- If $GIT_BRANCH_NAME is available and NOT "master" or "production":
  - Extract the numeric integer value from the start of the branch name (before the first dash)
  - Use this number as the scope (e.g., feat(123): for branch "123-add-feature")
  - Store this number for use in the footer reference
- If no numeric value exists or branch is master/production, scope may be omitted or use a contextual noun
- Scope must be a noun in parentheses

Description (REQUIRED)
- Short, striking one-line summary
- Immediately follows the colon and space after type/scope
- Use imperative mood (e.g., "add feature" not "added feature")
- Do NOT describe compiled files or build artifacts
- Keep it concise and meaningful

Body (OPTIONAL but RECOMMENDED)
- MUST be separated from description by ONE blank line
- Multi-line descriptive text explaining what happened in the commit
- Explain the "what" and "why", not the "how"
- Do NOT describe compiled files or build artifacts
- Can contain multiple paragraphs separated by blank lines
- Use imperative mood

Footer (OPTIONAL)
- MUST be separated from body by ONE blank line
- Use for:
  - Breaking changes: BREAKING CHANGE: description
  - Issue references: If numeric scope was extracted from $GIT_BRANCH_NAME, add: Refs: https://app.freelo.io/task/<number>
  - Other references: Closes: #456, etc.
  - Reviewed-by, Signed-off-by, etc.
- Each footer token must use - instead of spaces (e.g., Reviewed-by)

Examples

With scope from branch:
feat(456): add user authentication system

Implement JWT-based authentication with refresh tokens.
Add login and logout endpoints with proper session management.

Refs: https://app.freelo.io/task/456

With breaking change:
feat!: redesign API response format

Change all API endpoints to return standardized response objects
with consistent error handling structure.

BREAKING CHANGE: all API responses now include data, error, and meta fields

Simple fix without body:
fix: resolve memory leak in data processing

Important Notes
- Ignore any compiled files, build artifacts, or generated code in your description and body
- Focus on source code changes and meaningful updates
- Keep the description under 72 characters when possible
- Always use imperative mood ("add" not "added", "fix" not "fixed")
- CRITICAL: The generated commit message must be plain text only. Do not use any formatting characters such as: asterisks (*), backticks (`), hashtags (#), underscores (_), brackets for emphasis, or any other markdown/formatting syntax in the actual commit message output. The commit message should be readable as pure plain text.

Additional Resources

• Official specification: conventionalcommits.org
• Angular convention: Angular contributing guide
• Tools: semantic-release, commitlint, commitizen

Note: This standard is based on Angular commit guidelines and is widely supported by tools for automating versioning and changelog generation. Consistent use of Conventional Commits significantly improves project documentation quality and facilitates team collaboration.