Understanding and using conventional commits

Sara Verdi
Sara Verdi
Graphite software engineer


Note

This guide explains this concept in vanilla Git. For Graphite documentation, see our CLI docs.


Conventional commits offer a structured format for writing commit messages, making it easier to manage versioning and release notes automatically. This guide explores how to use conventional commits, including types, examples, and how to integrate them into your workflow using the Graphite CLI.

Conventional commits define a standard for adding human and machine-readable meaning to commit messages. This format specifies a fixed structure that includes types, scopes, and a description that describes the changes succinctly.

The primary conventional commit types include:

  • feat: Introduces a new feature.
  • fix: Patches a bug.
  • docs: Adds or updates documentation.
  • style: Improves structure/format of the code without changing code logic.
  • refactor: Modifies the code without adding new features or fixing bugs.
  • test: Adds or modifies tests.
  • chore: Updates build tasks, CI configurations, and other non-production code changes.

For a more information on commit messages, check out this page.

Here’s how to use conventional commits in your projects:

To start using conventional commits effectively, install the Graphite CLI, which enhances Git functionality with additional features for managing branches and commit stacks:

Terminal
brew install withgraphite/tap/graphite

When you make changes in your repository, use the Graphite CLI to commit these using the conventional commit format. For example:

Terminal
gt create -am "feat(login): add remember me checkbox"

This command creates a new branch and commits the changes with a message that follows the conventional commits format.

Use the gt log command to view the history of commits in a structured way. This helps in understanding the sequence and scope of changes:

Terminal
gt log

After making your commits, use gt submit to create pull requests for each commit in your stack, ensuring each change is reviewed separately but managed together:

Terminal
gt submit --stack

Here are some examples of how conventional commits can be structured:

  • Feature commit: feat(user-profile): add user bio section
  • Bug fix commit: fix(login): correct username validation error
  • Documentation commit: docs(readme): update installation instructions
  • Automated version control: Easily determine the type of version change (major, minor, patch) based on commit messages.
  • Improved log readability: Makes the commit history more accessible and understandable.
  • Simplifies release notes: Automatic generation of changelogs from commit messages.

Adopting conventional commits can streamline your development process, making it more efficient and manageable. Integrating tools like the Graphite CLI can further enhance this workflow, providing powerful commands that align with conventional commit standards while offering enhanced functionality for managing complex codebases.

Graphite
Git stacked on GitHub

Stacked pull requests are easier to read, easier to write, and easier to manage.
Teams that stack ship better software, faster.

Or install our CLI.
Product Screenshot 1
Product Screenshot 2