# Git Tag<no value>
// <!-- Required for asciidoctor -->
:toc:
// Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] config key
:toclevels: 4

[cols="1^,1^,1^",options=header]
|===
| source | condition | target
| &#10004; | &#10004; | &#10004;
|===

== Description

The `gittag` resource works with the tags of a git repository directly, over the git protocol (no forge API involved, so it works with any host).

**source**::
Returns the tag matching `versionfilter`, or its hash when `key: hash`.

**condition**::
Tests that a matching tag exists. With `tag` set, the check is an exact match instead of a pattern match.

**target**::
**Creates** the tag when no matching one exists. This is the one resource in this family that writes to a repository.

== Parameters

{{< resourceparameters "sources" "gittag" >}}

`url`:: The repository. Over SSH (`git@github.com:updatecli/updatecli.git`), access depends on your local SSH configuration; over HTTPS, on `username` and `password`.
`path`:: A local repository to read instead of cloning.
`key`:: Source only. `name`, the default, returns the tag name; `hash` returns the commit hash it points at. Any other value is rejected with `The only valid values for Key are 'name', 'hash', or empty.`
`tag`:: Condition only - an exact tag, bypassing `versionfilter`.
`message`:: Target only - the annotation message of the tag being created.
`sourcebranch`:: Target only, and required when no `scmid` is set.

=== Avoiding a clone

`lsremote: true` lists the tags straight from the remote with `git ls-remote`, without cloning. On a large repository that is the difference between a second and a minute, and it is enough for any source or condition that only needs tag names.

`depth` limits how many commits are fetched when a clone does happen.

[WARNING]
====
`lsremote` and `depth` both mean an incomplete local repository. A `key: hash` lookup or a target creating a tag needs real objects, so leave them off there.
====

=== Version Filter

include::content/en/docs/plugins/_versionFilter.adoc[]

== Example

[source,yaml]
----
# updatecli.yaml
{{<include "assets/code_example/docs/plugins/resources/gittag/updatecli.yaml">}}
----

== Links

* link:/docs/plugins/resource/gitBranch/[The `gitbranch` resource]
* link:/docs/plugins/resource/gitcommit/[The `gitcommit` resource]
* link:/docs/core/versionfilter/["Version Filtering" page]