Skip to content

Commit

Permalink
Edit and move new section about getLatestTagFromAllRefs up in docs
Browse files Browse the repository at this point in the history
  • Loading branch information
webpro committed Jul 8, 2023
1 parent 930e80a commit a166ab4
Showing 1 changed file with 17 additions and 11 deletions.
28 changes: 17 additions & 11 deletions docs/git.md
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down

0 comments on commit a166ab4

Please sign in to comment.