vcs | Qbs Manual
Description: Provides support for version control systems (Git, SVN, Mercurial).

- Qbs Manual
- QbsModules
- vcs
- Qbs 3.1.1

# vcs

Provides support for version control systems (Git, SVN, Mercurial). More...

Since: | Qbs 1.10

- List of all members, including inherited members

## Properties

- headerFileName : string
- repoCommitSha : string `(since Qbs 3.1.0)`
- repoCommitsSinceTag : string `(since Qbs 3.1.0)`
- repoDir : string
- repoLatestTag : string `(since Qbs 3.1.0)`
- repoState : string
- toolFilePath : string
- type : string

## Detailed Description

The `vcs` module provides information about the current state of the project's repository. This is useful for embedding version information directly into your binaries, such as the latest tag, number of commits since the tag, and current commit hash.

By default, a C header file is generated, which defines macros representing the repository state. This allows C/C++ code to access this information at run time.

Supported version control systems:

- Git
- Subversion (SVN)
- Mercurial (hg)

For example:

     #include <vcs-repo-state.h>
     #include <iostream>

     int main()
     {
         std::cout << "I was built from " << VCS_REPO_STATE << std::endl;
         std::cout << "Latest tag: " << VCS_REPO_LATEST_TAG << std::endl;
         std::cout << "Commits since tag: " << VCS_REPO_COMMITS_SINCE_TAG << std::endl;
         std::cout << "Commit SHA: " << VCS_REPO_COMMIT_SHA << std::endl;
     }

Above, a header file called `vcs-repo-state.h` is created, defining a macro called `VCS_REPO_STATE`, which expands to a character constant describing the current state of the repository. For Git, this would be the current HEAD's commit hash.

Example:

     VCS_REPO_STATE = "v1.2.3-5-gabcdef0"
     VCS_REPO_LATEST_TAG = "v1.2.3"
     VCS_REPO_COMMITS_SINCE_TAG = "5"
     VCS_REPO_COMMIT_SHA = "gabcdef0"

For Git repositories without any tags, the commit hash will be used instead. For Mercurial repositories, the full repository state is always shown. For SVN, only repoState is currently available.

## Property Documentation

headerFileName : string

The name of the C header file to be generated. This header file defines the following macros:

- `VCS_REPO_STATE` — Full repository state string
- `VCS_REPO_LATEST_TAG` — Latest tag reachable from HEAD (or "none")
- `VCS_REPO_COMMITS_SINCE_TAG` — Number of commits since latest tag (or "none")
- `VCS_REPO_COMMIT_SHA` — Current commit SHA (or "none")

Set this to `undefined` to disable header file generation.

Default: `"vcs-repo-state.h"`

repoCommitSha : string `[since Qbs 3.1.0]`

The abbreviated commit hash of HEAD.

For Git, this is the `gSHA` component from `git` describe output. If no tags are present, this will be set to the commit hash prefixed with `g`.

For Mercurial, this is the `m{node|short}` component from the template.

For SVN, this property is currently not set and will be `"none"`.

Default: Undefined

This property was introduced in Qbs 3.1.0.

repoCommitsSinceTag : string `[since Qbs 3.1.0]`

The number of commits since the latest tag.

For Git, this is the `N` component from `git` describe output. If no tags are present, this will be set to `"none"`.

For Mercurial, this is the `latesttagdistance` component from the template.

For SVN, this property is currently not set and will be `"none"`.

Default: Undefined

This property was introduced in Qbs 3.1.0.

repoDir : string

The root directory of the repository.

Default: The top-level project directory (project.sourceDirectory).

repoLatestTag : string `[since Qbs 3.1.0]`

The latest reachable tag in the repository.

For Git, this is the `TAG` component from `git` describe output. If no tags are present, this will be set to `"none"`.

For Mercurial, this is the `latesttag` component from the template.

For SVN, this property is currently not set and will be `"none"`.

Default: Undefined

This property was introduced in Qbs 3.1.0.

repoState : string

The full repository state string.

For Git, this corresponds to the output of: `git describe --tags --always --long HEAD`

Example values:

- `abc1234` (no tags)
- `abc1234-0-gabc1234` (at tag)
- `v1.0.0-3-gabc1234` (3 commits after tag)

For Mercurial, this corresponds to the output of: `hg log -r . --template "{latesttag}-{latesttagdistance}-m{node|short}"`

Example values:

- `null-0-m000000000000` (empty repo)
- `null-1-mabc1234` (no tags)
- `null-3-mabc1234` (4 commits, no tags)
- `v1.0.0-1-mabc1234` (at tag)
- `v1.0.0-3-mabc1234` (4 commits after tag)

For SVN, this is the current revision number.

Default: Undefined

toolFilePath : string

Set this property if the tool has an unusual name in your local installation, or if it is located in a directory that is not in the build environment's `PATH`.

Default: The file name of the version control tool corresponding to type.

type : string

The version control system used in the project.

Currently, the supported values are `"git"`, `"hg"` and `"svn"`.

Default: auto-detected