Doc: Update info about Git

- Move all information about Git to the Git-specific topic
- Add missing information

Change-Id: I54bc19fd05ac100e8fbb03b3103754e8eb04fa01
Reviewed-by: Orgad Shaneh <orgads@gmail.com>
Reviewed-by: André Hartmann <aha_1980@gmx.de>

3 files changed, 265 insertions, 180 deletions

diff --git a/doc/src/vcs/creator-vcs-git.qdoc b/doc/src/vcs/creator-vcs-git.qdoc
index 1909b1ae43..fc1edbca7b 100644
--- a/doc/src/vcs/creator-vcs-git.qdoc
+++ b/doc/src/vcs/creator-vcs-git.qdoc
@@ -42,12 +42,16 @@
 
     \title Using Git
 
-    Git is a fast decentralized version control system. Git is available
-    for Windows, Linux, and \macos.
+    \l{http://git-scm.com/}{Git} is a fast decentralized version control system.
+    Git is available for Windows, Linux, and \macos.
 
     You can use the \l{http://code.google.com/p/gerrit/}{Gerrit} code review
     tool for projects that use Git.
 
+    \if defined(qtdesignstudio)
+    \include creator-vcs-options.qdocinc vcs options
+    \endif
+
     \section1 Using Git for Windows
 
     If you configure Git for use with \c {git bash}, only, and use SSH
@@ -65,85 +69,158 @@
     set to \c %HOMEDRIVE%%HOMEPATH% when the Git executable is run and
     authorization works as it would with \c {git bash}.
 
-    \section1 Reverting Changes Using Git
+    \section1 Working with the Current File
 
-    The Git version control system has an index that is used to stage
-    changes. The index is committed on the next commit. Git allows you to revert
-    back to the state of the last commit as well as to the state staged in the
-    index.
+    To work with the current file, select the commands in \uicontrol Tools >
+    \uicontrol Git > \uicontrol {Current File}. Some of the commands are also
+    available for the project or local repository that contains the file.
 
-    \list
+    \section2 Viewing Git Diff
 
-        \li \uicontrol Git > \uicontrol {Current File} >
-            \uicontrol{Undo Unstaged Changes} reverts all changes and resets the
-            current file to the state of the index.
+    You can \e{diff} the current file or project to compare it with the latest
+    version stored in the repository and to display the differences. To display
+    the diff in a read-only editor, select \uicontrol {Diff of}. 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.
 
-        \li \uicontrol Git > \uicontrol {Current File} >
-            \uicontrol {Undo Uncommitted Changes} reverts all changes,
-            discarding the index. This returns the current file to the state it
-            was in right after the last commit.
+    \image qtcreator-vcs-diff.png
 
-        \li \uicontrol Git > \uicontrol {Local Repository} > \uicontrol Reset
-            opens a dialog where you can select the SHA-1 to reset the working
-            directory to. This is useful after applying patches for review, for
-            example. You can choose between a \uicontrol Soft reset that does
-            not touch the index file nor the working tree at all, a
-            \uicontrol Hard reset that discards all changes to tracked files in
-            working tree, and a \uicontrol Mixed reset that resets HEAD and the
-            index (nothing remains staged) without touching the working
-            directory.
+    The diff is displayed side-by-side in a \l{Comparing Files}{diff editor}
+    by default. To use the unified diff view instead, select the
+    \uicontrol {Switch to Unified Diff Editor} (1) option from the toolbar.
+    In both views, you can use context menu commands to apply, revert, stage,
+    and unstage hunks, as well as send them to a code pasting service.
 
-    \endlist
+    \section2 Viewing Git Log
 
-    \section1 Working with the Current File
+    To display the versioning history of a file, select \uicontrol{Log of}.
+    The log output contains the date, the commit message, and a commit
+    identifier. Click on the commit 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 a commit identifier brings up a context menu that lets
+    you apply actions on the commit, such as view annotations or cherry-pick
+    or revert a commit.
+
+    Select \inlineimage reload_gray.png
+    (\uicontrol Reload) to rescan the files.
+
+    \section2 Viewing Annotations
+
+    To view annotations, select \uicontrol{Blame}. The view displays the lines
+    of the file prepended by the commit identifier they originate from. Clicking
+    on the commit identifier shows a detailed description of the change.
 
-    In addition to the standard version control system functions, you can
-    select \uicontrol Tools > \uicontrol Git > \uicontrol {Current File} >
-    \uicontrol {Stage File for Commit} to mark a new or modified file for
-    committing to the repository.
+    To show the annotation of a previous version, right-click on the commit
+    identifier and select \uicontrol {Blame Parent Revision}. This allows you
+    to navigate through the history of the file and obtain previous versions
+    of it.
 
-    To undo this function, select \uicontrol {Unstage File from Commit}.
+    The other actions in the context-menu enable you to apply actions to the
+    commit, such as cherry-pick, checkout, or revert it.
+
+    To rescan the files, click \inlineimage reload_gray.png
+    (\uicontrol Reload).
+
+    \section2 Staging Changes
+
+    To mark a new or modified file for committing it to the repository,
+    select \uicontrol {Stage File for Commit}. To undo this function,
+    select \uicontrol {Unstage File from Commit}.
+
+    \section2 Resetting Changes
+
+    Git has an index that is used to stage changes. The index is committed on
+    the next commit. Git allows you to revert back to the state of the last
+    commit as well as to the state staged in the index.
+
+    To revert all changes and reset the current file to the state of the index,
+    select \uicontrol{Undo Unstaged Changes}.
+
+    To return the current file to the state it was in right after the last
+    commit, select \uicontrol {Undo Uncommitted Changes}. This reverts all
+    changes, discarding the index.
 
     \section1 Working with the Current Project
 
-    In addition to the standard version control system functions, you can
-    select \uicontrol Tools > \uicontrol Git > \uicontrol {Current Project} >
-    \uicontrol {Clean Project}
-    to clean the working directory. All files that are not under version control
-    are displayed in the \uicontrol {Clean Repository} dialog. Ignored files are
+    To work with the current project, select the commands in \uicontrol Tools >
+    \uicontrol Git > \uicontrol {Current Project}. The \uicontrol {Diff Project}
+    and \uicontrol {Log Project} commands, which are also available for the
+    current file, are described above.
+
+    \section2 Cleaning Projects
+
+    To clean the working directory, select \uicontrol {Clean Project}.
+    All files that are not under version control are displayed in
+    the \uicontrol {Clean Repository} dialog. Ignored files are
     deselected by default. Select the files to delete and click
     \uicontrol Delete.
 
     \section1 Working with Local Repositories
 
-    In addition to the standard version control system functions, you can
-    select \uicontrol Tools > \uicontrol Git > \uicontrol {Local Repository} >
-    \uicontrol Clean to clean the repository.
+    To work with the local repository, select the commands in \uicontrol Tools >
+    \uicontrol Git > \uicontrol {Local Repository}. The commands that are also
+    available for the current file or project are described above.
+
+    \section2 Viewing Reference Log
 
-    To apply latest changes to the last commit, select \uicontrol Tools >
-    \uicontrol Git > \uicontrol {Local Repository} >
+    Reference logs record when the tips of branches and other references were
+    updated in the local repository. To view the reference log, select
+    \uicontrol Reflog.
+
+    \section2 Viewing Git Status
+
+    To view the status of the repository in the \uicontrol {Version Control}
+    output view, select \uicontrol Status.
+
+    \section2 Committing Changes to Git
+
+    To submit your changes to Git, select \uicontrol Commit. \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 Amending Commits
+
+    To apply latest changes to the last commit, select
     \uicontrol {Amend Last Commit}. You can also edit the commit message.
 
     To amend an earlier comment in a series of related commits, select
-    \uicontrol Tools > \uicontrol Git > \uicontrol {Local Repository} >
     \uicontrol {Fixup Previous Commit}. This operation is done using interactive
     rebase. In case of conflicts, a merge tool is suggested.
 
-    To recover removed files, select \uicontrol Tools > \uicontrol Git >
-    \uicontrol {Recover Deleted Files}.
+    \section2 Resetting Local Repository
+
+    To reset changes, select \uicontrol Reset. This opens a dialog where you
+    can select the commit to reset the working directory to. This is useful
+    after applying patches for review, for example. You can choose between a
+    \uicontrol Soft reset that does not touch the index file nor the working
+    tree at all, a \uicontrol Hard reset that discards all changes to tracked
+    files in the working tree, and a \uicontrol Mixed reset that resets HEAD
+    and the index (nothing remains staged) without touching the working
+    directory.
+
+    To recover removed files, select \uicontrol {Recover Deleted Files}.
 
     To change a series of commits in the local repository, select
-    \uicontrol Tools > \uicontrol Git > \uicontrol {Local Repository} >
     \uicontrol {Interactive Rebase}. You can reorder or discard commits, squash
     them into a single commit, or edit the commit messages.
 
-    The following sections describe how to manage local and remote branches,
-    apply patches, and use stashes.
-
     \section2 Working with Branches
 
-    To work with Git branches, select \uicontrol Tools > \uicontrol Git >
-    \uicontrol {Local Repository} > \uicontrol {Branches}. The checked out
+    To work with Git branches, select \uicontrol {Branches}. The checked out
     branch is shown in bold and underlined in the list of branches. Double-click
     branch names to edit them.
 
@@ -204,8 +281,7 @@
     \section2 Applying Patches
 
     Patches are rewriting instructions that can be applied to a set of files.
-    To apply a patch file that is open in \QC, select \uicontrol Tools >
-    \uicontrol Git > \uicontrol {Local Repository} > \uicontrol Patch >
+    To apply a patch file that is open in \QC, select \uicontrol Patch >
     \uicontrol {Apply from Editor}.
 
     To select the patch file to apply from the file system, select
@@ -218,8 +294,7 @@
     changes to work on higher priority tasks or to pull in new chages from
     another repository.
 
-    To stash all local changes, select \uicontrol Tools > \uicontrol Git >
-    \uicontrol {Local Repository} > \uicontrol Stash > \uicontrol Stash. The
+    To stash all local changes, select \uicontrol Stash > \uicontrol Stash. The
     working copy is reset to the state it had after the last commit. To save the
     current state of your unstaged files and reset the repository to its staged
     state, select \uicontrol {Stash Unstaged Files}.
@@ -244,16 +319,31 @@
 
     \image creator-git-commit-actions.png "Select a Git Commit dialog"
 
+    \section1 Initializing Git Repositories
+
+    To start controlling a project directory that is currently not under
+    version control, select \uicontrol Tools > \uicontrol Git >
+    \uicontrol {Create Repository}. \QC creates a new subdirectory named .git
+    that contains all the necessary repository files. However, nothing in the
+    project is tracked yet, so you will need to create an initial commit to
+    start tracking the project files.
+
     \section1 Working with Remote Repositories
 
-    In addition to the standard version control system functions, you can
-    select \uicontrol Tools > \uicontrol Git > \uicontrol {Remote Repository} >
-    \uicontrol Pull topull changes from the remote repository. If there are
-    locally modified files, you are prompted to stash the changes. Select
+    To work with remote repositories, select the commands in \uicontrol Tools >
+    \uicontrol Git > \uicontrol {Remote Repository}.
+
+    To fetch all the branches and change information from a remote repository,
+    select \uicontrol Fetch.
+
+    To pull changes from the remote repository, select \uicontrol Pull. If there
+    are locally modified files, you are prompted to stash the changes. Select
     \uicontrol Tools > \uicontrol Options > \uicontrol {Version Control} >
     \uicontrol Git and then select the \uicontrol {Pull with rebase} check box
     to perform a rebase operation while pulling.
 
+    To push committed changes to the remote repository, select \uicontrol Push.
+
     \section2 Managing Remote Repositories
 
     To manage remote repositories available in Git, select \uicontrol Tools >
diff --git a/doc/src/vcs/creator-vcs-options.qdocinc b/doc/src/vcs/creator-vcs-options.qdocinc
new file mode 100644
index 0000000000..47727d22e4
--- /dev/null
+++ b/doc/src/vcs/creator-vcs-options.qdocinc
@@ -0,0 +1,104 @@
+/****************************************************************************
+**
+** 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.
+**
+****************************************************************************/
+
+/*!
+
+//! [vcs options]
+
+    \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
+
+//! [vcs options]
+*/
diff --git a/doc/src/vcs/creator-vcs.qdoc b/doc/src/vcs/creator-vcs.qdoc
index fb868945a3..9a87e53f89 100644
--- a/doc/src/vcs/creator-vcs.qdoc
+++ b/doc/src/vcs/creator-vcs.qdoc
@@ -78,89 +78,7 @@
             \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
+    \include creator-vcs-options.qdocinc vcs options
 
     \section1 Creating VCS Repositories for New Projects
 
@@ -183,7 +101,17 @@
     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.
+    particular version control system, see:
+
+    \list
+        \li \l{Using Bazaar}
+        \li \l{Using ClearCase}
+        \li \l{Using CVS}
+        \li \l{Using Git}
+        \li \l{Using Mercurial}
+        \li \l{Using Perforce}
+        \li \l{Using Subversion}
+    \endlist
 
     The \uicontrol{Version Control} output pane displays the commands that are
     executed, a timestamp, and the relevant output. Select \uicontrol {Window > Output
@@ -200,9 +128,6 @@
     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
@@ -224,18 +149,7 @@
 
     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.
+    message, and a change or revision identifier.
 
     \section2 Annotating Files
 
@@ -253,9 +167,6 @@
     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
@@ -263,17 +174,6 @@
     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
@@ -284,9 +184,6 @@
     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
@@ -298,13 +195,7 @@
     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.
 */