Skip to content

Commit 50c240c

Browse files
jan-ferdinandorhun
jan-ferdinand
and
orhun
authored
feat(changelog): support parsing commits by footer (#569)
* feat: Enable footer-based commit parsing Enable defining parsers for a commit's footer, similar to the already- present commit parsers for a commit's message or body. For example: ```toml commit_parsers = [ { footer = "changelog: ignore", skip = true }, ] ``` Due to an inconsistency between the conventional commits specification and its reference parser, footers are currently interpreted as `key:value` instead of the (correct) `key: value`. See conventional-commits/parser#47 for details. As a future-proof workaround, you can use `key: ?value` in the regex. * chore: fix typo --------- Co-authored-by: Orhun Parmaksız <orhunparmaksiz@gmail.com>
1 parent dabe716 commit 50c240c

File tree

8 files changed

+137
-0
lines changed

8 files changed

+137
-0
lines changed

‎.github/fixtures/test-footer-filter/cliff.toml

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
[changelog]
2+
# changelog header
3+
header = """
4+
# Changelog\n
5+
All notable changes to this project will be documented in this file.\n
6+
"""
7+
# template for the changelog body
8+
# https://keats.github.io/tera/docs/#introduction
9+
body = """
10+
{% if version %}\
11+
## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
12+
{% else %}\
13+
## [unreleased]
14+
{% endif %}\
15+
{% for group, commits in commits | group_by(attribute="group") %}
16+
### {{ group | upper_first }}
17+
{% for commit in commits %}
18+
- {{ commit.message | upper_first }}\
19+
{% endfor %}
20+
{% endfor %}\n
21+
"""
22+
# template for the changelog footer
23+
footer = """
24+
<!-- generated by git-cliff -->
25+
"""
26+
# remove the leading and trailing whitespace from the templates
27+
trim = true
28+
29+
[git]
30+
# regex for parsing and grouping commits
31+
commit_parsers = [
32+
{ message = "^feat", group = "Features", default_scope = "app" },
33+
{ message = "^fix", group = "Bug Fixes", scope = "cli" },
34+
# Accept both separators, ": " and ":".
35+
# Conventional commits require the separator to be ": ", but the reference implementation of the
36+
# conventional commits parser currently does not adhere to the specification. See also:
37+
# https://github.com/conventional-commits/parser/issues/47
38+
{ footer = "^changelog: ?ignore", skip = true },
39+
]

‎.github/fixtures/test-footer-filter/commit.sh

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
#!/usr/bin/env bash
2+
set -e
3+
4+
GIT_COMMITTER_DATE="2022-04-06 00:00:00" git commit --allow-empty -m "Initial commit"
5+
GIT_COMMITTER_DATE="2022-04-06 00:10:00" git commit --allow-empty -m "feat: add feature 1"
6+
git tag v0.1.0
7+
GIT_COMMITTER_DATE="2022-04-06 01:00:00" git commit --allow-empty -m "refactor: change feature 1" -m "BREAKING CHANGE: feature 1 is now different"
8+
GIT_COMMITTER_DATE="2022-04-06 01:10:00" git commit --allow-empty -m "chore: upgrade dependencies" -m "changelog: ignore"
9+
git tag v0.2.0
10+
GIT_COMMITTER_DATE="2022-04-06 02:00:00" git commit --allow-empty -m "test: add tests" -m "footer: some more info"
11+
GIT_COMMITTER_DATE="2022-04-06 02:10:00" git commit --allow-empty -m "test: add more tests" -m "changelog: ignore"

‎.github/fixtures/test-footer-filter/expected.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
## [unreleased]
6+
7+
### Test
8+
9+
- Add tests
10+
11+
## [0.2.0] - 2022-04-06
12+
13+
### Refactor
14+
15+
- Change feature 1
16+
17+
## [0.1.0] - 2022-04-06
18+
19+
### Features
20+
21+
- Add feature 1
22+
23+
<!-- generated by git-cliff -->

‎git-cliff-core/src/changelog.rs

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -632,6 +632,7 @@ mod test {
632632
sha: Some(String::from("tea")),
633633
message: None,
634634
body: None,
635+
footer: None,
635636
group: Some(String::from("I love tea")),
636637
default_scope: None,
637638
scope: None,
@@ -643,6 +644,7 @@ mod test {
643644
sha: Some(String::from("coffee")),
644645
message: None,
645646
body: None,
647+
footer: None,
646648
group: None,
647649
default_scope: None,
648650
scope: None,
@@ -654,6 +656,7 @@ mod test {
654656
sha: Some(String::from("coffee2")),
655657
message: None,
656658
body: None,
659+
footer: None,
657660
group: None,
658661
default_scope: None,
659662
scope: None,
@@ -665,6 +668,7 @@ mod test {
665668
sha: None,
666669
message: Regex::new(r".*merge.*").ok(),
667670
body: None,
671+
footer: None,
668672
group: None,
669673
default_scope: None,
670674
scope: None,
@@ -676,6 +680,7 @@ mod test {
676680
sha: None,
677681
message: Regex::new("feat*").ok(),
678682
body: None,
683+
footer: None,
679684
group: Some(String::from("New features")),
680685
default_scope: Some(String::from("other")),
681686
scope: None,
@@ -687,6 +692,7 @@ mod test {
687692
sha: None,
688693
message: Regex::new("^fix*").ok(),
689694
body: None,
695+
footer: None,
690696
group: Some(String::from("Bug Fixes")),
691697
default_scope: None,
692698
scope: None,
@@ -698,6 +704,7 @@ mod test {
698704
sha: None,
699705
message: Regex::new("doc:").ok(),
700706
body: None,
707+
footer: None,
701708
group: Some(String::from("Documentation")),
702709
default_scope: None,
703710
scope: Some(String::from("documentation")),
@@ -709,6 +716,7 @@ mod test {
709716
sha: None,
710717
message: Regex::new("docs:").ok(),
711718
body: None,
719+
footer: None,
712720
group: Some(String::from("Documentation")),
713721
default_scope: None,
714722
scope: Some(String::from("documentation")),
@@ -720,17 +728,31 @@ mod test {
720728
sha: None,
721729
message: Regex::new(r"match\((.*)\):.*").ok(),
722730
body: None,
731+
footer: None,
723732
group: Some(String::from("Matched ($1)")),
724733
default_scope: None,
725734
scope: None,
726735
skip: None,
727736
field: None,
728737
pattern: None,
729738
},
739+
CommitParser {
740+
sha: None,
741+
message: None,
742+
body: None,
743+
footer: Regex::new("Footer:.*").ok(),
744+
group: Some(String::from("Footer")),
745+
default_scope: None,
746+
scope: Some(String::from("footer")),
747+
skip: None,
748+
field: None,
749+
pattern: None,
750+
},
730751
CommitParser {
731752
sha: None,
732753
message: Regex::new(".*").ok(),
733754
body: None,
755+
footer: None,
734756
group: Some(String::from("Other")),
735757
default_scope: Some(String::from("other")),
736758
scope: None,
@@ -832,6 +854,10 @@ mod test {
832854
String::from("coffee"),
833855
String::from("revert(app): skip this commit"),
834856
),
857+
Commit::new(
858+
String::from("footer"),
859+
String::from("misc: use footer\n\nFooter: footer text"),
860+
),
835861
],
836862
commit_id: Some(String::from("0bc123")),
837863
timestamp: 50000000,
@@ -957,6 +983,10 @@ mod test {
957983
- update docs
958984
- add some documentation
959985
986+
### Footer
987+
#### footer
988+
- use footer
989+
960990
### I love tea
961991
#### app
962992
- damn right
@@ -998,6 +1028,13 @@ mod test {
9981028
config.git.split_commits = Some(true);
9991029
config.git.filter_unconventional = Some(false);
10001030
config.git.protect_breaking_commits = Some(true);
1031+
1032+
if let Some(parsers) = config.git.commit_parsers.as_mut() {
1033+
for parser in parsers.iter_mut().filter(|p| p.footer.is_some()) {
1034+
parser.skip = Some(true)
1035+
}
1036+
}
1037+
10011038
releases[0].commits.push(Commit::new(
10021039
String::from("0bc123"),
10031040
String::from(
@@ -1164,6 +1201,10 @@ chore(deps): fix broken deps
11641201
- update docs
11651202
- add some documentation
11661203
1204+
### Footer
1205+
#### footer
1206+
- use footer
1207+
11671208
### I love tea
11681209
#### app
11691210
- damn right

‎git-cliff-core/src/commit.rs

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -277,6 +277,13 @@ impl Commit<'_> {
277277
if let Some(body_regex) = parser.body.as_ref() {
278278
regex_checks.push((body_regex, body.clone().unwrap_or_default()))
279279
}
280+
if let (Some(footer_regex), Some(footers)) = (
281+
parser.footer.as_ref(),
282+
self.conv.as_ref().map(|v| v.footers()),
283+
) {
284+
regex_checks
285+
.extend(footers.iter().map(|f| (footer_regex, f.to_string())));
286+
}
280287
if let (Some(field_name), Some(pattern_regex)) =
281288
(parser.field.as_ref(), parser.pattern.as_ref())
282289
{
@@ -483,6 +490,7 @@ mod test {
483490
sha: None,
484491
message: Regex::new("test*").ok(),
485492
body: None,
493+
footer: None,
486494
group: Some(String::from("test_group")),
487495
default_scope: Some(String::from("test_scope")),
488496
scope: None,
@@ -656,6 +664,7 @@ mod test {
656664
sha: None,
657665
message: None,
658666
body: None,
667+
footer: None,
659668
group: Some(String::from("Test group")),
660669
default_scope: None,
661670
scope: None,
@@ -684,6 +693,7 @@ mod test {
684693
)),
685694
message: None,
686695
body: None,
696+
footer: None,
687697
group: None,
688698
default_scope: None,
689699
scope: None,
@@ -703,6 +713,7 @@ mod test {
703713
)),
704714
message: None,
705715
body: None,
716+
footer: None,
706717
group: Some(String::from("Test group")),
707718
default_scope: None,
708719
scope: None,

‎git-cliff-core/src/config.rs

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -213,6 +213,9 @@ pub struct CommitParser {
213213
/// Regex for matching the commit body.
214214
#[serde(with = "serde_regex", default)]
215215
pub body: Option<Regex>,
216+
/// Regex for matching the commit footer.
217+
#[serde(with = "serde_regex", default)]
218+
pub footer: Option<Regex>,
216219
/// Group of the commit.
217220
pub group: Option<String>,
218221
/// Default scope of the commit.

‎git-cliff-core/tests/integration_test.rs

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,7 @@ fn generate_changelog() -> Result<()> {
5656
sha: Some(String::from("coffee")),
5757
message: None,
5858
body: None,
59+
footer: None,
5960
group: Some(String::from("I love coffee")),
6061
default_scope: None,
6162
scope: None,
@@ -67,6 +68,7 @@ fn generate_changelog() -> Result<()> {
6768
sha: None,
6869
message: Regex::new("^feat").ok(),
6970
body: None,
71+
footer: None,
7072
group: Some(String::from("shiny features")),
7173
default_scope: None,
7274
scope: None,
@@ -78,6 +80,7 @@ fn generate_changelog() -> Result<()> {
7880
sha: None,
7981
message: Regex::new("^fix").ok(),
8082
body: None,
83+
footer: None,
8184
group: Some(String::from("fix bugs")),
8285
default_scope: None,
8386
scope: None,
@@ -89,6 +92,7 @@ fn generate_changelog() -> Result<()> {
8992
sha: None,
9093
message: Regex::new("^test").ok(),
9194
body: None,
95+
footer: None,
9296
group: None,
9397
default_scope: None,
9498
scope: Some(String::from("tests")),
@@ -100,6 +104,7 @@ fn generate_changelog() -> Result<()> {
100104
sha: None,
101105
message: None,
102106
body: None,
107+
footer: None,
103108
group: Some(String::from("docs")),
104109
default_scope: None,
105110
scope: None,

‎website/docs/configuration/git.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -146,6 +146,10 @@ Examples:
146146
- Group the commit as "Features" if the commit message (description) starts with "feat".
147147
- `{ body = ".*security", group = "Security" }`
148148
- Group the commit as "Security" if the commit body contains "security".
149+
<!-- Conventional commits parser is out of sync with spec, parsing only separator ":", not ": "; see: -->
150+
<!-- https://github.com/conventional-commits/parser/issues/47 -->
151+
- `{ footer = "^changelog: ?ignore", skip = true }`
152+
- Skip processing the commit if the commit footer contains "changelog: ignore".
149153
- `{ message = '^fix\((.*)\)', group = 'Fix (${1})' }`
150154
- Use the matched scope value from the commit message in the group name.
151155
- `{ message = ".*deprecated", body = ".*deprecated", group = "Deprecation" }`

0 commit comments

Comments
 (0)