<!-- NOTE: THIS FILE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/attribute_namespace.md.j2 -->

# VCS

- [VCS Repository Attributes](#vcs-repository-attributes)
- [VCS Deprecated Attributes](#vcs-deprecated-attributes)

## VCS Repository Attributes

This group defines the attributes for [Version Control Systems (VCS)](https://wikipedia.org/wiki/Version_control).

| Attribute | Type | Description | Examples | Stability |
|---|---|---|---|---|
| <a id="vcs-change-id" href="#vcs-change-id">`vcs.change.id`</a> | string | The ID of the change (pull request/merge request/changelist) if applicable. This is usually a unique (within repository) identifier generated by the VCS system. | `123` | ![Development](https://img.shields.io/badge/-development-blue) |
| <a id="vcs-change-state" href="#vcs-change-state">`vcs.change.state`</a> | string | The state of the change (pull request/merge request/changelist). | `open`; `closed`; `merged` | ![Development](https://img.shields.io/badge/-development-blue) |
| <a id="vcs-change-title" href="#vcs-change-title">`vcs.change.title`</a> | string | The human readable title of the change (pull request/merge request/changelist). This title is often a brief summary of the change and may get merged in to a ref as the commit summary. | `Fixes broken thing`; `feat: add my new feature`; `[chore] update dependency` | ![Development](https://img.shields.io/badge/-development-blue) |
| <a id="vcs-line-change-type" href="#vcs-line-change-type">`vcs.line_change.type`</a> | string | The type of line change being measured on a branch or change. | `added`; `removed` | ![Development](https://img.shields.io/badge/-development-blue) |
| <a id="vcs-owner-name" href="#vcs-owner-name">`vcs.owner.name`</a> | string | The group owner within the version control system. | `my-org`; `myteam`; `business-unit` | ![Development](https://img.shields.io/badge/-development-blue) |
| <a id="vcs-provider-name" href="#vcs-provider-name">`vcs.provider.name`</a> | string | The name of the version control system provider. | `github`; `gitlab`; `gitea`; `bitbucket` | ![Development](https://img.shields.io/badge/-development-blue) |
| <a id="vcs-ref-base-name" href="#vcs-ref-base-name">`vcs.ref.base.name`</a> | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. [1] | `my-feature-branch`; `tag-1-test` | ![Development](https://img.shields.io/badge/-development-blue) |
| <a id="vcs-ref-base-revision" href="#vcs-ref-base-revision">`vcs.ref.base.revision`</a> | string | The revision, literally [revised version](https://www.merriam-webster.com/dictionary/revision), The revision most often refers to a commit object in Git, or a revision number in SVN. [2] | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` | ![Development](https://img.shields.io/badge/-development-blue) |
| <a id="vcs-ref-base-type" href="#vcs-ref-base-type">`vcs.ref.base.type`</a> | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. [3] | `branch`; `tag` | ![Development](https://img.shields.io/badge/-development-blue) |
| <a id="vcs-ref-head-name" href="#vcs-ref-head-name">`vcs.ref.head.name`</a> | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. [4] | `my-feature-branch`; `tag-1-test` | ![Development](https://img.shields.io/badge/-development-blue) |
| <a id="vcs-ref-head-revision" href="#vcs-ref-head-revision">`vcs.ref.head.revision`</a> | string | The revision, literally [revised version](https://www.merriam-webster.com/dictionary/revision), The revision most often refers to a commit object in Git, or a revision number in SVN. [5] | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` | ![Development](https://img.shields.io/badge/-development-blue) |
| <a id="vcs-ref-head-type" href="#vcs-ref-head-type">`vcs.ref.head.type`</a> | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. [6] | `branch`; `tag` | ![Development](https://img.shields.io/badge/-development-blue) |
| <a id="vcs-ref-type" href="#vcs-ref-type">`vcs.ref.type`</a> | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | ![Development](https://img.shields.io/badge/-development-blue) |
| <a id="vcs-repository-name" href="#vcs-repository-name">`vcs.repository.name`</a> | string | The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [7] | `semantic-conventions`; `my-cool-repo` | ![Development](https://img.shields.io/badge/-development-blue) |
| <a id="vcs-repository-url-full" href="#vcs-repository-url-full">`vcs.repository.url.full`</a> | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [8] | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | ![Development](https://img.shields.io/badge/-development-blue) |
| <a id="vcs-revision-delta-direction" href="#vcs-revision-delta-direction">`vcs.revision_delta.direction`</a> | string | The type of revision comparison. | `ahead`; `behind` | ![Development](https://img.shields.io/badge/-development-blue) |

**[1] `vcs.ref.base.name`:** `base` refers to the starting point of a change. For example, `main`
would be the base reference of type branch if you've created a new
reference of type branch from it and created new commits.

**[2] `vcs.ref.base.revision`:** `base` refers to the starting point of a change. For example, `main`
would be the base reference of type branch if you've created a new
reference of type branch from it and created new commits. The
revision can be a full [hash value (see
glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf),
of the recorded change to a ref within a repository pointing to a
commit [commit](https://git-scm.com/docs/git-commit) object. It does
not necessarily have to be a hash; it can simply define a [revision
number](https://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html)
which is an integer that is monotonically increasing. In cases where
it is identical to the `ref.base.name`, it SHOULD still be included.
It is up to the implementer to decide which value to set as the
revision based on the VCS system and situational context.

**[3] `vcs.ref.base.type`:** `base` refers to the starting point of a change. For example, `main`
would be the base reference of type branch if you've created a new
reference of type branch from it and created new commits.

**[4] `vcs.ref.head.name`:** `head` refers to where you are right now; the current reference at a
given time.

**[5] `vcs.ref.head.revision`:** `head` refers to where you are right now; the current reference at a
given time.The revision can be a full [hash value (see
glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf),
of the recorded change to a ref within a repository pointing to a
commit [commit](https://git-scm.com/docs/git-commit) object. It does
not necessarily have to be a hash; it can simply define a [revision
number](https://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html)
which is an integer that is monotonically increasing. In cases where
it is identical to the `ref.head.name`, it SHOULD still be included.
It is up to the implementer to decide which value to set as the
revision based on the VCS system and situational context.

**[6] `vcs.ref.head.type`:** `head` refers to where you are right now; the current reference at a
given time.

**[7] `vcs.repository.name`:** Due to it only being the name, it can clash with forks of the same
repository if collecting telemetry across multiple orgs or groups in
the same backends.

**[8] `vcs.repository.url.full`:** In Git Version Control Systems, the canonical URL SHOULD NOT include
the `.git` extension.

---

`vcs.change.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

| Value  | Description | Stability |
|---|---|---|
| `closed` | Closed means the merge request has been closed without merging. This can happen for various reasons, such as the changes being deemed unnecessary, the issue being resolved in another way, or the author deciding to withdraw the request. | ![Development](https://img.shields.io/badge/-development-blue) |
| `merged` | Merged indicates that the change has been successfully integrated into the target codebase. | ![Development](https://img.shields.io/badge/-development-blue) |
| `open` | Open means the change is currently active and under review. It hasn't been merged into the target branch yet, and it's still possible to make changes or add comments. | ![Development](https://img.shields.io/badge/-development-blue) |
| `wip` | WIP (work-in-progress, draft) means the change is still in progress and not yet ready for a full review. It might still undergo significant changes. | ![Development](https://img.shields.io/badge/-development-blue) |

---

`vcs.line_change.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

| Value  | Description | Stability |
|---|---|---|
| `added` | How many lines were added. | ![Development](https://img.shields.io/badge/-development-blue) |
| `removed` | How many lines were removed. | ![Development](https://img.shields.io/badge/-development-blue) |

---

`vcs.provider.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

| Value  | Description | Stability |
|---|---|---|
| `bitbucket` | [Bitbucket](https://bitbucket.org) | ![Development](https://img.shields.io/badge/-development-blue) |
| `gitea` | [Gitea](https://gitea.io) | ![Development](https://img.shields.io/badge/-development-blue) |
| `github` | [GitHub](https://github.com) | ![Development](https://img.shields.io/badge/-development-blue) |
| `gitlab` | [GitLab](https://gitlab.com) | ![Development](https://img.shields.io/badge/-development-blue) |

---

`vcs.ref.base.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

| Value  | Description | Stability |
|---|---|---|
| `branch` | [branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch) | ![Development](https://img.shields.io/badge/-development-blue) |
| `tag` | [tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag) | ![Development](https://img.shields.io/badge/-development-blue) |

---

`vcs.ref.head.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

| Value  | Description | Stability |
|---|---|---|
| `branch` | [branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch) | ![Development](https://img.shields.io/badge/-development-blue) |
| `tag` | [tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag) | ![Development](https://img.shields.io/badge/-development-blue) |

---

`vcs.ref.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

| Value  | Description | Stability |
|---|---|---|
| `branch` | [branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch) | ![Development](https://img.shields.io/badge/-development-blue) |
| `tag` | [tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag) | ![Development](https://img.shields.io/badge/-development-blue) |

---

`vcs.revision_delta.direction` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

| Value  | Description | Stability |
|---|---|---|
| `ahead` | How many revisions the change is ahead of the target ref. | ![Development](https://img.shields.io/badge/-development-blue) |
| `behind` | How many revisions the change is behind the target ref. | ![Development](https://img.shields.io/badge/-development-blue) |

## VCS Deprecated Attributes

"Describes deprecated vcs attributes."

| Attribute | Type | Description | Examples | Stability |
|---|---|---|---|---|
| <a id="vcs-repository-change-id" href="#vcs-repository-change-id">`vcs.repository.change.id`</a> | string | Deprecated, use `vcs.change.id` instead. | `123` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Deprecated, use `vcs.change.id` instead. |
| <a id="vcs-repository-change-title" href="#vcs-repository-change-title">`vcs.repository.change.title`</a> | string | Deprecated, use `vcs.change.title` instead. | `Fixes broken thing`; `feat: add my new feature`; `[chore] update dependency` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Deprecated, use `vcs.change.title` instead. |
| <a id="vcs-repository-ref-name" href="#vcs-repository-ref-name">`vcs.repository.ref.name`</a> | string | Deprecated, use `vcs.ref.head.name` instead. | `my-feature-branch`; `tag-1-test` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Deprecated, use `vcs.ref.head.name` instead. |
| <a id="vcs-repository-ref-revision" href="#vcs-repository-ref-revision">`vcs.repository.ref.revision`</a> | string | Deprecated, use `vcs.ref.head.revision` instead. | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Deprecated, use `vcs.ref.head.revision` instead. |
| <a id="vcs-repository-ref-type" href="#vcs-repository-ref-type">`vcs.repository.ref.type`</a> | string | Deprecated, use `vcs.ref.head.type` instead. | `branch`; `tag` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Deprecated, use `vcs.ref.head.type` instead. |

---

`vcs.repository.ref.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

| Value  | Description | Stability |
|---|---|---|
| `branch` | [branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch) | ![Development](https://img.shields.io/badge/-development-blue) |
| `tag` | [tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag) | ![Development](https://img.shields.io/badge/-development-blue) |
