diff --git a/doc/qtcreator/images/qtcreator-gitlab-clone-repository.png b/doc/qtcreator/images/qtcreator-gitlab-clone-repository.png new file mode 100644 index 00000000000..35194c4e4f2 Binary files /dev/null and b/doc/qtcreator/images/qtcreator-gitlab-clone-repository.png differ diff --git a/doc/qtcreator/images/qtcreator-gitlab-preferences-add-server.png b/doc/qtcreator/images/qtcreator-gitlab-preferences-add-server.png new file mode 100644 index 00000000000..f1963b3484d Binary files /dev/null and b/doc/qtcreator/images/qtcreator-gitlab-preferences-add-server.png differ diff --git a/doc/qtcreator/images/qtcreator-gitlab-preferences-project.png b/doc/qtcreator/images/qtcreator-gitlab-preferences-project.png new file mode 100644 index 00000000000..835434f5c35 Binary files /dev/null and b/doc/qtcreator/images/qtcreator-gitlab-preferences-project.png differ diff --git a/doc/qtcreator/images/qtcreator-gitlab-preferences.png b/doc/qtcreator/images/qtcreator-gitlab-preferences.png new file mode 100644 index 00000000000..459d5d60ccb Binary files /dev/null and b/doc/qtcreator/images/qtcreator-gitlab-preferences.png differ diff --git a/doc/qtcreator/images/qtcreator-gitlab-project-list.png b/doc/qtcreator/images/qtcreator-gitlab-project-list.png new file mode 100644 index 00000000000..039e294ef97 Binary files /dev/null and b/doc/qtcreator/images/qtcreator-gitlab-project-list.png differ diff --git a/doc/qtcreator/src/qtcreator-toc.qdoc b/doc/qtcreator/src/qtcreator-toc.qdoc index ffdc1f1f039..b401e05bffa 100644 --- a/doc/qtcreator/src/qtcreator-toc.qdoc +++ b/doc/qtcreator/src/qtcreator-toc.qdoc @@ -69,6 +69,7 @@ \li \l{Using ClearCase} \li \l{Using CVS} \li \l{Using Git} + \li \l{Using GitLab} \li \l{Using Mercurial} \li \l{Using Perforce} \li \l{Using Subversion} diff --git a/doc/qtcreator/src/vcs/creator-only/creator-vcs-gitlab.qdoc b/doc/qtcreator/src/vcs/creator-only/creator-vcs-gitlab.qdoc new file mode 100644 index 00000000000..7c4e9589a48 --- /dev/null +++ b/doc/qtcreator/src/vcs/creator-only/creator-vcs-gitlab.qdoc @@ -0,0 +1,146 @@ +/**************************************************************************** +** +** Copyright (C) 2022 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. +** +****************************************************************************/ + +/*! + \previouspage creator-vcs-git.html + \page creator-vcs-gitlab.html + \nextpage creator-vcs-mercurial.html + + \title Using GitLab + + GitLab is a DevOps tool developed by GitLab. You can clone projects from + GitLab servers and use \l{Using Git}{Git} to manage your local and remote + repositories. + + To enable the experimental GitLab plugin, select \uicontrol Help > + \uicontrol {About Plugins} > \uicontrol {Version Control} > + \uicontrol GitLab. Then select \uicontrol {Restart Now} to + restart \QC and load the plugin. + + To use GitLab, you must create a connection to the GitLab server and clone + the projects you want to work on. You can also link previously cloned + projects to GitLab in the project settings. This enables you to receive + event notifications in the \l {Viewing Output}{Version Control} pane. + + \section1 Connecting to GitLab Servers + + To connect to a GitLab server, you need to specify the server host name and + port number, as well as an access token that you create in GitLab for \QC. + The permission scope of the token must be at least \c read_api or \c api. + + To specify connections to GitLab servers, select \uicontrol Edit > + \uicontrol Preferences > \uicontrol {Version Control} > \uicontrol GitLab: + + \image qtcreator-gitlab-preferences.png + + To add GitLab servers: + + \list 1 + \li Select \uicontrol Add to open the \uicontrol {Add Server} dialog: + \image qtcreator-gitlab-preferences-add-server.png + \li In \uicontrol Host, enter the host name of the GitLab server. + \li In \uicontrol Description, enter a free-form text that is displayed + in the GitLab settings of a linked project. + \li In \uicontrol {Access token}, enter the access token you created for + \QC in the GitLab server, in \uicontrol Preferences > + \uicontrol {Access Tokens}. + \li In \uicontrol Port, enter a port number. + \li Deselect the \uicontrol HTTPS check box to use an HTTP connection + instead of a secure connection. + \li Select \uicontrol Add to create the connection. + \endlist + + In the \uicontrol GitLab tab, \uicontrol curl displays the path to the + \c curl tool used for HTTP connections. You can specify another path to + use another instance of the tool than the one found by \QC. + + To edit the selected connection, select \uicontrol Edit. + + To remove the selected connection, select \uicontrol Remove. + + \section1 Cloning Projects + + You can clone projects from the connected GitLab servers. \QC reads your + user name and ID from the access token and displays the available projects + in each server. You can search for a particular project or browse projects + in the list. + + To clone projects from GitLab: + + \list 1 + \li Select \uicontrol Tools > \uicontrol GitLab to view a list of + connected GitLab servers and available projects in each server: + \image qtcreator-gitlab-project-list.png + \li In \uicontrol Remote, select a GitLab server. + \li In \uicontrol Projects, select the project to clone. + \li Select \uicontrol Clone to open the \uicontrol {Clone Repository} + dialog: + \image qtcreator-gitlab-clone-repository.png + \li In \uicontrol Repository, specify the URL of the repository. + \li In \uicontrol Path, specify the path where to clone the repository. + \li In \uicontrol Directory, specify the name of the directory for the + cloned repository. + \li Select the \uicontrol Recursive check box to also clone submodules + of the repository. + \li Select \uicontrol Clone to clone the project to the specified + directory. + \endlist + + \QC automatically opens the project. If the cloned project has several + project files (such as CMakeList.txt, .pro, and .qbs), \QC prompts you to + select the one to open. If it does not contain a project file that \QC can + open, select \uicontrol File > \uicontrol {New Project} > + \uicontrol {Import Project} > \uicontrol {Import Existing Project} to + import the project as a generic project. For more information, see + \l {Using Project Wizards}. + + \section1 Linking Projects with GitLab + + Link a project with a GitLab token to receive notifications on events, such + as merge requests, issues, or comments, in the \uicontrol {Version Control} + pane. The information is fetched every 15 minutes. Only events that occurred + after the last time you logged into GitLab are displayed when you open the + project for the first time. Subsequently, events that occurred after the last + successful fetch are listed. + + To link with GitLab: + + \list 1 + \li In the \uicontrol Projects mode, select \uicontrol {GitLab} to view + the GitLab settings for the currently active project: + \image qtcreator-gitlab-preferences-project.png + \li In \uicontrol Host, select the URL of the GitLab server. + \li In \uicontrol {Linked GitLab configuration}, select the GitLab + server settings to use. + \li Select \uicontrol {Link with GitLab} to receive event notifications + in the \uicontrol {Version Control} pane. + \endlist + + To test the connection to the host using the access token specified in the + GitLab configuration, select \uicontrol {Test Connection}. + + To stop the reception of event notifications, select + \uicontrol {Unlink from GitLab}. +*/ diff --git a/doc/qtcreator/src/vcs/creator-only/creator-vcs-mercurial.qdoc b/doc/qtcreator/src/vcs/creator-only/creator-vcs-mercurial.qdoc index 244cb995a8b..e4212947a7b 100644 --- a/doc/qtcreator/src/vcs/creator-only/creator-vcs-mercurial.qdoc +++ b/doc/qtcreator/src/vcs/creator-only/creator-vcs-mercurial.qdoc @@ -30,7 +30,7 @@ // ********************************************************************** /*! - \previouspage creator-vcs-git.html + \previouspage creator-vcs-gitlab.html \page creator-vcs-mercurial.html \nextpage creator-vcs-perforce.html diff --git a/doc/qtcreator/src/vcs/creator-only/creator-vcs.qdoc b/doc/qtcreator/src/vcs/creator-only/creator-vcs.qdoc index 3555b137d82..27869401a4d 100644 --- a/doc/qtcreator/src/vcs/creator-only/creator-vcs.qdoc +++ b/doc/qtcreator/src/vcs/creator-only/creator-vcs.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2020 The Qt Company Ltd. +** Copyright (C) 2022 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Creator documentation. @@ -72,6 +72,10 @@ \li Git version 1.9.0, or later Gerrit version 2.6, or later + \row + \li \l{Using GitLab}{GitLab} + \li \l{http://gitlab.com/} + \li Experimental \row \li \l{Using Mercurial}{Mercurial} \li \l{http://mercurial.selenic.com/} @@ -124,6 +128,7 @@ \li \l{https://doc.qt.io/qtcreator/creator-vcs-fossil.html} {Qt Creator Fossil Plugin Manual} \li \l{Using Git} + \li \l{Using GitLab} \li \l{Using Mercurial} \li \l{Using Perforce} \li \l{Using Subversion} diff --git a/doc/qtcreator/src/vcs/creator-vcs-git.qdoc b/doc/qtcreator/src/vcs/creator-vcs-git.qdoc index e4ced3102b0..bb1e08c611e 100644 --- a/doc/qtcreator/src/vcs/creator-vcs-git.qdoc +++ b/doc/qtcreator/src/vcs/creator-vcs-git.qdoc @@ -36,7 +36,7 @@ \nextpage studio-porting-projects.html \else \previouspage creator-vcs-cvs.html - \nextpage creator-vcs-mercurial.html + \nextpage creator-vcs-gitlab.html \endif \title Using Git