Back to Doc.qt.io
Contact Us Blog Download Qt

vcs

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

Since: Qbs 1.10

Properties

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"


[since Qbs 3.1.0] repoCommitSha : string

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.


[since Qbs 3.1.0] repoCommitsSinceTag : string

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).


[since Qbs 3.1.0] repoLatestTag : string

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


© 2022 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.