https://github.com/shubhexists/conventional_commits
A light-weight, conventional commit parser written in Rust
https://github.com/shubhexists/conventional_commits
commit-msg commitlint conventional-commits git
Last synced: 27 days ago
JSON representation
A light-weight, conventional commit parser written in Rust
- Host: GitHub
- URL: https://github.com/shubhexists/conventional_commits
- Owner: shubhexists
- Created: 2024-09-23T22:17:40.000Z (8 months ago)
- Default Branch: master
- Last Pushed: 2025-03-31T04:27:22.000Z (2 months ago)
- Last Synced: 2025-05-05T14:47:01.958Z (27 days ago)
- Topics: commit-msg, commitlint, conventional-commits, git
- Language: Rust
- Homepage:
- Size: 10.7 KB
- Stars: 6
- Watchers: 1
- Forks: 1
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Conventional Commits Parser
A robust Rust library for parsing [Conventional Commits](https://www.conventionalcommits.org/), adding human and machine-readable meaning to commit messages.
## Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Valid Commit Structure](#valid-commit-structure)
- [Invalid Commits](#invalid-commits)
- [API Reference](#api-reference)
- [Contributing](#contributing)
- [License](#license)
## Features
- Parse Conventional Commits into structured data
- Tokenize commit messages for detailed analysis
- Identify commit type, scope, description, body, and footer
- Detect breaking changes
- Robust error handling for invalid commits
## Installation
Add this to your `Cargo.toml`:
```toml
[dependencies]
conventional-commit = "0.1.0"
```
## Usage
Here's a quick example of how to use the Conventional Commits Parser:
```rust
use conventional_commit::{parse_commit, Lexer};
fn main() -> Result<(), String> {
let input = "feat(parser): add ability to parse conventional commits".to_string();
let mut lexer = Lexer::new(input);
let tokens = lexer.lex()?;
let commit = parse_commit(tokens)?;
println!("{:?}", commit);
Ok(())
}
```
## Valid Commit Structure
A valid Conventional Commit has the following structure:
```
[optional scope]:
[optional body]
[optional footer(s)]
```
### Components:
1. **Type**: Describes the kind of change (e.g., feat, fix, docs, style, refactor, test, chore).
- Must be lowercase.
- Examples: `feat`, `fix`, `docs`
2. **Scope** (optional): Describes what area of the project is changing.
- Enclosed in parentheses.
- Can use kebab-case, lowercase, or uppercase.
- Examples: `(parser)`, `(ui)`, `(docs)`
3. **Breaking Change Indicator** (optional): An exclamation mark (`!`) before the colon.
- Indicates a breaking change.
- Example: `feat!:` or `feat(scope)!:`
4. **Description**: A brief explanation of the change.
- Separated from the type (and scope) by a colon and space.
- Written in the imperative mood.
- Example: `add ability to parse conventional commits`
5. **Body** (optional): Provides additional contextual information about the change.
- Must be separated from the description by a blank line.
- Can be multiple paragraphs.
6. **Footer** (optional): Used for referencing issues, noting breaking changes, etc.
- Must start with a word token followed by `:` or `#`.
- Common footers: `BREAKING CHANGE:`, `Refs:`, `Reviewed-by:`
### Examples of Valid Commits:
```
feat(parser): add ability to parse conventional commits
This commit introduces a new parser for Conventional Commits.
The parser can identify commit types, scopes, and descriptions.
Refs: #123
```
```
fix!: correct critical bug in authentication flow
BREAKING CHANGE: This changes the API for user authentication.
Old auth tokens will no longer be valid.
```
```
docs: update README with new API examples
Updated the README to include examples of how to use
the new parsing functions introduced in v2.0.0.
```
## Invalid Commits
The following are examples of invalid commits and why they're incorrect:
1. Missing type:
```
add new feature
```
Error: Commit type is missing.
2. Unclosed scope:
```
feat(parser: add new parsing logic
```
Error: Scope is not properly closed with a parenthesis.
3. Missing description:
```
feat(ui):
```
Error: Description is missing.
## API Reference
For detailed API documentation, please refer to the rustdoc comments in the source code.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
This project is licensed under the MIT License - see the LICENSE file for details.