Doc: Try to make the Git information more visible

- Create a new category for Git topics
- Split the Git topic into several small topics
- Add descriptions of features that users were
  missing even though they are there

Change-Id: Iddae03b0149bef9435c09883fe91207ddfa195f7
Reviewed-by: André Hartmann <aha_1980@gmx.de>
Reviewed-by: Orgad Shaneh <orgads@gmail.com>
Reviewed-by: Mats Honkamaa <mats.honkamaa@qt.io>

doc/qtcreator/src/external-resources/external-resources.qdoc

@@ -273,3 +273,11 @@
     \externalpage https://clang.llvm.org/docs/LibFormat.html
     \title LibFormat: Documentation
 */
+/*!
+    \externalpage https://git-scm.com/downloads
+    \title Git Downloads
+*/
+/*!
+    \externalpage https://www.gerritcodereview.com/
+    \title Gerrit Code Review
+*/

doc/qtcreator/src/howto/creator-only/creator-how-tos.qdoc

@@ -240,6 +240,34 @@
 
     \generatelist creator-how-to-test
 
+    \section1 Use Git
+
+    \l{Git} is a fast decentralized version control system
+    that is available for Windows, Linux, and \macos. You can use the
+    \l {Gerrit Code Review} tool for projects that use Git.
+
+    \generatelist creator-how-to-git
+
+    \section2 Current file
+
+    \generatelist creator-how-to-git-current-file
+
+    \section2 Current project
+
+    \generatelist creator-how-to-git-current-project
+
+    \section2 Local repositories
+
+    \generatelist creator-how-to-git-local-repository
+
+    \section2 Commits
+
+    \generatelist creator-how-to-git-commits
+
+    \section2 Remote repositories
+
+    \generatelist creator-how-to-git-remote-repository
+
     \section1 Use \QC
 
     Use basic \QC features and preinstalled plugins. Install more plugins and

doc/qtcreator/src/qtcreator-toc.qdoc

@@ -93,6 +93,20 @@
                 \generatelist creator-how-to-get-help
             \li Test
                 \generatelist creator-how-to-test
+            \li Use Git
+                \generatelist creator-how-to-git
+                \list
+                    \li Current file
+                        \generatelist creator-how-to-git-current-file
+                    \li Current project
+                        \generatelist creator-how-to-git-current-project
+                    \li Local repositories
+                        \generatelist creator-how-to-git-local-repository
+                    \li Commits
+                        \generatelist creator-how-to-git-commits
+                    \li Remote repositories
+                        \generatelist creator-how-to-git-remote-repository
+                \endlist
             \li Use \QC
                 \generatelist creator-how-to-use
             \li Use the UI

doc/qtcreator/src/qtcreator.qdoc

@@ -86,6 +86,7 @@
                     \list
                         \li \l{Use \QC}
                         \li \l{Use the UI}
+                        \li \l{Use Git}
                         \li \l{Design UIs}
                         \li \l{Create Models and Diagrams}
                         \li \l{Read Documentation}

doc/qtcreator/src/vcs/creator-only/creator-how-to-use-git-on-windows.qdoc

@@ -0,0 +1,30 @@
+// Copyright (C) 2024 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+    \page creator-how-to-use-git-on-windows.html
+    \previouspage creator-how-tos.html
+
+    \ingroup creator-how-to-git
+
+    \title Use Git for Windows
+
+    If you configure Git for use with \c {git bash} only, and use SSH
+    authorization, Git looks for the SSH keys in the directory where the
+    \c HOME environment points to. The variable is always set by \c {git bash}.
+
+    However, the variable is typically not set in a Windows command prompt. When
+    you run Git from a Windows command prompt, it looks for the SSH keys in its
+    installation directory, and therefore, the authorization fails.
+
+    You can set the \c HOME environment variable from \QC. Go to \preferences >
+    \uicontrol {Version Control} > \uicontrol Git, and then select
+    \uicontrol {Set "HOME" environment variable}. \c HOME is
+    set to \c %HOMEDRIVE%%HOMEPATH% when the Git executable is run and
+    authorization works as it would with \c {git bash}.
+
+    \image qtcreator-preferences-vcs-git.webp {Git preferences}
+
+    \sa {Use Git}{How To: Use Git}, {Compare files},
+    {Set up version control systems}, {Version Control Systems}
+*/

doc/qtcreator/src/vcs/creator-only/creator-vcs-preferences.qdoc

@@ -6,6 +6,7 @@
     \previouspage creator-how-tos.html
 
     \ingroup creator-how-to-use
+    \ingroup creator-how-to-git
 
     \title Set up version control systems
 
@@ -23,7 +24,7 @@
     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}.
+    \l {Use Git for Windows}.
 
     \section1 General VCS preferences
 
@@ -82,5 +83,5 @@
     To show file status, go to \preferences > \uicontrol {Version Control}
     > \uicontrol General, and then select \uicontrol {Show VCS file status}.
 
-    \sa {Version Control Systems}
+    \sa {Use Git}{How To: Use Git}, {Version Control Systems}
 */

doc/qtcreator/src/vcs/creator-only/creator-vcs-subversion.qdoc

@@ -20,16 +20,16 @@
     Subversion is an open source version control system.
 
     In addition to the standard version control system functions described in
-    \l {Use common VCS Functions}, you can select \uicontrol Tools >
-    \uicontrol Subversion > \uicontrol Describe to display commit log messages
-    for a revision.
+    \l {Use common VCS Functions}, you can go to \uicontrol Tools >
+    \uicontrol Subversion and select \uicontrol Describe to display commit log
+    messages for a revision.
 
     You can use Git as a client for a Subversion server. For more information,
-    see \l{Using Git with Subversion}.
+    see \l{Use Git with Subversion}.
 
     \section1 Subversion Preferences
 
-    To set Subversion preferences, select \preferences >
+    To set Subversion preferences, go to \preferences >
     \uicontrol {Version Control} > \uicontrol Subversion:
 
    \image qtcreator-preferences-vcs-subversion.webp {Subversion preferences}

doc/qtcreator/src/vcs/creator-only/creator-vcs.qdoc

@@ -46,7 +46,7 @@
             \li Enable the plugin to use it.
              \row
             \li \l{Git}
-            \li \l{http://git-scm.com/}
+            \li \l{https://git-scm.com/}
             \li Git version 1.9.0, or later
 
                 Gerrit version 2.6, or later
@@ -71,7 +71,8 @@
     \endtable
 
     \sa {Create VCS repositories for new projects}, {Enable and disable plugins},
-    {Set up version control systems}, {Use common VCS functions}
+    {Use Git}{How To: Use Git}, {Set up version control systems},
+    {Use common VCS functions}
 */
 
 /*!
@@ -80,23 +81,30 @@
 
     \ingroup creator-how-to-projects-create
     \ingroup creator-how-to-projects-configure
+    \ingroup creator-how-to-git
 
     \title Create 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 create repositories for version control systems that
+    support local repository creation, such as Git, Mercurial, or Bazaar in
+    the following ways:
 
-    You can also select \uicontrol Tools and then select \uicontrol {Create Repository}
-    in the submenu for the version control system.
+    \list
+        \li To create a new project, go to \uicontrol File >
+            \uicontrol {New Project}, and select a version
+            control system on the last wizard page.
+        \li To place a project directory under version control, go to
+            \uicontrol Tools, and then select \uicontrol {Create Repository} in
+            the submenu for a version control system.
+        \li To import a project that is already under version control, go to
+            \uicontrol File > \uicontrol {New Project} >
+            \uicontrol {Project from Version Control} and select the version
+            control system that you use. Follow the instructions of the wizard
+            to import the project.
+    \endlist
 
-    To import a project that is under version control, choose \uicontrol File >
-    \uicontrol {New Project} > \uicontrol {Project from Version Control}
-    and select the version control system that you use. Follow the instructions
-    of the wizard to import the project.
-
-    \sa {Creating Projects}, {Use project wizards}, {Version Control Systems}
+    \sa {Use Git}{How To: Use Git}, {Use project wizards}, {Creating Projects},
+    {Git}, {Version Control Systems}
 */
 
 /*!
@@ -104,6 +112,7 @@
     \previouspage creator-how-tos.html
 
     \ingroup creator-how-to-use
+    \ingroup creator-how-to-git
 
     \title Use common VCS functions
 
@@ -136,15 +145,18 @@
     All version control systems have 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
+    read-only editor.
+
+    \image qtcreator-git-diff-repository.webp {Git Diff Repository view}
+    \caption Git Diff Repository view
+
+    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, Mercurial, and Subversion, the diff is displayed side-by-side in
     a \l{Compare files}{diff editor} by default. To use the inline diff view
-    instead, select the \uicontrol {Switch to Text Diff Editor} (1) option from
+    instead, select the \uicontrol {Unified Diff Editor} option from
     the toolbar. In the inline
     diff view, you can use context menu commands to apply, revert, stage, and
     unstage chunks or selected lines, as well as send chunks to a code pasting
@@ -160,7 +172,7 @@
 
     To open annotation views, select \uicontrol {Annotate} or \uicontrol {Blame}.
     They show the lines of the file and the identifier of the change the lines
-    originate from. Click the change identifier to see a detailed description of
+    originate from. Select the change identifier to see a detailed description of
     the change.
 
     To show the annotation of a previous version, right-click on the
@@ -204,5 +216,6 @@
 
     You can select \uicontrol Delete to delete obsolete files from the repository.
 
-    \sa {Set up version control systems}, {Version Control Systems}
+    \sa {Use Git}{How To: Use Git}, {Set up version control systems},
+    {Version Control Systems}
 */

doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc

@@ -242,6 +242,8 @@
             \list
                 \li \l{Finding the Qt Runtime Version}
                 \li \l{Using Git}
+                    \generatelist studio-how-to-git-gs
+                    \generatelist studio-how-to-git
                 \li \l{Converting Qt 5 Projects into Qt 6 Projects}
                 \li \l{Converting UI Projects to Applications}
                 \li \l{Use external tools}