/****************************************************************************
**
** Copyright (C) 2017 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of Qbs.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \qmltype vcs
    \inqmlmodule QbsModules
    \since Qbs 1.10

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

    The \c 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:
    \list
        \li Git
        \li Subversion (SVN)
        \li Mercurial (hg)
    \endlist

    For example:

    \code
    #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;
    }
    \endcode

    Above, a header file called \c{vcs-repo-state.h} is created, defining a
    macro called \c 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:

    \code
    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"
    \endcode

    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 \l{vcs::}{repoState} is currently available.
*/

/*!
    \qmlproperty string vcs::headerFileName

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

    \list
        \li \c VCS_REPO_STATE — Full repository state string
        \li \c VCS_REPO_LATEST_TAG — Latest tag reachable from HEAD (or "none")
        \li \c VCS_REPO_COMMITS_SINCE_TAG — Number of commits since latest tag (or "none")
        \li \c VCS_REPO_COMMIT_SHA — Current commit SHA (or "none")
    \endlist

    Set this to \c undefined to disable header file generation.

    \defaultvalue \c{"vcs-repo-state.h"}
*/

/*!
    \qmlproperty string vcs::repoDir

    The root directory of the repository.

    \defaultvalue The top-level project directory (\l{Project::sourceDirectory}
    {project.sourceDirectory}).
*/

/*!
    \qmlproperty string vcs::repoState

    The full repository state string.

    For Git, this corresponds to the output of:
    \c {git describe --tags --always --long HEAD}

    Example values:
    \list
        \li \c abc1234 (no tags)
        \li \c abc1234-0-gabc1234 (at tag)
        \li \c v1.0.0-3-gabc1234 (3 commits after tag)
    \endlist

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

    Example values:
    \list
        \li \c null-0-m000000000000 (empty repo)
        \li \c null-1-mabc1234 (no tags)
        \li \c null-3-mabc1234 (4 commits, no tags)
        \li \c v1.0.0-1-mabc1234 (at tag)
        \li \c v1.0.0-3-mabc1234 (4 commits after tag)
    \endlist

    For SVN, this is the current revision number.

    \nodefaultvalue
*/

/*!
    \qmlproperty string vcs::repoLatestTag

    The latest reachable tag in the repository.

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

    For Mercurial, this is the \c {latesttag} component from the template.

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

    \nodefaultvalue
    \since Qbs 3.1.0
*/

/*!
    \qmlproperty string vcs::repoCommitsSinceTag

    The number of commits since the latest tag.

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

    For Mercurial, this is the \c {latesttagdistance} component from the template.

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

    \nodefaultvalue
    \since Qbs 3.1.0
*/

/*!
    \qmlproperty string vcs::repoCommitSha

    The abbreviated commit hash of HEAD.

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

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

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

    \nodefaultvalue
    \since Qbs 3.1.0
*/

/*!
    \qmlproperty string vcs::toolFilePath

    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 \c PATH.

    \defaultvalue The file name of the version control tool corresponding to
    \l{vcs::type}{type}.
*/

/*!
    \qmlproperty string vcs::type

    The version control system used in the project.

    Currently, the supported values are \c{"git"}, \c{"hg"} and \c{"svn"}.

    \defaultvalue auto-detected
*/
