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.
What are conventional commits?
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.
Types of conventional commits
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.
Using conventional commits
Here’s how to use conventional commits in your projects:
1. Install and configure your tools
To start using conventional commits effectively, install the Graphite CLI, which enhances Git functionality with additional features for managing branches and commit stacks:
brew install withgraphite/tap/graphite
2. Creating a commit
When you make changes in your repository, use the Graphite CLI to commit these using the conventional commit format. For example:
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.
3. Visualizing and navigating commits
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:
gt log
4. Submitting changes
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:
gt submit --stack
Conventional commits examples
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
Benefits of using conventional commits
- 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.
Conclusion
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.
