Writing Professional Git Commit Messages: A Developer’s Reference

As developers, we often underestimate the power of a well-written commit message. Professional, concise, and structured commit messages are not just a formality; they are an essential aspect of collaborative development, debugging, and maintaining codebases. This guide delves into writing professional Git commit messages in the format you prefer and offers a clear reference for experienced developers.

---

Why Commit Message Format Matters

1. Clarity: Clear commit messages make it easier to understand the purpose of a change.

2. Collaboration: Team members can quickly grasp the scope of changes.

3. History Tracking: Well-documented commits provide a reliable history for debugging or reviewing past decisions.

4. Automation: Some CI/CD pipelines and release tools depend on structured commit messages.

---

Preferred Git Commit Format

Your preferred format is structured as follows:

1. Commit Title (Summary)

• Structure: <type>: <summary>

• Details:

  • Starts with a type (e.g., feat, fix, refactor).

  • Followed by a colon and a brief summary (imperative tone).

  • Keep under 50 characters.

Example:

feat: Allow SVG file uploads in WordPress

2. Commit Body

• Structure: One or more points providing context and details.

• Details:

  • Each point starts with a verb in the past tense (e.g., “Added”, “Updated”).

  • Use bullet points for clarity.

  • Explain what the commit does, why it’s necessary, and how it was done.

  • Wrap lines at 72 characters for readability.

Example:

- Added a code snippet to enable SVG file uploads via the filter.
- Updated the snippet comment with details about functionality and security considerations.
- Ensured compatibility with WordPress coding standards.

3. Commit Footer (Optional)

• Purpose: Provide additional context, references, or next steps.

• Structure:

  • Prefixed with keywords like Note:, Closes #, or Refs #.

  • Includes relevant issue numbers, disclaimers, or reminders.

Example:

Note: Implementing security measures for handling SVG files is recommended to mitigate potential risks.

---

Step-by-Step Guide to Writing a Professional Commit

Step 1: Choose the Correct Commit Type

Commit types are the backbone of your message. Here are the most common types:

• feat: A new feature.

• fix: A bug fix.

• docs: Documentation updates.

• style: Code style changes (formatting, no logic changes).

• refactor: Refactoring code (neither fixes nor features).

• test: Adding or updating tests.

• chore: Maintenance or non-functional changes (e.g., updating dependencies).

Step 2: Craft a Clear Title

Keep your title concise and action-oriented. Use the imperative tone to describe what the commit does, not what you did.

Example:

fix: Correct login redirect for unauthenticated users

Step 3: Write a Detailed Body (If Necessary)

Use the body to:

1. Explain the rationale behind the change.

2. Describe what changed and why.

3. Outline any potential impacts or considerations.

Tips:

• Use bullet points.

• Wrap lines at 72 characters.

• Be precise without overloading with unnecessary details.

Example Body:

- Updated the redirect logic to point unauthenticated users to the login page.
- Removed deprecated methods causing redirection issues.
- Added tests to verify the new redirection logic.

Step 4: Add an Informative Footer (Optional)

Use the footer to:

1. Reference related issues (e.g., Closes #123).

2. Include additional recommendations or notes.

Example Footer:

Closes #456
Note: Ensure all login page assets are preloaded for better UX.

---

Example Commit in Full

Here’s how a professional Git commit message looks in your preferred format:

feat: Add support for SVG file uploads in WordPress

- Implemented a filter to enable SVG file uploads.
- Added comments to the snippet detailing functionality and security precautions.
- Ensured adherence to WordPress coding standards for compatibility.

Note: Use security measures to handle SVG uploads safely, mitigating potential risks.

---

Best Practices for Professional Commit Messages

1. Be Specific: Clearly explain the purpose and scope of your changes.

2. Focus on the ‘What’ and ‘Why’: Avoid describing ‘how’ in excessive detail unless it’s crucial.

3. Commit Small, Logical Changes: One purpose per commit keeps the history clean and easy to review.

4. Use Proper Grammar and Punctuation: Maintain a professional tone.

5. Follow Team Guidelines: If your team uses a specific convention (e.g., Conventional Commits), adhere to it.

---

💡 Pro Tip: Understanding Author Date vs. Committer Date and Committing on an Old Date

When writing professional commit messages, it's essential to understand how Git tracks dates and how you can manipulate them for accuracy or backdating purposes. Here’s everything you need to know:

---

🔹 Author Date vs. Committer Date

Author Date

• What it Represents:
  The date and time when the original work (code changes) was created or authored.

• Use Case:
  Shows when the content of the commit was initially written, regardless of when it was committed.

• Example:
  If you wrote the code on Jan 1st but committed it on Jan 5th, the author date reflects Jan 1st.

---

Committer Date

• What it Represents:
  The date and time when the commit was made in the repository.

• Use Case:
  Tracks when the commit was recorded or modified. For example, if the commit is rebased or cherry-picked, the committer date will update, while the author date remains unchanged.

---

🔧 How to Commit on an Old Date

If you need to backdate a commit, Git provides options to set both the author date and committer date. Here's how:

Option 1: Using --date Flag (Simple Method)

The --date flag sets the author date, but the committer date will remain the current time.

git commit -m "Your commit message" --date="YYYY-MM-DD HH:MM:SS"

Example:

git commit -m "Backdated commit" --date="2024-11-30 10:10:01"

---

Option 2: Setting Both Dates Explicitly

To backdate both the author date and committer date:

GIT_AUTHOR_DATE="YYYY-MM-DD HH:MM:SS" \
GIT_COMMITTER_DATE="YYYY-MM-DD HH:MM:SS" \
git commit -m "Your commit message"

Example:

GIT_AUTHOR_DATE="2024-01-01 12:00:00" \
GIT_COMMITTER_DATE="2024-01-05 15:00:00" \
git commit -m "Added feature X with backdated commit"

---

🔑 Key Differences

---

💡 Why Does This Matter?

1. Author Date:

   • Helps maintain the integrity of the original timeline of your work.

   • Ensures the right person gets credit for the changes.

2. Committer Date:

   • Tracks when and how a commit was added or modified in the repository.

   • Useful for debugging and tracking rebases, cherry-picks, or edits.

3. Backdating Commits:

   • Keep your commit history accurate by reflecting the actual time work was done.

   • Avoid confusion in collaborative projects by clearly setting the correct dates.

By mastering these concepts and techniques, you can create a clean, professional, and transparent commit history! 🚀

---

Conclusion

Professional Git commit messages are a hallmark of a disciplined and collaborative developer. By following this structured format, you ensure that your codebase remains understandable, maintainable, and ready for teamwork or audits. Stick to these principles, and your commit history will reflect the quality and professionalism of your work.