Merge bd79b2230c into 9e152a2dc0

.github/fixtures/test-bump-unreleased-with-tag-message-arg/cliff.toml

@@ -0,0 +1,37 @@
+[changelog]
+# template for the changelog footer
+header = """
+# Changelog\n
+All notable changes to this project will be documented in this file.\n
+"""
+# template for the changelog body
+# https://keats.github.io/tera/docs/#introduction
+body = """
+{% if version %}\
+    ## [{{ version | trim_start_matches(pat="v") }}]
+    {% if message %}
+        {{ message }}
+    {% endif %}\
+{% else %}\
+    ## [unreleased]
+{% endif %}\
+{% for group, commits in commits | group_by(attribute="group") %}
+    ### {{ group | upper_first }}
+    {% for commit in commits %}
+        - {{ commit.message | upper_first }}\
+    {% endfor %}
+{% endfor %}\n
+"""
+# template for the changelog footer
+footer = """
+<!-- generated by git-cliff -->
+"""
+# remove the leading and trailing whitespace from the templates
+trim = true
+
+[git]
+# regex for parsing and grouping commits
+commit_parsers = [
+    { message = "^feat", group = "Features", default_scope = "app" },
+    { message = "^fix", group = "Bug Fixes", scope = "cli" },
+]

.github/fixtures/test-bump-unreleased-with-tag-message-arg/commit.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -e
+
+GIT_COMMITTER_DATE="2022-04-06 01:25:08" git commit --allow-empty -m "Initial commit"
+GIT_COMMITTER_DATE="2022-04-06 01:25:09" git commit --allow-empty -m "feat: add feature 1"
+GIT_COMMITTER_DATE="2022-04-06 01:25:10" git commit --allow-empty -m "fix: fix feature 1"
+git tag v0.1.0
+GIT_COMMITTER_DATE="2022-04-06 01:25:11" git commit --allow-empty -m "feat(gui): add feature 2"
+GIT_COMMITTER_DATE="2022-04-06 01:25:12" git commit --allow-empty -m "fix(gui): fix feature 2"
+git tag v0.2.0
+GIT_COMMITTER_DATE="2022-04-06 01:25:13" git commit --allow-empty -m "test: add tests"

.github/fixtures/test-bump-unreleased-with-tag-message-arg/expected.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.2.1]
+
+Some text
+
+### Test
+
+- Add tests
+
+<!-- generated by git-cliff -->

.github/fixtures/test-tag-message/cliff.toml

@@ -0,0 +1,37 @@
+[changelog]
+# template for the changelog footer
+header = """
+# Changelog\n
+All notable changes to this project will be documented in this file.\n
+"""
+# template for the changelog body
+# https://keats.github.io/tera/docs/#introduction
+body = """
+{% if version %}\
+    ## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
+    {% if message %}
+        {{ message }}\
+    {% endif %}\
+{% else %}\
+    ## [unreleased]
+{% endif %}\
+{% for group, commits in commits | group_by(attribute="group") %}
+    ### {{ group | upper_first }}
+    {% for commit in commits %}
+        - {{ commit.message | upper_first }}\
+    {% endfor %}
+{% endfor %}\n
+"""
+# template for the changelog footer
+footer = """
+<!-- generated by git-cliff -->
+"""
+# remove the leading and trailing whitespace from the templates
+trim = true
+
+[git]
+# regex for parsing and grouping commits
+commit_parsers = [
+    { message = "^feat", group = "Features", default_scope = "app" },
+    { message = "^fix", group = "Bug Fixes", scope = "cli" },
+]

.github/fixtures/test-tag-message/commit.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -e
+
+GIT_COMMITTER_DATE="2022-04-06 01:25:08" git commit --allow-empty -m "Initial commit"
+GIT_COMMITTER_DATE="2022-04-06 01:25:09" git commit --allow-empty -m "feat: add feature 1"
+GIT_COMMITTER_DATE="2022-04-06 01:25:10" git commit --allow-empty -m "fix: fix feature 1"
+git tag v0.1.0 -m "Some text"
+GIT_COMMITTER_DATE="2022-04-06 01:25:11" git commit --allow-empty -m "feat(gui): add feature 2"
+GIT_COMMITTER_DATE="2022-04-06 01:25:12" git commit --allow-empty -m "fix(gui): fix feature 2"
+git tag v0.2.0
+GIT_COMMITTER_DATE="2022-04-06 01:25:13" git commit --allow-empty -m "test: add tests"

.github/fixtures/test-tag-message/expected.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [unreleased]
+
+### Test
+
+- Add tests
+
+## [0.2.0] - 2022-04-06
+
+### Bug Fixes
+
+- Fix feature 2
+
+### Features
+
+- Add feature 2
+
+## [0.1.0] - 2022-04-06
+
+Some text
+
+### Bug Fixes
+
+- Fix feature 1
+
+### Features
+
+- Add feature 1
+
+<!-- generated by git-cliff -->

.github/workflows/test-fixtures.yml

@@ -79,6 +79,9 @@ jobs:
             command: --bump --tag=2.1.1
           - fixtures-name: test-cli-arg-ignore-tags
             command: --ignore-tags ".*beta"
+          - fixtures-name: test-tag-message
+          - fixtures-name: test-bump-unreleased-with-tag-message-arg
+            command: --bump --unreleased --with-tag-message "Some text"
 
     steps:
       - name: Checkout

config/cliff.toml

@@ -16,6 +16,9 @@ All notable changes to this project will be documented in this file.\n
 body = """
 {% if version %}\
     ## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
+    {% if message %}
+        {{ message }}
+    {% endif %}\
 {% else %}\
     ## [unreleased]
 {% endif %}\

git-cliff-core/src/changelog.rs

@@ -815,6 +815,7 @@ mod test {
 		};
 		let test_release = Release {
 			version: Some(String::from("v1.0.0")),
+			message: None,
 			commits: vec![
 				Commit::new(
 					String::from("coffee"),
@@ -909,6 +910,7 @@ mod test {
 			},
 			Release {
 				version: None,
+				message: None,
 				commits: vec![
 					Commit::new(
 						String::from("abc123"),

git-cliff-core/src/lib.rs

@@ -33,6 +33,8 @@ pub mod remote;
 /// Git repository.
 #[cfg(feature = "repo")]
 pub mod repo;
+/// Git tag.
+pub mod tag;
 /// Template engine.
 pub mod template;
 

git-cliff-core/src/release.rs

@@ -21,6 +21,8 @@ use serde::{
 pub struct Release<'a> {
 	/// Release version, git tag.
 	pub version:   Option<String>,
+	/// git tag's message.
+	pub message:   Option<String>,
 	/// Commits made for the release.
 	pub commits:   Vec<Commit<'a>>,
 	/// Commit ID of the tag.
@@ -159,6 +161,7 @@ mod test {
 		fn build_release<'a>(version: &str, commits: &'a [&str]) -> Release<'a> {
 			Release {
 				version: None,
+				message: None,
 				commits: commits
 					.iter()
 					.map(|v| Commit::from(v.to_string()))
@@ -340,6 +343,7 @@ mod test {
 
 		let mut release = Release {
 			version: None,
+			message: None,
 			commits: vec![
 				Commit::from(String::from(
 					"1d244937ee6ceb8e0314a4a201ba93a7a61f2071 add github \
@@ -625,6 +629,7 @@ mod test {
 
 		let mut release = Release {
 			version: None,
+			message: None,
 			commits: vec![
 				Commit::from(String::from(
 					"1d244937ee6ceb8e0314a4a201ba93a7a61f2071 add github \
@@ -968,6 +973,7 @@ mod test {
 
 		let mut release = Release {
 			version: None,
+			message: None,
 			commits: vec![
 				Commit::from(String::from(
 					"1d244937ee6ceb8e0314a4a201ba93a7a61f2071 add github \

git-cliff-core/src/repo.rs

@@ -3,6 +3,7 @@ use crate::error::{
 	Error,
 	Result,
 };
+use crate::tag::Tag;
 use git2::{
 	BranchType,
 	Commit,
@@ -95,11 +96,47 @@ impl Repository {
 	/// Returns the current tag.
 	///
 	/// It is the same as running `git describe --tags`
-	pub fn current_tag(&self) -> Option<String> {
+	pub fn current_tag(&self) -> Option<Tag> {
 		self.inner
 			.describe(DescribeOptions::new().describe_tags())
 			.ok()
-			.and_then(|describe| describe.format(None).ok())
+			.and_then(|describe| {
+				describe
+					.format(None)
+					.ok()
+					.map(|name| self.resolve_tag(&name))
+			})
+	}
+
+	/// Returns the tag object of the given name.
+	/// if given name don't exists, still returns Tag object with the given name
+	pub fn resolve_tag(&self, name: &str) -> Tag {
+		match self.inner.resolve_reference_from_short_name(name) {
+			Ok(reference) => match reference.peel_to_tag() {
+				Ok(tag) => Tag {
+					name:    tag.name().unwrap_or_default().to_owned(),
+					message: tag.message().map(Self::cleanup_message),
+				},
+				_ => Tag {
+					name:    name.to_owned(),
+					message: None,
+				},
+			},
+			_ => Tag {
+				name:    name.to_owned(),
+				message: None,
+			},
+		}
+	}
+
+	/// used to remove signature from signed tag message
+	fn cleanup_message(message: &str) -> String {
+		let re = Regex::new(
+			r"(?s)-----BEGIN PGP SIGNATURE-----(.*?)-----END PGP SIGNATURE-----",
+		)
+		.expect("invalid regex, wtf");
+
+		re.replace(message, "").trim().to_string()
 	}
 
 	/// Returns the commit object of the given ID.
@@ -119,8 +156,8 @@ impl Repository {
 		&self,
 		pattern: &Option<Regex>,
 		topo_order: bool,
-	) -> Result<IndexMap<String, String>> {
-		let mut tags: Vec<(Commit, String)> = Vec::new();
+	) -> Result<IndexMap<String, Tag>> {
+		let mut tags: Vec<(Commit, Tag)> = Vec::new();
 		let tag_names = self.inner.tag_names(None)?;
 		for name in tag_names
 			.iter()
@@ -132,14 +169,21 @@ impl Repository {
 		{
 			let obj = self.inner.revparse_single(&name)?;
 			if let Ok(commit) = obj.clone().into_commit() {
-				tags.push((commit, name));
+				// lightweight commit?
+				tags.push((commit, Tag {
+					name,
+					message: None,
+				}));
 			} else if let Some(tag) = obj.as_tag() {
 				if let Some(commit) = tag
 					.target()
 					.ok()
 					.and_then(|target| target.into_commit().ok())
 				{
-					tags.push((commit, name));
+					tags.push((commit, Tag {
+						name:    tag.name().expect("tag don't have name").to_owned(),
+						message: tag.message().map(|msg| msg.to_owned()),
+					}));
 				}
 			}
 		}
@@ -261,7 +305,7 @@ mod test {
 	fn get_latest_tag() -> Result<()> {
 		let repository = get_repository()?;
 		let tags = repository.tags(&None, false)?;
-		assert_eq!(&get_last_tag()?, tags.last().expect("no tags found").1);
+		assert_eq!(get_last_tag()?, tags.last().expect("no tags found").1.name);
 		Ok(())
 	}
 
@@ -270,16 +314,20 @@ mod test {
 		let repository = get_repository()?;
 		let tags = repository.tags(&None, true)?;
 		assert_eq!(
-			tags.get("2b8b4d3535f29231e05c3572e919634b9af907b6").expect(
-				"the commit hash does not exist in the repository (tag v0.1.0)"
-			),
+			tags.get("2b8b4d3535f29231e05c3572e919634b9af907b6")
+				.expect(
+					"the commit hash does not exist in the repository (tag v0.1.0)"
+				)
+				.name,
 			"v0.1.0"
 		);
 		assert_eq!(
-			tags.get("4ddef08debfff48117586296e49d5caa0800d1b5").expect(
-				"the commit hash does not exist in the repository (tag \
-				 v0.1.0-beta.4)"
-			),
+			tags.get("4ddef08debfff48117586296e49d5caa0800d1b5")
+				.expect(
+					"the commit hash does not exist in the repository (tag \
+					 v0.1.0-beta.4)"
+				)
+				.name,
 			"v0.1.0-beta.4"
 		);
 		let tags = repository.tags(
@@ -290,9 +338,11 @@ mod test {
 			true,
 		)?;
 		assert_eq!(
-			tags.get("2b8b4d3535f29231e05c3572e919634b9af907b6").expect(
-				"the commit hash does not exist in the repository (tag v0.1.0)"
-			),
+			tags.get("2b8b4d3535f29231e05c3572e919634b9af907b6")
+				.expect(
+					"the commit hash does not exist in the repository (tag v0.1.0)"
+				)
+				.name,
 			"v0.1.0"
 		);
 		assert!(!tags.contains_key("4ddef08debfff48117586296e49d5caa0800d1b5"));
@@ -313,4 +363,35 @@ mod test {
 		);
 		Ok(())
 	}
+
+	#[test]
+	fn resolves_existing_tag_with_name_and_message() -> Result<()> {
+		let repository = get_repository()?;
+
+		let tag = repository.resolve_tag("v0.2.3");
+
+		assert_eq!(tag.name, "v0.2.3");
+		assert_eq!(
+			tag.message,
+			Some(
+				"Release v0.2.3\n\nBug Fixes\n- Fetch the dependencies before \
+				 copying the file to embed (9e29c95)"
+					.to_string()
+			)
+		);
+
+		Ok(())
+	}
+
+	#[test]
+	fn resolves_tag_when_no_tags_exist() -> Result<()> {
+		let repository = get_repository()?;
+
+		let tag = repository.resolve_tag("nonexistent-tag");
+
+		assert_eq!(tag.name, "nonexistent-tag");
+		assert_eq!(tag.message, None);
+
+		Ok(())
+	}
 }

git-cliff-core/src/tag.rs

@@ -0,0 +1,46 @@
+/// Common tag object that is parsed from a repository.
+/// lightweight tag will have None at message.
+#[derive(Debug)]
+pub struct Tag {
+	/// The name of the tag
+	pub name:    String,
+	/// the message of the tag. only if it was annotated
+	pub message: Option<String>,
+}
+
+#[cfg(test)]
+mod test {
+	use super::*;
+
+	#[test]
+	fn create_tag_with_name_and_message() {
+		let tag = Tag {
+			name:    String::from("v1.0"),
+			message: Some(String::from("Initial release")),
+		};
+		assert_eq!(tag.name, "v1.0");
+		assert_eq!(tag.message, Some(String::from("Initial release")));
+	}
+
+	#[test]
+	fn create_tag_with_name_and_no_message() {
+		let tag = Tag {
+			name:    String::from("v1.0"),
+			message: None,
+		};
+		assert_eq!(tag.name, "v1.0");
+		assert_eq!(tag.message, None);
+	}
+
+	#[test]
+	fn debug_print_tag_with_message() {
+		let tag = Tag {
+			name:    String::from("v1.0"),
+			message: Some(String::from("Initial release")),
+		};
+		assert_eq!(
+			format!("{:?}", tag),
+			"Tag { name: \"v1.0\", message: Some(\"Initial release\") }"
+		);
+	}
+}

git-cliff-core/src/template.rs

@@ -189,6 +189,7 @@ mod test {
 	fn get_fake_release_data() -> Release<'static> {
 		Release {
 			version: Some(String::from("1.0")),
+			message: None,
 			commits: vec![
 				Commit::new(
 					String::from("123123"),

git-cliff-core/tests/integration_test.rs

@@ -149,6 +149,7 @@ fn generate_changelog() -> Result<()> {
 	let releases = vec![
 		Release {
 			version:   Some(String::from("v2.0.0")),
+			message: None,
 			commits:   vec![
 
 				Commit::new(
@@ -212,6 +213,7 @@ fn generate_changelog() -> Result<()> {
 		},
 		Release {
 			version:   Some(String::from("v1.0.0")),
+			message: None,
 			commits:   vec![
 				Commit::new(
 					String::from("0bc123"),

git-cliff/src/args.rs

@@ -64,7 +64,7 @@ pub struct Opt {
 		help = "Prints help information",
 		help_heading = "FLAGS"
 	)]
-	pub help:            Option<bool>,
+	pub help:             Option<bool>,
 	#[arg(
 		short = 'V',
 		long,
@@ -73,10 +73,10 @@ pub struct Opt {
 		help = "Prints version information",
 		help_heading = "FLAGS"
 	)]
-	pub version:         Option<bool>,
+	pub version:          Option<bool>,
 	/// Increases the logging verbosity.
 	#[arg(short, long, action = ArgAction::Count, alias = "debug", help_heading = Some("FLAGS"))]
-	pub verbose:         u8,
+	pub verbose:          u8,
 	/// Writes the default configuration file to cliff.toml
 	#[arg(
 	    short,
@@ -85,7 +85,7 @@ pub struct Opt {
 	    num_args = 0..=1,
 	    required = false
 	)]
-	pub init:            Option<Option<String>>,
+	pub init:             Option<Option<String>>,
 	/// Sets the configuration file.
 	#[arg(
 	    short,
@@ -95,7 +95,7 @@ pub struct Opt {
 	    default_value = DEFAULT_CONFIG,
 	    value_parser = Opt::parse_dir
 	)]
-	pub config:          PathBuf,
+	pub config:           PathBuf,
 	/// Sets the working directory.
 	#[arg(
 	    short,
@@ -104,7 +104,7 @@ pub struct Opt {
 	    value_name = "PATH",
 	    value_parser = Opt::parse_dir
 	)]
-	pub workdir:         Option<PathBuf>,
+	pub workdir:          Option<PathBuf>,
 	/// Sets the git repository.
 	#[arg(
 		short,
@@ -114,7 +114,7 @@ pub struct Opt {
 		num_args(1..),
 		value_parser = Opt::parse_dir
 	)]
-	pub repository:      Option<Vec<PathBuf>>,
+	pub repository:       Option<Vec<PathBuf>>,
 	/// Sets the path to include related commits.
 	#[arg(
 		long,
@@ -122,7 +122,7 @@ pub struct Opt {
 		value_name = "PATTERN",
 		num_args(1..)
 	)]
-	pub include_path:    Option<Vec<Pattern>>,
+	pub include_path:     Option<Vec<Pattern>>,
 	/// Sets the path to exclude related commits.
 	#[arg(
 		long,
@@ -130,10 +130,10 @@ pub struct Opt {
 		value_name = "PATTERN",
 		num_args(1..)
 	)]
-	pub exclude_path:    Option<Vec<Pattern>>,
+	pub exclude_path:     Option<Vec<Pattern>>,
 	/// Sets the regex for matching git tags.
 	#[arg(long, env = "GIT_CLIFF_TAG_PATTERN", value_name = "PATTERN")]
-	pub tag_pattern:     Option<Regex>,
+	pub tag_pattern:      Option<Regex>,
 	/// Sets custom commit messages to include in the changelog.
 	#[arg(
 		long,
@@ -141,10 +141,19 @@ pub struct Opt {
 		value_name = "MSG",
 		num_args(1..)
 	)]
-	pub with_commit:     Option<Vec<String>>,
+	pub with_commit:      Option<Vec<String>>,
+	/// Sets custom message to the latest release (will overwrite original tag's
+	/// message if exists).
+	#[arg(
+		long,
+		env = "GIT_CLIFF_WITH_TAG_MESSAGE",
+		value_name = "MSG",
+		num_args = 0..=1,
+	)]
+	pub with_tag_message: Option<String>,
 	/// Sets the tags to ignore in the changelog.
 	#[arg(long, env = "GIT_CLIFF_IGNORE_TAGS", value_name = "PATTERN")]
-	pub ignore_tags:     Option<Regex>,
+	pub ignore_tags:      Option<Regex>,
 	/// Sets commits that will be skipped in the changelog.
 	#[arg(
 		long,
@@ -152,7 +161,7 @@ pub struct Opt {
 		value_name = "SHA1",
 		num_args(1..)
 	)]
-	pub skip_commit:     Option<Vec<String>>,
+	pub skip_commit:      Option<Vec<String>>,
 	/// Prepends entries to the given changelog file.
 	#[arg(
 	    short,
@@ -161,7 +170,7 @@ pub struct Opt {
 	    value_name = "PATH",
 	    value_parser = Opt::parse_dir
 	)]
-	pub prepend:         Option<PathBuf>,
+	pub prepend:          Option<PathBuf>,
 	/// Writes output to the given file.
 	#[arg(
 	    short,
@@ -172,7 +181,7 @@ pub struct Opt {
 	    num_args = 0..=1,
 	    default_missing_value = DEFAULT_OUTPUT
 	)]
-	pub output:          Option<PathBuf>,
+	pub output:           Option<PathBuf>,
 	/// Sets the tag for the latest version.
 	#[arg(
 		short,
@@ -181,13 +190,13 @@ pub struct Opt {
 		value_name = "TAG",
 		allow_hyphen_values = true
 	)]
-	pub tag:             Option<String>,
+	pub tag:              Option<String>,
 	/// Bumps the version for unreleased changes.
 	#[arg(long, help_heading = Some("FLAGS"))]
-	pub bump:            bool,
+	pub bump:             bool,
 	/// Prints bumped version for unreleased changes.
 	#[arg(long, help_heading = Some("FLAGS"))]
-	pub bumped_version:  bool,
+	pub bumped_version:   bool,
 	/// Sets the template for the changelog body.
 	#[arg(
 		short,
@@ -196,38 +205,38 @@ pub struct Opt {
 		value_name = "TEMPLATE",
 		allow_hyphen_values = true
 	)]
-	pub body:            Option<String>,
+	pub body:             Option<String>,
 	/// Processes the commits starting from the latest tag.
 	#[arg(short, long, help_heading = Some("FLAGS"))]
-	pub latest:          bool,
+	pub latest:           bool,
 	/// Processes the commits that belong to the current tag.
 	#[arg(long, help_heading = Some("FLAGS"))]
-	pub current:         bool,
+	pub current:          bool,
 	/// Processes the commits that do not belong to a tag.
 	#[arg(short, long, help_heading = Some("FLAGS"))]
-	pub unreleased:      bool,
+	pub unreleased:       bool,
 	/// Sorts the tags topologically.
 	#[arg(long, help_heading = Some("FLAGS"))]
-	pub topo_order:      bool,
+	pub topo_order:       bool,
 	/// Disables the external command execution.
 	#[arg(long, help_heading = Some("FLAGS"))]
-	pub no_exec:         bool,
+	pub no_exec:          bool,
 	/// Prints changelog context as JSON.
 	#[arg(short = 'x', long, help_heading = Some("FLAGS"))]
-	pub context:         bool,
+	pub context:          bool,
 	/// Strips the given parts from the changelog.
 	#[arg(short, long, value_name = "PART", value_enum)]
-	pub strip:           Option<Strip>,
+	pub strip:            Option<Strip>,
 	/// Sets sorting of the commits inside sections.
 	#[arg(
 		long,
 		value_enum,
 		default_value_t = Sort::Oldest
 	)]
-	pub sort:            Sort,
+	pub sort:             Sort,
 	/// Sets the commit range to process.
 	#[arg(value_name = "RANGE", help_heading = Some("ARGS"))]
-	pub range:           Option<String>,
+	pub range:            Option<String>,
 	/// Sets the GitHub API token.
 	#[arg(
 		long,
@@ -236,7 +245,7 @@ pub struct Opt {
 		hide_env_values = true,
 		hide = !cfg!(feature = "github"),
 	)]
-	pub github_token:    Option<SecretString>,
+	pub github_token:     Option<SecretString>,
 	/// Sets the GitHub repository.
 	#[arg(
 		long,
@@ -245,7 +254,7 @@ pub struct Opt {
 		value_name = "OWNER/REPO",
 		hide = !cfg!(feature = "github"),
 	)]
-	pub github_repo:     Option<RemoteValue>,
+	pub github_repo:      Option<RemoteValue>,
 	/// Sets the GitLab API token.
 	#[arg(
 		long,
@@ -254,7 +263,7 @@ pub struct Opt {
 		hide_env_values = true,
 		hide = !cfg!(feature = "gitlab"),
 	)]
-	pub gitlab_token:    Option<SecretString>,
+	pub gitlab_token:     Option<SecretString>,
 	/// Sets the GitLab repository.
 	#[arg(
 		long,
@@ -263,7 +272,7 @@ pub struct Opt {
 		value_name = "OWNER/REPO",
 		hide = !cfg!(feature = "gitlab"),
 	)]
-	pub gitlab_repo:     Option<RemoteValue>,
+	pub gitlab_repo:      Option<RemoteValue>,
 	/// Sets the Gitea API token.
 	#[arg(
 		long,
@@ -272,7 +281,7 @@ pub struct Opt {
 		hide_env_values = true,
 		hide = !cfg!(feature = "gitea"),
 	)]
-	pub gitea_token:     Option<SecretString>,
+	pub gitea_token:      Option<SecretString>,
 	/// Sets the GitLab repository.
 	#[arg(
 		long,
@@ -281,7 +290,7 @@ pub struct Opt {
 		value_name = "OWNER/REPO",
 		hide = !cfg!(feature = "gitea"),
 	)]
-	pub gitea_repo:      Option<RemoteValue>,
+	pub gitea_repo:       Option<RemoteValue>,
 	/// Sets the Bitbucket API token.
 	#[arg(
 		long,
@@ -290,7 +299,7 @@ pub struct Opt {
 		hide_env_values = true,
 		hide = !cfg!(feature = "bitbucket"),
 	)]
-	pub bitbucket_token: Option<SecretString>,
+	pub bitbucket_token:  Option<SecretString>,
 	/// Sets the Bitbucket repository.
 	#[arg(
 		long,
@@ -299,7 +308,7 @@ pub struct Opt {
 		value_name = "OWNER/REPO",
 		hide = !cfg!(feature = "bitbucket"),
 	)]
-	pub bitbucket_repo:  Option<RemoteValue>,
+	pub bitbucket_repo:   Option<RemoteValue>,
 }
 
 /// Custom type for the remote value.

git-cliff/src/lib.rs

@@ -90,7 +90,9 @@ fn process_repository<'a>(
 	let ignore_regex = config.git.ignore_tags.as_ref();
 	tags = tags
 		.into_iter()
-		.filter(|(_, name)| {
+		.filter(|(_, tag)| {
+			let name = &tag.name;
+
 			// Keep skip tags to drop commits in the later stage.
 			let skip = skip_regex.map(|r| r.is_match(name)).unwrap_or_default();
 
@@ -184,7 +186,7 @@ fn process_repository<'a>(
 					repository.current_tag().as_ref().and_then(|tag| {
 						tags.iter()
 							.enumerate()
-							.find(|(_, (_, v))| v == &tag)
+							.find(|(_, (_, v))| v.name == tag.name)
 							.map(|(i, _)| i)
 					}) {
 					match current_tag_index.checked_sub(1) {
@@ -226,10 +228,10 @@ fn process_repository<'a>(
 		if let Some(commit_id) = commits.first().map(|c| c.id().to_string()) {
 			match tags.get(&commit_id) {
 				Some(tag) => {
-					warn!("There is already a tag ({}) for {}", tag, commit_id)
+					warn!("There is already a tag ({:?}) for {}", tag, commit_id)
 				}
 				None => {
-					tags.insert(commit_id, tag.to_string());
+					tags.insert(commit_id, repository.resolve_tag(tag));
 				}
 			}
 		}
@@ -249,9 +251,13 @@ fn process_repository<'a>(
 			releases[release_index].commits.push(commit);
 		}
 		if let Some(tag) = tags.get(&commit_id) {
-			releases[release_index].version = Some(tag.to_string());
+			let tag_name = &tag.name;
+
+			releases[release_index].version = Some(tag_name.clone());
+			releases[release_index].message = tag.message.clone();
 			releases[release_index].commit_id = Some(commit_id);
-			releases[release_index].timestamp = if args.tag.as_deref() == Some(tag) {
+			releases[release_index].timestamp = if args.tag == Some(tag_name.clone())
+			{
 				SystemTime::now()
 					.duration_since(UNIX_EPOCH)?
 					.as_secs()
@@ -286,6 +292,13 @@ fn process_repository<'a>(
 		}
 	}
 
+	// Set custom message to the latest release.
+	if let Some(message) = &args.with_tag_message {
+		if let Some(latest_release) = releases.iter_mut().last() {
+			latest_release.message = Some(message.to_owned());
+		}
+	}
+
 	// Set the previous release if the first release does not have one set.
 	if !releases.is_empty() &&
 		releases
@@ -299,7 +312,7 @@ fn process_repository<'a>(
 			.map(|tag| {
 				tags.iter()
 					.enumerate()
-					.find(|(_, (_, v))| v == &tag)
+					.find(|(_, (_, v))| v.name == tag.name)
 					.and_then(|(i, _)| i.checked_sub(1))
 					.and_then(|i| tags.get_index(i))
 			})
@@ -307,10 +320,10 @@ fn process_repository<'a>(
 			.flatten();
 
 		// Set the previous release if the first tag is found.
-		if let Some((commit_id, version)) = first_tag {
+		if let Some((commit_id, tag)) = first_tag {
 			let previous_release = Release {
 				commit_id: Some(commit_id.to_string()),
-				version: Some(version.to_string()),
+				version: Some(tag.name.clone()),
 				timestamp: repository
 					.find_commit(commit_id.to_string())
 					.map(|v| v.time().seconds())

website/docs/usage/args.md

@@ -20,33 +20,38 @@ git-cliff [FLAGS] [OPTIONS] [--] [RANGE]
     --current         Processes the commits that belong to the current tag
 -u, --unreleased      Processes the commits that do not belong to a tag
     --topo-order      Sorts the tags topologically
--x, --context         Prints changelog context as JSON
     --no-exec         Disables the external command execution
+-x, --context         Prints changelog context as JSON
 ```
 
 ## Options
 
 ```
--i, --init [<CONFIG>]            Writes the default configuration file to cliff.toml
--c, --config <PATH>              Sets the configuration file [env: GIT_CLIFF_CONFIG=] [default: cliff.toml]
--w, --workdir <PATH>             Sets the working directory [env: GIT_CLIFF_WORKDIR=]
--r, --repository <PATH>...       Sets the git repository [env: GIT_CLIFF_REPOSITORY=]
-    --include-path <PATTERN>...  Sets the path to include related commits [env: GIT_CLIFF_INCLUDE_PATH=]
-    --exclude-path <PATTERN>...  Sets the path to exclude related commits [env: GIT_CLIFF_EXCLUDE_PATH=]
-    --tag-pattern <PATTERN>      Sets the regex for matching git tags [env: GIT_CLIFF_TAG_PATTERN=]
-    --with-commit <MSG>...       Sets custom commit messages to include in the changelog [env: GIT_CLIFF_WITH_COMMIT=]
-    --ignore-tags <PATTERN>      Sets the tags to ignore in the changelog [env: GIT_CLIFF_IGNORE_TAGS=]
-    --skip-commit <SHA1>...      Sets commits that will be skipped in the changelog [env: GIT_CLIFF_SKIP_COMMIT=]
--p, --prepend <PATH>             Prepends entries to the given changelog file [env: GIT_CLIFF_PREPEND=]
--o, --output [<PATH>]            Writes output to the given file [env: GIT_CLIFF_OUTPUT=]
--t, --tag <TAG>                  Sets the tag for the latest version [env: GIT_CLIFF_TAG=]
--b, --body <TEMPLATE>            Sets the template for the changelog body [env: GIT_CLIFF_TEMPLATE=]
--s, --strip <PART>               Strips the given parts from the changelog [possible values: header, footer, all]
-    --sort <SORT>                Sets sorting of the commits inside sections [default: oldest] [possible values: oldest, newest]
-    --github-token <TOKEN>       Sets the GitHub API token [env: GITHUB_TOKEN]
-    --github-repo <OWNER/REPO>   Sets the GitHub repository [env: GITHUB_REPO=]
-    --gitlab-token <TOKEN>       Sets the GitLab API token [env: GITLAB_TOKEN]
-    --gitlab-repo <OWNER/REPO>   Sets the GitLab repository [env: GITLAB_REPO=]
+-i, --init [<CONFIG>]              Writes the default configuration file to cliff.toml
+-c, --config <PATH>                Sets the configuration file [env: GIT_CLIFF_CONFIG=] [default: cliff.toml]
+-w, --workdir <PATH>               Sets the working directory [env: GIT_CLIFF_WORKDIR=]
+-r, --repository <PATH>...         Sets the git repository [env: GIT_CLIFF_REPOSITORY=]
+    --include-path <PATTERN>...    Sets the path to include related commits [env: GIT_CLIFF_INCLUDE_PATH=]
+    --exclude-path <PATTERN>...    Sets the path to exclude related commits [env: GIT_CLIFF_EXCLUDE_PATH=]
+    --tag-pattern <PATTERN>        Sets the regex for matching git tags [env: GIT_CLIFF_TAG_PATTERN=]
+    --with-commit <MSG>...         Sets custom commit messages to include in the changelog [env: GIT_CLIFF_WITH_COMMIT=]
+    --with-tag-message [<MSG>]     Sets custom message to the latest release (will overwrite original tag's message if exists) [env: GIT_CLIFF_WITH_TAG_MESSAGE=]
+    --ignore-tags <PATTERN>        Sets the tags to ignore in the changelog [env: GIT_CLIFF_IGNORE_TAGS=]
+    --skip-commit <SHA1>...        Sets commits that will be skipped in the changelog [env: GIT_CLIFF_SKIP_COMMIT=]
+-p, --prepend <PATH>               Prepends entries to the given changelog file [env: GIT_CLIFF_PREPEND=]
+-o, --output [<PATH>]              Writes output to the given file [env: GIT_CLIFF_OUTPUT=]
+-t, --tag <TAG>                    Sets the tag for the latest version [env: GIT_CLIFF_TAG=]
+-b, --body <TEMPLATE>              Sets the template for the changelog body [env: GIT_CLIFF_TEMPLATE=]
+-s, --strip <PART>                 Strips the given parts from the changelog [possible values: header, footer, all]
+    --sort <SORT>                  Sets sorting of the commits inside sections [default: oldest] [possible values: oldest, newest]
+    --github-token <TOKEN>         Sets the GitHub API token [env: GITHUB_TOKEN]
+    --github-repo <OWNER/REPO>     Sets the GitHub repository [env: GITHUB_REPO=]
+    --gitlab-token <TOKEN>         Sets the GitLab API token [env: GITLAB_TOKEN]
+    --gitlab-repo <OWNER/REPO>     Sets the GitLab repository [env: GITLAB_REPO=]
+    --gitea-token <TOKEN>          Sets the Gitea API token [env: GITEA_TOKEN]
+    --gitea-repo <OWNER/REPO>      Sets the GitLab repository [env: GITEA_REPO=]
+    --bitbucket-token <TOKEN>      Sets the Bitbucket API token [env: BITBUCKET_TOKEN]
+    --bitbucket-repo <OWNER/REPO>  Sets the Bitbucket repository [env: BITBUCKET_REPO=]
 ```
 
 ## Args