feedc0de/qt-creator
1
0
Fork 0
forked from qt-creator/qt-creator
Code Pull Requests Activity

Doc: Update info about Git

Browse Source 
- 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>
This commit is contained in:
Leena Miettinen
2018-08-15 13:58:17 +02:00
parent 3286b6a36d
commit ee9745e3da
3 changed files with 271 additions and 186 deletions
Download Patch File Download Diff File Expand all files Collapse all files

218
doc/src/vcs/creator-vcs-git.qdoc
View File

@@ -42,12 +42,16 @@
\title Using Git \title Using Git
Git is a fast decentralized version control system. Git is available \l{http://git-scm.com/}{Git} is a fast decentralized version control system.
for Windows, Linux, and \macos. Git is available for Windows, Linux, and \macos.
You can use the \l{http://code.google.com/p/gerrit/}{Gerrit} code review You can use the \l{http://code.google.com/p/gerrit/}{Gerrit} code review
tool for projects that use Git. tool for projects that use Git.
\if defined(qtdesignstudio)
\include creator-vcs-options.qdocinc vcs options
\endif
\section1 Using Git for Windows \section1 Using Git for Windows
If you configure Git for use with \c {git bash}, only, and use SSH 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 set to \c %HOMEDRIVE%%HOMEPATH% when the Git executable is run and
authorization works as it would with \c {git bash}. authorization works as it would with \c {git bash}.
\section1 Reverting Changes Using Git
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.
\list
\li \uicontrol Git > \uicontrol {Current File} >
\uicontrol{Undo Unstaged Changes} reverts all changes and resets the
current file to the state of the index.
\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.
\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.
\endlist
\section1 Working with the Current File \section1 Working with the Current File
In addition to the standard version control system functions, you can To work with the current file, select the commands in \uicontrol Tools >
select \uicontrol Tools > \uicontrol Git > \uicontrol {Current File} > \uicontrol Git > \uicontrol {Current File}. Some of the commands are also
\uicontrol {Stage File for Commit} to mark a new or modified file for available for the project or local repository that contains the file.
committing to the repository.
To undo this function, select \uicontrol {Unstage File from Commit}. \section2 Viewing Git Diff
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.
\image qtcreator-vcs-diff.png
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.
\section2 Viewing Git Log
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.
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.
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 \section1 Working with the Current Project
In addition to the standard version control system functions, you can To work with the current project, select the commands in \uicontrol Tools >
select \uicontrol Tools > \uicontrol Git > \uicontrol {Current Project} > \uicontrol Git > \uicontrol {Current Project}. The \uicontrol {Diff Project}
\uicontrol {Clean Project} and \uicontrol {Log Project} commands, which are also available for the
to clean the working directory. All files that are not under version control current file, are described above.
are displayed in the \uicontrol {Clean Repository} dialog. Ignored files are
\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 deselected by default. Select the files to delete and click
\uicontrol Delete. \uicontrol Delete.
\section1 Working with Local Repositories \section1 Working with Local Repositories
In addition to the standard version control system functions, you can To work with the local repository, select the commands in \uicontrol Tools >
select \uicontrol Tools > \uicontrol Git > \uicontrol {Local Repository} > \uicontrol Git > \uicontrol {Local Repository}. The commands that are also
\uicontrol Clean to clean the repository. available for the current file or project are described above.
To apply latest changes to the last commit, select \uicontrol Tools > \section2 Viewing Reference Log
\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. \uicontrol {Amend Last Commit}. You can also edit the commit message.
To amend an earlier comment in a series of related commits, select 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 \uicontrol {Fixup Previous Commit}. This operation is done using interactive
rebase. In case of conflicts, a merge tool is suggested. rebase. In case of conflicts, a merge tool is suggested.
To recover removed files, select \uicontrol Tools > \uicontrol Git > \section2 Resetting Local Repository
\uicontrol {Recover Deleted Files}.
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 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 \uicontrol {Interactive Rebase}. You can reorder or discard commits, squash
them into a single commit, or edit the commit messages. 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 \section2 Working with Branches
To work with Git branches, select \uicontrol Tools > \uicontrol Git > To work with Git branches, select \uicontrol {Branches}. The checked out
\uicontrol {Local Repository} > \uicontrol {Branches}. The checked out
branch is shown in bold and underlined in the list of branches. Double-click branch is shown in bold and underlined in the list of branches. Double-click
branch names to edit them. branch names to edit them.
@@ -204,8 +281,7 @@
\section2 Applying Patches \section2 Applying Patches
Patches are rewriting instructions that can be applied to a set of files. 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 > To apply a patch file that is open in \QC, select \uicontrol Patch >
\uicontrol Git > \uicontrol {Local Repository} > \uicontrol Patch >
\uicontrol {Apply from Editor}. \uicontrol {Apply from Editor}.
To select the patch file to apply from the file system, select 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 changes to work on higher priority tasks or to pull in new chages from
another repository. another repository.
To stash all local changes, select \uicontrol Tools > \uicontrol Git > To stash all local changes, select \uicontrol Stash > \uicontrol Stash. The
\uicontrol {Local Repository} > \uicontrol Stash > \uicontrol Stash. The
working copy is reset to the state it had after the last commit. To save 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 current state of your unstaged files and reset the repository to its staged
state, select \uicontrol {Stash Unstaged Files}. state, select \uicontrol {Stash Unstaged Files}.
@@ -244,16 +319,31 @@
\image creator-git-commit-actions.png "Select a Git Commit dialog" \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 \section1 Working with Remote Repositories
In addition to the standard version control system functions, you can To work with remote repositories, select the commands in \uicontrol Tools >
select \uicontrol Tools > \uicontrol Git > \uicontrol {Remote Repository} > \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 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 Tools > \uicontrol Options > \uicontrol {Version Control} >
\uicontrol Git and then select the \uicontrol {Pull with rebase} check box \uicontrol Git and then select the \uicontrol {Pull with rebase} check box
to perform a rebase operation while pulling. to perform a rebase operation while pulling.
To push committed changes to the remote repository, select \uicontrol Push.
\section2 Managing Remote Repositories \section2 Managing Remote Repositories
To manage remote repositories available in Git, select \uicontrol Tools > To manage remote repositories available in Git, select \uicontrol Tools >

104
doc/src/vcs/creator-vcs-options.qdocinc Normal file
View File

@@ -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]
*/

135
doc/src/vcs/creator-vcs.qdoc
View File

@@ -78,89 +78,7 @@
\li Subversion version 1.7.0 and later \li Subversion version 1.7.0 and later
\endtable \endtable
\section1 Setting Up Version Control Systems \include creator-vcs-options.qdocinc vcs options
\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 \section1 Creating VCS Repositories for New Projects
@@ -183,7 +101,17 @@
control system. This section describes using the functions that are control system. This section describes using the functions that are
available for all the supported version control systems. For more available for all the supported version control systems. For more
information about the additional functions and options available for a 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 The \uicontrol{Version Control} output pane displays the commands that are
executed, a timestamp, and the relevant output. Select \uicontrol {Window > Output executed, a timestamp, and the relevant output. Select \uicontrol {Window > Output
@@ -200,9 +128,6 @@
for example, Perforce and Subversion. Alternatively, you can for example, Perforce and Subversion. Alternatively, you can
add files later by using the version control tool menus. 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 \section2 Viewing Diff Output
All version control systems provide menu options to \e{diff} the current 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} Display the versioning history of a file by selecting \uicontrol{Log}
or \uicontrol{Filelog}. Typically, the log output contains the date, the commit or \uicontrol{Filelog}. Typically, the log output contains the date, the commit
message, and a change or revision identifier. Click on the identifier to message, and a change or revision identifier.
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 \section2 Annotating Files
@@ -253,9 +167,6 @@
The same context menu is available when right-clicking on a version The same context menu is available when right-clicking on a version
identifier in the file log view of a single file. 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 \section2 Committing Changes
Once you have finished making changes, submit them to the version control 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 commit page containing a text editor where you can enter your commit
message and a checkable list of modified files to be included. 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 \section2 Reverting Changes
All supported version control systems support reverting your project to 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 A version control system can replace the \uicontrol Revert menu option with other
options. options.
For more information about reverting changes using Git, see
\l {Reverting Changes Using Git}.
\section2 Viewing Status \section2 Viewing Status
You can select \uicontrol{Status} to view the status of the project or 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 changes from the branch. Some version control systems allow you to choose
between updating the current project and updating all projects. 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 \section2 Deleting Files
You can select \uicontrol Delete to delete obsolete files from the repository. 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.
*/ */