Convert Figma logo to code with AI

joelparkerhenderson logogit-commit-message

Git commit message: how to write a great git commit message and commit template for version control

1,178
120
1,178
0
View on GitHub

Top Related Projects

conventional-changelog's avatar

commitlint

16,617

📓 Lint commit messages

commitizen's avatar

cz-cli

16,701

The commitizen command line utility. #BlackLivesMatter

typicode's avatar

husky

32,324

Git hooks made easy 🐶 woof!

carloscuesta's avatar

gitmoji

15,606

An emoji guide for your commit messages. 😜

angular's avatar

angular

95,657

Deliver web apps with confidence 🚀

Quick Overview

The joelparkerhenderson/git-commit-message repository is a comprehensive guide for writing effective Git commit messages. It provides best practices, templates, and examples to help developers create clear, concise, and informative commit messages. The repository serves as a valuable resource for improving communication and collaboration in software development projects.

Pros

  • Offers detailed guidelines and best practices for writing commit messages
  • Includes various templates and examples for different types of commits
  • Provides explanations and rationales for each recommendation
  • Helps improve project documentation and team communication

Cons

  • May be overwhelming for beginners due to the extensive amount of information
  • Some recommendations might not align with specific team or project conventions
  • Lacks interactive elements or tools for practicing commit message writing
  • Could benefit from more frequent updates to reflect evolving industry practices

Getting Started

To start using the guidelines from this repository:

  1. Visit the repository at https://github.com/joelparkerhenderson/git-commit-message
  2. Read through the README.md file for an overview of commit message best practices
  3. Explore the various sections, such as "The Seven Rules of a Great Git Commit Message"
  4. Implement the suggested practices in your next Git commit

Example of a good commit message structure:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Remember to keep your commit messages concise, informative, and consistent with your team's conventions.

Competitor Comparisons

conventional-changelog logo

commitlint

16,617

📓 Lint commit messages

Pros of commitlint

  • Automated enforcement of commit message conventions
  • Integration with popular development tools and CI/CD pipelines
  • Active community and regular updates

Cons of commitlint

  • Steeper learning curve for new users
  • More complex setup and configuration
  • Stricter rules may limit flexibility in certain scenarios

Code Comparison

git-commit-message example:

<type>: <subject>

[optional body]

[optional footer(s)]

commitlint example:

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [2, 'always', ['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore']],
  },
};

git-commit-message provides a simple template for structuring commit messages, while commitlint offers a more robust, configurable approach to enforcing commit message conventions.

git-commit-message is a lightweight solution that focuses on educating developers about best practices for writing commit messages. It's easy to adopt and doesn't require any additional setup.

commitlint, on the other hand, is a more comprehensive tool that can be integrated into the development workflow to automatically check commit messages against predefined rules. It offers greater consistency across projects and teams but requires more initial setup and configuration.

Both approaches aim to improve the quality and consistency of commit messages, but they cater to different levels of complexity and team needs.

commitizen logo

cz-cli

16,701

The commitizen command line utility. #BlackLivesMatter

Pros of cz-cli

  • Interactive CLI tool that guides users through commit message creation
  • Customizable commit message format and prompts
  • Integrates with popular tools and can be used in CI/CD pipelines

Cons of cz-cli

  • Requires installation and configuration, which may be overkill for small projects
  • Learning curve for team members unfamiliar with the tool
  • May slow down the commit process for experienced developers

Code comparison

git-commit-message:

<type>: <subject>

[optional body]

[optional footer(s)]

cz-cli:

module.exports = {
  types: [
    { value: 'feat', name: 'feat:     A new feature' },
    { value: 'fix', name: 'fix:      A bug fix' },
    // ... more types
  ],
  // ... other configuration options
};

Summary

git-commit-message is a simple, lightweight guide for writing commit messages, while cz-cli is a more comprehensive tool that enforces a specific commit message format through an interactive CLI. git-commit-message is easier to adopt and doesn't require any setup, making it suitable for quick reference and small teams. cz-cli offers more structure and consistency but comes with a steeper learning curve and additional setup requirements. The choice between the two depends on the project's size, team preferences, and desired level of commit message standardization.

typicode logo

husky

32,324

Git hooks made easy 🐶 woof!

Pros of husky

  • Provides a more comprehensive Git hooks management solution
  • Offers easier integration with npm scripts and other tools
  • Supports multiple programming languages and environments

Cons of husky

  • Requires Node.js and npm to be installed
  • May introduce additional complexity for simpler projects
  • Can potentially slow down Git operations due to hook execution

Code comparison

git-commit-message:

# <type>: <subject>
# |<----  Using a Maximum Of 50 Characters  ---->|

# Explain why this change is being made
# |<----   Try To Limit Each Line to a Maximum Of 72 Characters   ---->|

husky:

{
  "husky": {
    "hooks": {
      "pre-commit": "npm test",
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }
  }
}

Summary

git-commit-message focuses on providing guidelines for writing effective commit messages, while husky offers a more comprehensive solution for managing Git hooks across various stages of the development process. git-commit-message is simpler and language-agnostic, whereas husky provides more flexibility and integration options but requires Node.js. The choice between the two depends on the project's complexity and specific requirements for Git workflow management.

carloscuesta logo

gitmoji

15,606

An emoji guide for your commit messages. 😜

Pros of gitmoji

  • Visual appeal: Uses emojis for quick, intuitive understanding of commit types
  • Standardized approach: Provides a consistent set of emojis for various commit purposes
  • Tooling support: Offers CLI and other tools for easy integration into workflows

Cons of gitmoji

  • Learning curve: Requires memorizing emoji meanings or referencing a guide
  • Limited expressiveness: May not cover all possible commit scenarios or nuances
  • Potential overuse: Can lead to cluttered commit messages if not used judiciously

Code comparison

gitmoji:

git commit -m ":bug: Fix memory leak in data processing module"

git-commit-message:

git commit -m "Fix: Resolve memory leak in data processing module

This commit addresses a critical memory leak issue in the data
processing module, improving overall system stability and performance."

The gitmoji approach uses a concise, emoji-based format, while git-commit-message encourages more detailed, text-based descriptions. The latter provides more context but requires more time to write and read.

Both repositories aim to improve commit message quality, but they take different approaches. gitmoji focuses on quick visual identification, while git-commit-message emphasizes comprehensive, structured text descriptions. The choice between them depends on team preferences, project requirements, and the desired balance between brevity and detail in commit messages.

angular logo

angular

95,657

Deliver web apps with confidence 🚀

Pros of Angular

  • Comprehensive framework for building web applications
  • Large community and ecosystem with extensive documentation
  • Provides a complete solution for front-end development

Cons of Angular

  • Steeper learning curve compared to simpler git commit message guidelines
  • More complex setup and configuration required
  • Overkill for projects primarily focused on git commit practices

Code Comparison

Angular (TypeScript):

@Component({
  selector: 'app-root',
  template: '<h1>{{title}}</h1>'
})
export class AppComponent {
  title = 'My Angular App';
}

git-commit-message (Markdown):

# Summarize changes in around 50 characters or less

# More detailed explanatory text, if necessary. Wrap it to about 72
# characters or so. In some contexts, the first line is treated as the
# subject of the commit and the rest of the text as the body.

Summary

Angular is a full-featured web application framework, while git-commit-message is a focused guide for writing effective git commit messages. Angular offers a complete solution for building complex web applications but requires more learning and setup. git-commit-message provides simple, straightforward guidelines for improving version control practices without additional overhead. Choose Angular for comprehensive web development projects, and git-commit-message for enhancing git workflow across various project types.

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Git commit message

To write a great git commit message, take a look at these guidelines and suggestions.

Contents:

Top priorities

For the best git commit messages:

  • Read these guidelines and suggestions, then discuss them with your teammates.

  • Emphasize clear communication, because commit messages help you and your teammates.

  • Use a git commit template, such as ours here.

Begin with a short summary line

Begin with a short summary line a.k.a. message subject:

  • Start with an imperative present active verb: Add, Drop, Fix, Refactor, Optimize, etc.

  • Use up to 50 characters; this is the git official preference.

  • Finish without a sentence-ending period.

Continue with a longer description

Continue with a longer description a.k.a. message body:

  • Add a blank line after the summary line, then write as much as you want.

  • Use up to 72 characters per line for typical text for word wrap.

  • Use as many characters as needed for atypical text, such as URLs, terminal output, formatted messages, etc.

  • Include any kind of notes, links, examples, etc. as you want.

Summary examples

Summary examples of good commit messages:

  • Add foo

  • Drop foo

  • Fix foo

  • Refactor foo

  • Optimize foo

Summary keywords

We recommend these summary keywords because they use imperative mood, present tense, active voice, and are verbs:

  • Add: Create a capability e.g. feature, test, dependency.

  • Drop: Delete a capability e.g. feature, test, dependency.

  • Fix: Fix an issue e.g. bug, typo, accident, misstatement.

  • Bump: Increase the version of something e.g. a dependency.

  • Make: Change the build process, or tools, or infrastructure.

  • Start: Begin doing something; e.g. enable a toggle, feature flag, etc.

  • Stop: End doing something; e.g. disable a toggle, feature flag, etc.

  • Optimize: A change that MUST be just about performance, e.g. speed up code.

  • Document: A change that MUST be only in the documentation, e.g. help files.

  • Refactor: A change that MUST be just a refactoring patch

  • Reformat: A change that MUST be just a formatting patch, e.g. change spaces.

  • Rearrange: A change that MUST be just an arranging patch, e.g. change layout.

  • Redraw: A change that MUST be just a drawing patch, e.g. change a graphic, image, icon, etc.

  • Reword: A change that MUST be just a wording patch, e.g. change a comment, label, doc, etc.

  • Revise: A change that MUST be just a revising patch e.g. a change, an alteration, a correction, etc.

  • Refit/Refresh/Renew/Reload: A change that MUST be just a patch e.g. update test data, API keys, etc.

Real-world examples

Real-world examples show how we use imperative mood, present tense, active voice, and verbs:

  • Add feature for a user to like a post

  • Drop feature for a user to like a post

  • Fix association between a user and a post

  • Bump dependency library to current version

  • Make build process use caches for speed

  • Start feature flag for a user to like a post

  • Stop feature flag for a user to like a post

  • Optimize search speed for a user to see posts

  • Document community guidelines for post content

  • Refactor user model to new language syntax

  • Reformat home page text to use more whitespace

  • Rearrange buttons so OK is on the lower right

  • Redraw diagram of how our web app works

  • Reword home page text to be more welcoming

  • Revise link to update it to the new URL

Use semantic versioning

We use semantic versioning for many of our projects:

  • Add, Start: Increment SemVer MINOR version when there is a new capability.

  • Drop, Stop: Increment SemVer MAJOR version when there is an incompatibility.

  • Fix, Bump, Make, Optimize, Document: Increment SemVer PATCH version.

  • Refactor, Reformat, Rearrange, Redraw, Reword: Increment SemVer PATCH version.

Specifics for right and wrong

Capitalize the summary.

  • Right: Add feature

  • Wrong: add feature

Finish the summary without a sentence-ending a period.

  • Right: Add feature

  • Wrong: Add feature.

If the summary ends with an non-sentence-ending period, use it.

  • Right: Add feature for U.S.A.

  • Wrong: Add feature for U.S.A

Use imperative mood: present tense, active voice, and lead verb.

  • Right: Add feature

  • Wrong: Adds feature (this is indicative mood, not imperative mood)

  • Wrong: Added feature (this is past tense, not present tense)

  • Wrong: Adding feature (this lead is a gerund, not a verb)

  • Wrong: Feature added (this is passive voice, not active voice)

Specifics for length

Keep the summary line within 50 characters.

  • The purpose is easy readability.

  • This is the git official convention.

  • This is the same convention as writing an email message.

Use a blank line after the summary line.

  • The purpose is making the commit message parseable by tools.

  • This is the git official convention.

  • This is the same convention as writing an email message.

Use up to 72 characters per line for typical text for word wrap.

  • The purpose is easy readability on typical terminals.

  • This is the git official convention.

  • This is the same convention as writing an email message.

Use as many characters as needed for atypical text, such as URLs, output, formatted messages, etc.

  • The purpose is preserving important formatting.

  • This is the git official convention.

  • This is the same convention as writing an email message.

Reasoning

We primarily care that our team communicates effectively with our shared understanding.

We secondarily like these verbs above because they're easy to read, easy to type, and clear in many cultures.

If you and your team prefer other words, that's fine too; use what works for you.

Reject these formats

We reject git commit message styles that put meta-information into the summary line.

Example:

  • [bug] ...

  • (release) ...

  • #12345 ...

  • docs: ...

  • JIRA-666 #time 1w 2d 4h 30m #comment Task completed ahead of schedule #resolve

We reject the git commit message style of projects such as Angular, Commitizen defaults, etc.

  • Because these use a leading tag that is sometimes a word, sometimes an abbreviation, sometimes a plural noun, etc.

  • Examples are using "feat" for feature, "docs" for document, "perf" for performance improvement, etc.

  • Instead we use "Add" for adding a feature, "Document" for documenting help, "Optimize" for performance improvement, etc.

  • Active verbs are easier to skim, and easier to use for people from other cultures who may be less-comfortable using English.

We reject using a ticket id number in the summary line.

  • Instead, we use fully-qualified URLs in the commit message body.

  • This is because many of our projects use multiple tracking systems, and multiple ways of launching a URL.

  • We want URL tracking to be easy to use by a wide range of systems, scripts, and teams.

We reject using a time tracking syntax in the summary line.

  • Instead, if you want time tracking, put the info in the commit message body.

  • This is because your personal time tracking is irrelevant to most other developers.

  • If you must use time tracking, we recommend the format of ISO 8601 and UTC, such as "YYYY-MM-DDTHH:MM:SSZ"

Optional: use contact email addresses

We sometimes have more than one person working on a commit. For example, we do do pair programming.

To keep track of this, we write a git commit message body that lists each person. We use the person's name and the email address. We use one person per line because this is easy to parse.

Co-authored-by: Alice Adams <alice@eaxmple.com>
Co-authored-by: Bob Brown <bob@example.com>
Co-authored-by: Carol Curtis <carol@example.com>

To make this easy, we use a git commit template.

Optional: use task tracking links

We sometimes connect a git commit to a task tracking system or web page that explains more. For example, we use GitHub, Trello, Jira, and many other bug tracking systems and project management software systems.

To keep track of these, we use a git commit message body that lists each URL, one per line, because this is easy to parse.

Example:

Add feature foo

See: https://github.com/user/repo/issues/789
See: https://jira.com/tasks/123
See: https://wikipedia.com/quicksort

If we want to provide link names, then we use Markdown links, such as:

See: [Request for help with sign in](https://github.com/user/repo/issues/789)
See: [Add feature foo](https://jira.com/tasks/123)
See: [Wikipedia Quicksort](https://wikipedia/quicksort)

To make this easy in practice, we use a git template that helps fill in this info.

Optional: use resource tracking metrics

We sometimes connect a git commit to a resource tracking system or metrics scripts. For example, we work on some projects where the project managers must keep track of work hours spent on a commit, or story point estimates per feature branch, or cost of hiring a developer to fix a bug.

To keep track of these, we use a git commit message body that lists each item, one per line, because this is easy to parse.

Example:

Add feature foo

Time: 7 staff hours
Cost: $700
Points: 7

Optional: use keywords, importance, references, etc.

We like to use commit message keywords to help us skim, search, and prioritize.

To keep track of these, we write a git commit message body that uses email header conventions.

Example:

Fix foo

Keywords: security, encryption, authentication
Importance: high
References: ...
Supersedes: ...
Obsoletes: ...
See-Also: ...

We use some of these to help our teams focus on the most important work.

  • When a commit message says "Importance: high" then it gets priority for code review and also for testing on the continuous integration server.

  • When a commit message says "Supersedes", "References", "Obsoletes", then we can easily look up the earlier commits or URLs.

Related links

Blog posts about how to write git commit messages:

Tools that help with git commit messages: