Professional Way to Write Commits on Git

Published Sept. 26, 2024, 3:39 p.m. by frank_casanova

Writing professional Git commit messages is crucial for maintaining a clean, understandable, and maintainable project history. Here’s how professionals typically write their commit messages, following best practices:

1. Use a Clear and Concise Message Structure

A good commit message typically consists of three parts: - Title: A short summary of the change (ideally within 50 characters). - Description (optional but recommended): A more detailed explanation of the change, wrapped at 72 characters per line. - Footer (optional): Can be used for referencing issues, tickets, or other metadata like "Fixes #123".

Example Structure:

<type>(<scope>): <subject>

<body> (optional)

<footer> (optional)

2. Follow Commit Message Conventions

A common convention is Conventional Commits. Here's how it works:

Type: Indicates the type of change (e.g., feat, fix, docs, chore, refactor, test, style).
Scope: The part of the project affected by the change (optional but useful for larger projects).
Subject: A short description of what the change is. Written in imperative mood (like a command), e.g., "Fix bug" instead of "Fixed bug."

Common Commit Types:

feat: A new feature
fix: A bug fix
docs: Changes to documentation
style: Code style changes (formatting, missing semicolons, etc.)
refactor: Code changes that neither fix a bug nor add a feature
test: Adding or modifying tests
chore: Non-functional updates (build process, tooling, etc.)

Example Commit Messages:

Example 1: Adding a new feature

feat(api): add endpoint for task retrieval

Added a new `/task/{task_id}` endpoint to fetch tasks by ID. This 
returns a 404 if the task is not found and validates the input.

Closes #42

Example 2: Fixing a bug

fix(search): handle case sensitivity in keyword search

The search endpoint failed to return results when the case didn't 
match. Now, the search is case-insensitive and converts both the 
keyword and task titles to lowercase for comparison.

Fixes #56

Example 3: Refactoring code

refactor(database): optimize CSV reading logic

Refactored the `get_task_by_id` function to improve performance by 
avoiding redundant file reads. This reduces the file I/O operations 
in the task fetching process.

3. Use the Imperative Mood in the Subject

The subject line should sound like a command: - Correct: "Add new search feature" - Incorrect: "Added new search feature"

This keeps the language consistent and is often a convention followed by tools like Git itself (git merge or git revert).

4. Keep the Subject Line Short and to the Point

The subject should be no longer than 50 characters.
Avoid ending the subject line with a period.

5. Include a Detailed Body (if needed)

If the change is complex, use the body to provide additional context, such as: - Why the change was made - How it was implemented - Any challenges or trade-offs

Wrap the body at 72 characters per line for readability.

6. Use a Footer for Metadata

If you're linking to an issue tracker or closing an issue, use the footer for that:

Fixes #123
Closes #42

7. Commit Small, Logical Changes

Each commit should represent one logical unit of work. This makes it easier to: - Track changes - Roll back commits if needed - Review changes in code reviews

Bad vs. Good Commit Examples:

Bad Commit:

fix stuff

Good Commit:

fix(api): handle null response from task endpoint

Ensure that the API returns a 404 when no task is found, instead of 
an empty response. Updated tests to check for this case.

Following these best practices will make your commit history clear, and helpful to both yourself and others working on the project.

0 comments

There are no comments yet.