path: root/doc/src/vcs/creator-vcs.qdoc

/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Creator documentation.
**
** 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.
**
****************************************************************************/

// **********************************************************************
// NOTE: the sections are not ordered by their logical order to avoid
// reshuffling the file each time the index order changes (i.e., often).
// Run the fixnavi.pl script to adjust the links to the index order.
// **********************************************************************

/*!
    \contentspage index.html
    \previouspage creator-project-wizards-xml.html
    \page creator-version-control.html
    \nextpage creator-vcs-bazaar.html

    \title Using Version Control Systems

    Version control systems supported by \QC are:
    \table
        \header
            \li  Version Control System
            \li  Address
            \li  Notes
        \row
            \li \l{Using Bazaar}{Bazaar}
            \li \l{http://bazaar.canonical.com/}
            \li
        \row
            \li \l{Using ClearCase}{ClearCase}
            \li \l{http://www-01.ibm.com/software/awdtools/clearcase/}
            \li Disabled by default. To enable the plugin, select
                \uicontrol Help > \uicontrol {About Plugins} >
                \uicontrol {Version Control} > \uicontrol ClearCase, and then
                restart \QC.
        \row
            \li \l{Using CVS}{CVS}
            \li \l{http://www.nongnu.org/cvs/}
            \li
        \row
            \li \l{Using Git}{Git}
            \li \l{http://git-scm.com/}
            \li Git version 1.9.0, or later

                Gerrit version 2.6, or later
        \row
            \li \l{Using Mercurial}{Mercurial}
            \li \l{http://mercurial.selenic.com/}
            \li
        \row
            \li \l{Using Perforce}{Perforce}
            \li \l{http://www.perforce.com}
            \li Server version 2006.1 and later
        \row
            \li \l{Using Subversion}{Subversion}
            \li \l{http://subversion.apache.org/}
            \li Subversion version 1.7.0 and later
    \endtable

    \section1 Setting Up Version Control Systems

    \QC uses the version control system's command line clients to access your
    repositories. To allow access, make sure that the command line clients can
    be located using the \c{PATH} environment variable. Alternatively, specify
    the path to the command line client executable in the \uicontrol Command
    field in the version control system specific tab in \uicontrol Tools >
    \uicontrol Options > \uicontrol {Version Control}.

    If authentication is required to access the repository, enter the user
    credentials in the \uicontrol Username and \uicontrol Password fields.

    Enter a timeout for version control operations in the \uicontrol Timeout
    field.

    For some version control systems, you can specify the maximum number of
    lines the log can contain in the \uicontrol {Log count} field.

    After you set up the version control system, use the command line to check
    that everything works (for example, use the status command). If no issues
    arise, you should be ready to use the system also from \QC.

    For more information on using Git for Windows, see
    \l {Using Git for Windows}.

    \section1 Setting Up General Options

    Select \uicontrol{Tools} > \uicontrol{Options} > \uicontrol{Version Control}
    > \uicontrol{General}
    to specify settings for submit messages:

    \list

        \li \uicontrol{Wrap submit messages at} limits the line length of a
            submit message to the specified number of characters.

        \li \uicontrol{Submit message check script} is a script or program that
            can be used to perform checks on the submit message before
            submitting. The submit message is passed in as the script's first
            parameter. If there is an error, the script should output a
            message on standard error and return a non-zero exit code.

        \li \uicontrol{User/alias configuration file} is a text file that lists
            author names in mailmap format. For each author, you must specify a
            real name and email address and optionally an alias and a second
            email address. For example:

            \code
            Jon Doe <Jon.Doe@company.com> jdoe <jdoe@somemail.com>
            Hans Mustermann <Hans.Mustermann@company.com> hm <info@company.com>
            \endcode

            After you specify a file in this field, you can select authors
            as values of the submit message fields in the \uicontrol Nicknames dialog.

        \li \uicontrol{User fields configuration file} is a simple text file
            consisting of lines specifying submit message fields that take
            authors as values, for example:

            \code
            Acked-by:
            Initial-patch-by:
            Reported-by:
            Rubber-stamped-by:
            Signed-off-by:
            Tested-by:
            \endcode

            After you specify a file in this field, you can add authors as
            values of the submit message fields when submitting changes. If
            you also specified a \uicontrol{User/alias configuration file}, you can
            select authors in the \uicontrol Nicknames dialog.

        \li \uicontrol{SSH prompt command} specifies an ssh-askpass command that you
            can use (on Linux) to prompt the user for a password when using SSH.
            For example, \c ssh-askpass or \c x11-ssh-askpass, depending on the
            ssh-askpass implementation that you use.

        \li \uicontrol {Reset VCS Cache} resets the version control system
            configuration to a state known to \QC after it has been changed
            from the command line, for example.

    \endlist

    \section1 Creating VCS Repositories for New Projects

    \QC allows you to create repositories for version control systems that
    support local repository creation, such as Git, Mercurial, or Bazaar.
    When creating a new project by selecting \uicontrol File > \uicontrol{New File or
    Project}, you can choose a version control system on the final wizard page.

    You can also select \uicontrol Tools and then select \uicontrol {Create Repository}
    in the submenu for the version control system.

    To import a project that is under version control, choose \uicontrol {File >
    New File or Project > Project from Version Control} and select the
    version control system that you use. Follow the instructions of the
    wizard to import the project.

    \section1 Using Common Functions

    The \uicontrol{Tools} menu contains a submenu for each supported version
    control system. This section describes using the functions that are
    available for all the supported version control systems. For more
    information about the additional functions and options available for a
    particular version control system, see the topic dedicated to it.

    The \uicontrol{Version Control} output pane displays the commands that are
    executed, a timestamp, and the relevant output. Select \uicontrol {Window > Output
    Panes > Version Control} to open the pane.

    \image qtcreator-vcs-pane.png

    \section2 Adding Files

    When you create a new file or a new project, the wizard displays a page
    asking whether the files should be added to a version control system.
    This happens when the parent directory or the project is already
    under version control and the system supports the concept of adding files,
    for example, Perforce and Subversion. Alternatively, you can
    add files later by using the version control tool menus.

    With Git, there is no concept of adding files. Instead, all modified
    files must be staged for a commit.

    \section2 Viewing Diff Output

    All version control systems provide menu options to \e{diff} the current
    file or project: to compare it with the latest version stored in the
    repository and to display the differences. In \QC, a diff is displayed in a
    read-only editor. If the file is accessible, you can double-click on a
    selected diff chunk and \QC opens an editor displaying the file, scrolled to
    the line in question.

    \image qtcreator-vcs-diff.png

    With Git and Subversion, the diff is displayed side-by-side in a \l{Comparing Files}
    {diff editor} by default. To use the inline diff view instead, select the
    \uicontrol {Switch to Text Diff Editor} (1) option from the toolbar. In the inline
    diff view, you can use context menu commands to apply, revert, stage, and
    unstage hunks, as well as send them to a code pasting service.

    \section2 Viewing Versioning History and Change Details

    Display the versioning history of a file by selecting \uicontrol{Log}
    or \uicontrol{Filelog}. Typically, the log output contains the date, the commit
    message, and a change or revision identifier. Click on the identifier to
    display a description of the change including the diff in the
    \uicontrol {Git Show} view.

    \image qtcreator-vcs-show.png

    Right-clicking on an identifier brings up a context menu that lets you
    show annotation views of previous versions (see \l{Annotating Files}).
    With Git you can also choose to cherry-pick or revert a change.

    With Git, you can click \inlineimage reload_gray.png
    (\uicontrol Reload) to rescan the files.

    \section2 Annotating Files

    Annotation views are obtained by selecting \uicontrol{Annotate} or \uicontrol{Blame}.
    Selecting \uicontrol{Annotate} or \uicontrol{Blame} displays the lines of the file
    prepended by the change identifier they originate from. Clicking on the
    change identifier shows a detailed description of the change.

    To show the annotation of a previous version, right-click on the
    version identifier at the beginning of a line and choose one of the
    revisions shown at the bottom of the context menu. This allows you to
    navigate through the history of the file and obtain previous versions of
    it. It also works for Git and Mercurial using SHA-1.

    The same context menu is available when right-clicking on a version
    identifier in the file log view of a single file.

    With Git, you can click \inlineimage reload_gray.png
    (\uicontrol Reload) to rescan the files.

    \section2 Committing Changes

    Once you have finished making changes, submit them to the version control
    system by choosing \uicontrol{Commit} or \uicontrol{Submit}. \QC displays a
    commit page containing a text editor where you can enter your commit
    message and a checkable list of modified files to be included.

    \image qtcreator-vcs-commit.png

    When you have finished filling out the commit page information, click on
    \uicontrol{Commit} to start committing.

    The \uicontrol{Diff Selected Files} button brings up a diff view of the
    files selected in the file list. Since the commit page is just another
    editor, you can go back to it by closing the diff view. You can also switch
    to an open diff view by selecting it in the \uicontrol{Open Documents} pane in the
    sidebar.

    \section2 Reverting Changes

    All supported version control systems support reverting your project to
    known states. This functionality is generally called \e reverting.

    The changes discarded depend on the version control system.

    A version control system can replace the \uicontrol Revert menu option with other
    options.

    For more information about reverting changes using Git, see
    \l {Reverting Changes Using Git}.

    \section2 Viewing Status

    You can select \uicontrol{Status} to view the status of the project or
    repository.

    \section2 Updating the Working Tree

    You can select \uicontrol Update to update your working tree with the latest
    changes from the branch. Some version control systems allow you to choose
    between updating the current project and updating all projects.

    With Git, you stash your changes and then pull the changes from the
    repository.

    \section2 Deleting Files

    You can select \uicontrol Delete to delete obsolete files from the repository.

    With Git, you delete the files from the working tree and then stage the
    deleted files for a commit.
*/