From a166ab49493577d60dad1cb3ca3f3a5a36171115 Mon Sep 17 00:00:00 2001 From: Lars Kappert Date: Sat, 8 Jul 2023 21:34:29 +0200 Subject: [PATCH] Edit and move new section about `getLatestTagFromAllRefs` up in docs --- docs/git.md | 28 +++++++++++++++++----------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/docs/git.md b/docs/git.md index c5fd3d14..49b303df 100644 --- a/docs/git.md +++ b/docs/git.md @@ -64,7 +64,23 @@ normally used exclusively in pre-releases. Example: `git.tagExclude: *[-]*` -:bulb: N.b. `git.tagExclude` has no effect when `git.getLatestTagFromAllRefs: true` (see '[use all refs to determine latest tag](#use-all-refs-to-determine-latest-tag)'). +Note that `git.tagExclude` has no effect when `git.getLatestTagFromAllRefs: true`. See the next section +[use all refs to determine latest tag](#use-all-refs-to-determine-latest-tag) for more details. + +## Use all refs to determine latest tag + +By default, Git determines the latest tag using [`git describe`](https://git-scm.com/docs/git-describe), which finds the +most recent tag _that is reachable from a commit._ If you wish to consider all tags, e.g. to include tags that point to +sibling commits on different branches, then set `git.getLatestTagFromAllRefs: true` (the default is `false`). + +![Determine latest tag from all refs](assets/git-version-from-all-refs.svg) + +In the above illustration, releasing from `develop` and incrementing the semver `rc` modifier, when +`git.getLatestTagFromAllRefs: false` (the default), the latest tag is `v1.1.0-rc1`, because that is the most recent tag +reachable from the current commit (the red circle on `develop`). The version to release will therefore be `v1.1.0-rc2`. + +Setting `git.getLatestTagFromAllRefs: true` considers all tags (sorting them by version), whether directly reachable or +not. In which case, the latest tag is `v1.1.0` from `main`, and the new version to release is `v1.2.0-rc1`. ## Extra arguments @@ -98,16 +114,6 @@ Use e.g. `git.tag: false` or `--no-git.tag` to skip a single step. By default, untracked files are not added to the release commit. Use `git.addUntrackedFiles: true` to override this behavior. -## Use all refs to determine latest tag - -By default, Git determines the latest tag using [`git describe`](https://git-scm.com/docs/git-describe), which finds the most recent tag _that is reachable from a commit._ If you wish to consider all tags, e.g. to include tags that point to sibling commits on different branches, then set `git.getLatestTagFromAllRefs: true` (the default is `false`). - -![Determine latest tag from all refs](assets/git-version-from-all-refs.svg) - -In the above illustration, releasing from `develop` and incrementing the semver `rc` modifier, when `git.getLatestTagFromAllRefs: false` (the default), the latest tag is `v1.1.0-rc1`, because that is the most recent tag reachable from the current commit (the red circle on `develop`). The version to release will therefore be `v1.1.0-rc2`. - -Setting `git.getLatestTagFromAllRefs: true` considers all tags (sorting them by version), whether directly reachable or not. In which case, the latest tag is `v1.1.0` from `main`, and the new version to release is `v1.2.0-rc1`. - ## Prerequisite checks ### Required branch