diff --git a/doc/src/howto/creator-vcs.qdoc b/doc/src/howto/creator-vcs.qdoc deleted file mode 100644 index 78830adc94e..00000000000 --- a/doc/src/howto/creator-vcs.qdoc +++ /dev/null @@ -1,773 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2016 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 {Qt Creator Manual} - \previouspage creator-project-wizards-xml.html - \page creator-version-control.html - \nextpage creator-configuring-projects.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 Bazaar - \li \l{http://bazaar.canonical.com/} - \li - \row - \li ClearCase - \li \l{http://www-01.ibm.com/software/awdtools/clearcase/} - \li - \row - \li CVS - \li \l{http://www.cvshome.org} - \li - \row - \li Git - \li \l{http://git-scm.com/} - \li Git version 1.8.0, or later - - Gerrit version 2.6, or later - \row - \li Mercurial - \li \l{http://mercurial.selenic.com/} - \li - \row - \li Perforce - \li \l{http://www.perforce.com} - \li Server version 2006.1 and later - \row - \li 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 or specify the path to - the command line client executables in \uicontrol{Tools} > \uicontrol{Options} > - \uicontrol {Version Control}. - - 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. - - \section2 Using msysGit on 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. Select \uicontrol {Tools > - Options > Version Control > Git}. Select the \uicontrol {Environment Variables} - and the \uicontrol {Set "HOME" environment variable} check boxes. \c HOME is set - to \c %HOMEDRIVE%%HOMEPATH% when the Git executable is run and authorization - works as it would with \c {git bash}. - - \section1 Setting Up General Options - - Select \uicontrol{Tools} > \uicontrol{Options} > \uicontrol{Version Control} - > \uicontrol{General} - to specify settings for submit messages: - - \list - - \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 jdoe - Hans Mustermann hm - \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 {Patch command} specifies the path to the patch utility that is - used to apply changes in the format used to represent the diff - output. The \uicontrol Revert command uses the patch utility to revert - partial changes. - - \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 Version Control Systems - - The \uicontrol{Tools} menu contains a submenu for each supported version - control system. - - 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. - - \section3 Using GNU Diffutils with ClearCase - - You can use the GNU Diffutils tool With ClearCase to compare files and - activities: - - \list 1 - - \li Download \l{http://gnuwin32.sourceforge.net/packages/diffutils.htm} - {Diffutils} and extract it to a directory in your PATH. - - \li Select \uicontrol Tools > \uicontrol Options > - \uicontrol {Version Control} > \uicontrol ClearCase. - - \li Select the \uicontrol External radio button. The radio button is - disabled if \c diff is not found in the PATH. - - \li In the \uicontrol Arguments field, specify arguments for running - \c diff. - - \endlist - - \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. - - \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. - - \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. - - \section3 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 - - \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. - - \section2 Using Additional Bazaar Functions - - Bazaar is a free version control system sponsored by Canonical. - - The \uicontrol Bazaar submenu contains the following additional items: - - \table - \header - \li Menu Item - \li Description - \row - \li \uicontrol Pull - \li Turn the branch into a mirror of another branch. - \row - \li \uicontrol Push - \li Update a mirror of the branch. - \row - \li \uicontrol Uncommit - \li Remove the last committed revision. - \endtable - - \section3 Uncommitting Revisions - - In Bazaar, committing changes to a branch creates a new revision that holds - a snapshot of the state of the working tree. To remove the last committed - revision, select \uicontrol Tools > \uicontrol Bazaar > \uicontrol Uncommit. - - In the \uicontrol Uncommit dialog, select options to keep tags that point to - removed revisions and to only remove the commits from the local branch when - in a checkout. - - To remove all commits up to an entry in the revision log, specify the - revision in the \uicontrol Revision field. - - To test the outcome of the \uicontrol Uncommit command without actually removing - anything, select \uicontrol {Dry Run}. - - \uicontrol Uncommit leaves the working tree ready for a new commit. The only - change it might make is restoring pending merges that were present before - the commit. - - \section2 Using Additional ClearCase Functions - - IBM Rational ClearCase is a version control, workspace management, parallel - development support, and build automation solution developed by IBM. The - ClearCase client plugin is available on Linux and Windows for accessing a - ClearCase server. - - The \uicontrol ClearCase submenu contains the following additional items: - - \table - \header - \li Menu Item - \li Description - \row - \li \uicontrol{Check In} - \li Create a permanent new version of the current file or all files - in the versioned object base (VOB). - \row - \li \uicontrol{Check In Activity} - \li Check in checked-out versions in the change set of the current - Unified Change Management (UCM) activity. - \row - \li \uicontrol{Check Out} - \li Create a writable copy of a branch. If you check out files in a - UCM view, they are added to the change set of the UCM activity. - \row - \li \uicontrol{Undo Check Out} - \li Cancel the checkout for a file and delete the checked-out - version. - \row - \li \uicontrol{Undo Hijack} - \li Resolve hijacked files. If you change the read-only attribute of - a file that is loaded into a snapshot view and modify the file - without checking it out, you \e hijack the file. - \endtable - -\section2 Using Additional CVS Functions - - CVS is an open source version control system. - - In addition to the standard version control system functions, you can - select \uicontrol Tools > \uicontrol CVS > \uicontrol Edit to open a file for editing. - To discard the changes that you made in a file, select \uicontrol Unedit. - - \section2 Using Additional Git Functions - - Git is a fast decentralized version control system. Git is available - for Windows, Linux and Mac. - - You can use the \l{http://code.google.com/p/gerrit/}{Gerrit} code review - tool for projects that use Git. - - \section3 Working with the Current File - - 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 undo this function, select \uicontrol {Unstage File from Commit}. - - \section3 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 - deselected by default. Select the files to delete and click \uicontrol Delete. - - \section3 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 apply latest changes to the last commit, select \uicontrol Tools > \uicontrol Git > - \uicontrol {Local Repository} > \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 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. - - \section4 Working with Branches - - To work with Git branches, select \uicontrol Tools > \uicontrol Git > - \uicontrol {Local Repository} > \uicontrol {Branches}. The checked out branch - is shown in bold and underlined in the list of branches. Double-click branch - names to edit them. - - \image qtcreator-vcs-gitbranch.png "Branches dialog" - - The following operations are supported: - - \table - \header - \li Menu Item - \li Description - \row - \li \uicontrol{Refresh} - \li Refresh the list of branches. - \row - \li \uicontrol{Add} - \li Create new tracking and non-tracking branches. - \row - \li \uicontrol{Remove} - \li Remove a local branch. You cannot delete remote branches. - \row - \li \uicontrol Rename - \li Rename a local branch. - \row - \li \uicontrol{Checkout} - \li Check out the selected branch and make it current. You can stash - changes you have made to tracked files. - \row - \li \uicontrol{Diff} - \li Show the differences between the selected and the current - branch. - \row - \li \uicontrol{Log} - \li Show the changes in a branch. - \row - \li \uicontrol Merge - \li Join the development histories in two branches together. - - If the commit you are merging can be reached by following the - first commit's history, there is no divergent work to merge - together. To allow Git to move the branch pointer forward, - select \uicontrol {Fast-Forward}. If you do not want to fast-forward - the branch, select \uicontrol {No Fast-Forward}. - \row - \li \uicontrol Rebase - \li Copy local commits to the updated upstream head. - \row - \li \uicontrol Reset - \li Hard reset the active branch to the selected branch. - \row - \li \uicontrol {Cherry Pick} - \li Cherry pick the top commit from the selected branch. - \row - \li \uicontrol Track - \li Set the current branch to track the selected one. - \endtable - - \section4 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 > - \uicontrol {Apply from Editor}. - - To select the patch file to apply from the file system, select - \uicontrol {Apply from File}. - - \section4 Using Stashes - - With Git, you can put your current set of changes onto a virtual shelf - called a \e stash. Stashes are useful, for example, to put aside a set of - 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 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}. - - To display a dialog that shows all known stashes with options to restore, - display or delete them, select \uicontrol Stashes. - - To save a snapshot of your current work under a name for later reference, - select \uicontrol {Take Snapshot}. The working copy is unchanged. For example, if - you want to try something and find out later that it does not work, you can - discard the changes and return to the state of the snapshot. - - To remove a single stashed state from the stash list and apply it on top of - the current working tree state, select \uicontrol {Stash Pop}. - - \section3 Applying Actions to Commits - - To browse a directory or the commit history and to apply actions on the - commits, select \uicontrol Tools > \uicontrol Git > \uicontrol {Actions on Commits}. You can - checkout, revert, or cherry-pick commits or view them in the diff editor. - - \image creator-git-commit-actions.png "Select a Git Commit dialog" - - \section3 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 to - pull changes from the remote repository. 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. - - \section4 Managing Remote Repositories - - To manage remote repositories available in Git, select \uicontrol Tools > \uicontrol Git - > \uicontrol {Remote Repository} > \uicontrol{Manage Remotes}. Double-click the names - and URLs of the remote repositories to edit them. - - The following operations are supported: - - \table - \header - \li Menu Item - \li Description - \row - \li \uicontrol{Refresh} - \li Refresh the list of remote repositories. - \row - \li \uicontrol{Add} - \li Add a new remote repository. - \row - \li \uicontrol{Fetch} - \li Fetch all the branches and change information from a remote - repository. - \row - \li \uicontrol Push - \li Push committed changes to the remote repository. - \row - \li \uicontrol{Remove} - \li Remove a remote repository. - - \endtable - - \section4 Using Git with Subversion - - You can use Git as a client for a Subversion server. To fetch changes from a - Subversion repository to a Git repository, select \uicontrol Tools > \uicontrol Git > - \uicontrol {Remote Repository} > \uicontrol Subversion > \uicontrol Fetch. - - To view the Git Subversion log, select \uicontrol Log. - - \section4 Reviewing Code with Gerrit - - If your Git project uses Gerrit for code reviews, you can view your changes - in \QC. - - Select \uicontrol Tools > \uicontrol Options > \uicontrol {Version Control} - > \uicontrol Gerrit to - specify the connection to the Gerrit server. - - \image qtcreator-gerrit-options.png - - To push committed changes to Gerrit, select \uicontrol Tools > \uicontrol Git > - \uicontrol {Remote Repository} > \uicontrol {Push to Gerrit}. - - To view the same information about each change as in the Gerrit - web interface, select \uicontrol Tools > \uicontrol Git > \uicontrol {Remote Repository} > - \uicontrol Gerrit. - - \image qtcreator-gerrit.png - - To view details of the selected change, select \uicontrol Show. - - To cherry-pick the selected change to the local repository, select - \uicontrol {Cherry Pick}. To remove the change after testing it, select \uicontrol Tools > - \uicontrol Git > \uicontrol {Local Repository} > \uicontrol Reset. In the - \uicontrol {Undo Changes to} dialog, select the - state to reset the working directory to, and then select \uicontrol OK. - - To check out the change in a headless state, select \uicontrol Checkout. - - To refresh the list of changes, select \uicontrol Refresh. - - \section3 Working with Git Tools - - To start a graphical interface to Git, select \uicontrol Tools > \uicontrol Git > - \uicontrol {Git Tools} > \uicontrol {Git Gui}. - - \note On \macos, the default Git installation does not contain Git Gui. To - use Git Gui, install it separately. To start Git Gui from \QC, select - \uicontrol Preferences > \uicontrol {Version Control} > \uicontrol Git, and set the path to - the environment that contains Git Gui in the \uicontrol {Prepend to PATH} field. - - To start the commit viewer for Git, select \uicontrol Tools > \uicontrol Git > - \uicontrol {Git Tools} > \uicontrol Gitk. You can also start the tool to view commits in - the current document or in the folder that contains the current document. - To specify arguments for running Gitk, select \uicontrol Tools > \uicontrol Options > - \uicontrol {Version Control} > \uicontrol Git. - - To use some other application for viewing Git history, such as GitX or - QGit viewer, select \uicontrol Tools > \uicontrol Options > \uicontrol {Version Control} > - \uicontrol Git and specify the path to the application executable in the - \uicontrol {Command} field. To start the application, select \uicontrol Tools > \uicontrol Git - > \uicontrol {Git Tools} > \uicontrol {Repository Browser}. - - To resolve merge conflicts, select \uicontrol Tools > \uicontrol Git > \uicontrol {Git Tools} - > \uicontrol {Merge Tool}. - - \section2 Using Additional Mercurial Functionality - - Mercurial is a free, distributed source control management tool. - - The \uicontrol Mercurial submenu contains the following additional items: - - \table - \header - \li Menu Item - \li Description - \row - \li \uicontrol{Import} - \li Apply changes from a patch file. - \row - \li \uicontrol{Incoming} - \li Monitor the status of a remote repository by listing - the changes that will be pulled. - \row - \li \uicontrol{Outgoing} - \li Monitor the status of a remote repository by listing - the changes that will be pushed. - \row - \li \uicontrol{Pull} - \li Pull changes from the remote repository. - \row - \li \uicontrol{Push} - \li Push changes to the remote repository. - \endtable - - \section2 Using Additional Perforce Functions - - Perforce is a fast software configuration management system developed by - Perforce Software. - - When you start \QC, it looks for the executable specified - in the \uicontrol{P4 command} field in \uicontrol{Tools > Options > Version - Control > Perforce}. If the file is not found, the following error - message is displayed in the \uicontrol {Version Control} output pane: - \uicontrol {Perforce: Unable to determine the repository: "p4.exe" - terminated with exit code 1}. If you use Perforce, check that the - path to the executable is specified correctly in the \uicontrol{P4 command} - field. - - If you do not use Perforce, you can disable the Perforce plugin to - get rid of the error message. Choose \uicontrol {Help > About Plugins} and - deselect the \uicontrol Load check box for the \uicontrol Perforce plugin in the - \uicontrol {Version Control} group. - - In the Perforce options, you can specify workspace details: - \uicontrol {P4 user}, \uicontrol {P4 client}, and \uicontrol {P4 port}. To - specify the details individually for several projects, use configuration - files instead. Create a \c {p4config.txt} configuration file for each - project in the top level project directory. - - The \uicontrol Perforce submenu contains the following additional items: - - \table - \header - \li Menu Item - \li Description - \row - \li \uicontrol{Describe} - \li View information about changelists and the files in them. - \row - \li \uicontrol{Edit File} - \li Open a file for editing. - \row - \li \uicontrol{Opened} - \li List files that are open for editing. - \row - \li \uicontrol{Pending Changes} - \li Group files for commit. - \endtable - - \section2 Using Additional Subversion Functions - - Subversion is an open source version control system. - - In addition to the standard version control system functions, you can - select \uicontrol Tools > \uicontrol Subversion > \uicontrol Describe to display commit log - messages for a revision. - -*/ diff --git a/doc/src/qtcreator.qdoc b/doc/src/qtcreator.qdoc index 20d07b2b6b3..ac072b238ee 100644 --- a/doc/src/qtcreator.qdoc +++ b/doc/src/qtcreator.qdoc @@ -164,6 +164,15 @@ \endlist \endlist \li \l{Using Version Control Systems} + \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 \li \l{Configuring Projects} \list \li \l{Adding Kits} diff --git a/doc/src/vcs/creator-vcs-bazaar.qdoc b/doc/src/vcs/creator-vcs-bazaar.qdoc new file mode 100644 index 00000000000..976d4ceb152 --- /dev/null +++ b/doc/src/vcs/creator-vcs-bazaar.qdoc @@ -0,0 +1,78 @@ +/**************************************************************************** +** +** Copyright (C) 2016 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 {Qt Creator Manual} + \previouspage creator-version-control.html + \page creator-vcs-bazaar.html + \nextpage creator-vcs-clearcase.html + + \title Using Bazaar + + Bazaar is a free version control system sponsored by Canonical. + + The \uicontrol Bazaar submenu contains the following additional items: + + \table + \header + \li Menu Item + \li Description + \row + \li \uicontrol Pull + \li Turn the branch into a mirror of another branch. + \row + \li \uicontrol Push + \li Update a mirror of the branch. + \row + \li \uicontrol Uncommit + \li Remove the last committed revision. + \endtable + + \section1 Uncommitting Revisions + + In Bazaar, committing changes to a branch creates a new revision that holds + a snapshot of the state of the working tree. To remove the last committed + revision, select \uicontrol Tools > \uicontrol Bazaar > \uicontrol Uncommit. + + In the \uicontrol Uncommit dialog, select options to keep tags that point to + removed revisions and to only remove the commits from the local branch when + in a checkout. + + To remove all commits up to an entry in the revision log, specify the + revision in the \uicontrol Revision field. + + To test the outcome of the \uicontrol Uncommit command without actually + removing anything, select \uicontrol {Dry Run}. + + \uicontrol Uncommit leaves the working tree ready for a new commit. The only + change it might make is restoring pending merges that were present before + the commit. +*/ diff --git a/doc/src/vcs/creator-vcs-clearcase.qdoc b/doc/src/vcs/creator-vcs-clearcase.qdoc new file mode 100644 index 00000000000..5a155c5ba32 --- /dev/null +++ b/doc/src/vcs/creator-vcs-clearcase.qdoc @@ -0,0 +1,96 @@ +/**************************************************************************** +** +** Copyright (C) 2016 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 {Qt Creator Manual} + \previouspage creator-vcs-bazaar.html + \page creator-vcs-clearcase.html + \nextpage creator-vcs-cvs.html + + \title Using ClearCase + + IBM Rational ClearCase is a version control, workspace management, parallel + development support, and build automation solution developed by IBM. The + ClearCase client plugin is available on Linux and Windows for accessing a + ClearCase server. + + \section1 Using GNU Diffutils with ClearCase + + You can use the GNU Diffutils tool With ClearCase to compare files and + activities: + + \list 1 + + \li Download \l{http://gnuwin32.sourceforge.net/packages/diffutils.htm} + {Diffutils} and extract it to a directory in your PATH. + + \li Select \uicontrol Tools > \uicontrol Options > + \uicontrol {Version Control} > \uicontrol ClearCase. + + \li Select the \uicontrol External radio button. The radio button is + disabled if \c diff is not found in the PATH. + + \li In the \uicontrol Arguments field, specify arguments for running + \c diff. + + \endlist + + \section1 Using Additional ClearCase Functions + + The \uicontrol ClearCase submenu contains the following additional items: + + \table + \header + \li Menu Item + \li Description + \row + \li \uicontrol{Check In} + \li Create a permanent new version of the current file or all files + in the versioned object base (VOB). + \row + \li \uicontrol{Check In Activity} + \li Check in checked-out versions in the change set of the current + Unified Change Management (UCM) activity. + \row + \li \uicontrol{Check Out} + \li Create a writable copy of a branch. If you check out files in a + UCM view, they are added to the change set of the UCM activity. + \row + \li \uicontrol{Undo Check Out} + \li Cancel the checkout for a file and delete the checked-out + version. + \row + \li \uicontrol{Undo Hijack} + \li Resolve hijacked files. If you change the read-only attribute of + a file that is loaded into a snapshot view and modify the file + without checking it out, you \e hijack the file. + \endtable +*/ diff --git a/doc/src/vcs/creator-vcs-cvs.qdoc b/doc/src/vcs/creator-vcs-cvs.qdoc new file mode 100644 index 00000000000..d8bb0e27e62 --- /dev/null +++ b/doc/src/vcs/creator-vcs-cvs.qdoc @@ -0,0 +1,47 @@ +/**************************************************************************** +** +** Copyright (C) 2016 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 {Qt Creator Manual} + \previouspage creator-vcs-clearcase.html + \page creator-vcs-cvs.html + \nextpage creator-vcs-git.html + + \title Using CVS + + CVS is an open source version control system. + + In addition to the standard version control system functions, you can + select \uicontrol Tools > \uicontrol CVS > \uicontrol Edit to open a file + for editing. + + To discard the changes that you made in a file, select \uicontrol Unedit. +*/ diff --git a/doc/src/vcs/creator-vcs-git.qdoc b/doc/src/vcs/creator-vcs-git.qdoc new file mode 100644 index 00000000000..8042f863bf1 --- /dev/null +++ b/doc/src/vcs/creator-vcs-git.qdoc @@ -0,0 +1,349 @@ +/**************************************************************************** +** +** Copyright (C) 2016 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 {Qt Creator Manual} + \previouspage creator-vcs-cvs.html + \page creator-vcs-git.html + \nextpage creator-vcs-mercurial.html + + \title Using Git + + Git is a fast decentralized version control system. Git is available + for Windows, Linux and Mac. + + You can use the \l{http://code.google.com/p/gerrit/}{Gerrit} code review + tool for projects that use Git. + + \section1 Using msysGit on 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. Select + \uicontrol Tools > \uicontrol Options > \uicontrol {Version Control} > + \uicontrol Git. Select the \uicontrol {Environment Variables} + and the \uicontrol {Set "HOME" environment variable} check boxes. \c HOME is + 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 + + 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 + + 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 undo this function, select \uicontrol {Unstage File from Commit}. + + \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 + 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 apply latest changes to the last commit, select \uicontrol Tools > + \uicontrol Git > \uicontrol {Local Repository} > + \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 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 + branch is shown in bold and underlined in the list of branches. Double-click + branch names to edit them. + + \image qtcreator-vcs-gitbranch.png "Branches dialog" + + The following operations are supported: + + \table + \header + \li Menu Item + \li Description + \row + \li \uicontrol{Refresh} + \li Refresh the list of branches. + \row + \li \uicontrol{Add} + \li Create new tracking and non-tracking branches. + \row + \li \uicontrol{Remove} + \li Remove a local branch. You cannot delete remote branches. + \row + \li \uicontrol Rename + \li Rename a local branch. + \row + \li \uicontrol{Checkout} + \li Check out the selected branch and make it current. You can stash + changes you have made to tracked files. + \row + \li \uicontrol{Diff} + \li Show the differences between the selected and the current + branch. + \row + \li \uicontrol{Log} + \li Show the changes in a branch. + \row + \li \uicontrol Merge + \li Join the development histories in two branches together. + + If the commit you are merging can be reached by following the + first commit's history, there is no divergent work to merge + together. To allow Git to move the branch pointer forward, + select \uicontrol {Fast-Forward}. If you do not want to + fast-forward the branch, select \uicontrol {No Fast-Forward}. + \row + \li \uicontrol Rebase + \li Copy local commits to the updated upstream head. + \row + \li \uicontrol Reset + \li Hard reset the active branch to the selected branch. + \row + \li \uicontrol {Cherry Pick} + \li Cherry pick the top commit from the selected branch. + \row + \li \uicontrol Track + \li Set the current branch to track the selected one. + \endtable + + \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 > + \uicontrol {Apply from Editor}. + + To select the patch file to apply from the file system, select + \uicontrol {Apply from File}. + + \section2 Using Stashes + + With Git, you can put your current set of changes onto a virtual shelf + called a \e stash. Stashes are useful, for example, to put aside a set of + 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 + 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}. + + To display a dialog that shows all known stashes with options to restore, + display or delete them, select \uicontrol Stashes. + + To save a snapshot of your current work under a name for later reference, + select \uicontrol {Take Snapshot}. The working copy is unchanged. For + example, if you want to try something and find out later that it does not + work, you can discard the changes and return to the state of the snapshot. + + To remove a single stashed state from the stash list and apply it on top of + the current working tree state, select \uicontrol {Stash Pop}. + + \section1 Applying Actions to Commits + + To browse a directory or the commit history and to apply actions on the + commits, select \uicontrol Tools > \uicontrol Git > + \uicontrol {Actions on Commits}. You can checkout, revert, or cherry-pick + commits or view them in the diff editor. + + \image creator-git-commit-actions.png "Select a Git Commit dialog" + + \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 + \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. + + \section2 Managing Remote Repositories + + To manage remote repositories available in Git, select \uicontrol Tools > + \uicontrol Git > \uicontrol {Remote Repository} > + \uicontrol{Manage Remotes}. Double-click the names and URLs of the remote + repositories to edit them. + + The following operations are supported: + + \table + \header + \li Menu Item + \li Description + \row + \li \uicontrol{Refresh} + \li Refresh the list of remote repositories. + \row + \li \uicontrol{Add} + \li Add a new remote repository. + \row + \li \uicontrol{Fetch} + \li Fetch all the branches and change information from a remote + repository. + \row + \li \uicontrol Push + \li Push committed changes to the remote repository. + \row + \li \uicontrol{Remove} + \li Remove a remote repository. + + \endtable + + \section2 Using Git with Subversion + + You can use Git as a client for a Subversion server. To fetch changes from a + Subversion repository to a Git repository, select \uicontrol Tools > + \uicontrol Git > \uicontrol {Remote Repository} > \uicontrol Subversion > + \uicontrol Fetch. + + To view the Git Subversion log, select \uicontrol Log. + + \section2 Reviewing Code with Gerrit + + If your Git project uses Gerrit for code reviews, you can view your changes + in \QC. + + Select \uicontrol Tools > \uicontrol Options > \uicontrol {Version Control} + > \uicontrol Gerrit to specify the connection to the Gerrit server. + + \image qtcreator-gerrit-options.png + + To push committed changes to Gerrit, select \uicontrol Tools > + \uicontrol Git > \uicontrol {Remote Repository} > + \uicontrol {Push to Gerrit}. + + To view the same information about each change as in the Gerrit + web interface, select \uicontrol Tools > \uicontrol Git > + \uicontrol {Remote Repository} > \uicontrol Gerrit. + + \image qtcreator-gerrit.png + + To view details of the selected change, select \uicontrol Show. + + To cherry-pick the selected change to the local repository, select + \uicontrol {Cherry Pick}. To remove the change after testing it, select + \uicontrol Tools > \uicontrol Git > \uicontrol {Local Repository} > + \uicontrol Reset. In the \uicontrol {Undo Changes to} dialog, select the + state to reset the working directory to, and then select \uicontrol OK. + + To check out the change in a headless state, select \uicontrol Checkout. + + To refresh the list of changes, select \uicontrol Refresh. + + \section1 Working with Git Tools + + To start a graphical interface to Git, select \uicontrol Tools > + \uicontrol Git > \uicontrol {Git Tools} > \uicontrol {Git Gui}. + + \note On \macos, the default Git installation does not contain Git Gui. To + use Git Gui, install it separately. To start Git Gui from \QC, select + \uicontrol Preferences > \uicontrol {Version Control} > \uicontrol Git, and + set the path to the environment that contains Git Gui in the + \uicontrol {Prepend to PATH} field. + + To start the commit viewer for Git, select \uicontrol Tools > + \uicontrol Git > \uicontrol {Git Tools} > \uicontrol Gitk. You can also + start the tool to view commits in the current document or in the folder that + contains the current document. To specify arguments for running Gitk, select + \uicontrol Tools > \uicontrol Options > \uicontrol {Version Control} > + \uicontrol Git. + + To use some other application for viewing Git history, such as GitX or + QGit viewer, select \uicontrol Tools > \uicontrol Options > + \uicontrol {Version Control} > \uicontrol Git and specify the path to the + application executable in the \uicontrol {Command} field. To start the + application, select \uicontrol Tools > \uicontrol Git + > \uicontrol {Git Tools} > \uicontrol {Repository Browser}. + + To resolve merge conflicts, select \uicontrol Tools > \uicontrol Git > + \uicontrol {Git Tools} > \uicontrol {Merge Tool}. +*/ diff --git a/doc/src/vcs/creator-vcs-mercurial.qdoc b/doc/src/vcs/creator-vcs-mercurial.qdoc new file mode 100644 index 00000000000..0f97ecf9911 --- /dev/null +++ b/doc/src/vcs/creator-vcs-mercurial.qdoc @@ -0,0 +1,66 @@ +/**************************************************************************** +** +** Copyright (C) 2016 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 {Qt Creator Manual} + \previouspage creator-vcs-git.html + \page creator-vcs-mercurial.html + \nextpage creator-vcs-perforce.html + + \title Using Mercurial + + Mercurial is a free, distributed source control management tool. + + The \uicontrol Mercurial submenu contains the following additional items: + + \table + \header + \li Menu Item + \li Description + \row + \li \uicontrol{Import} + \li Apply changes from a patch file. + \row + \li \uicontrol{Incoming} + \li Monitor the status of a remote repository by listing + the changes that will be pulled. + \row + \li \uicontrol{Outgoing} + \li Monitor the status of a remote repository by listing + the changes that will be pushed. + \row + \li \uicontrol{Pull} + \li Pull changes from the remote repository. + \row + \li \uicontrol{Push} + \li Push changes to the remote repository. + \endtable +*/ diff --git a/doc/src/vcs/creator-vcs-perforce.qdoc b/doc/src/vcs/creator-vcs-perforce.qdoc new file mode 100644 index 00000000000..1347f87083b --- /dev/null +++ b/doc/src/vcs/creator-vcs-perforce.qdoc @@ -0,0 +1,84 @@ +/**************************************************************************** +** +** Copyright (C) 2016 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 {Qt Creator Manual} + \previouspage creator-vcs-mercurial.html + \page creator-vcs-perforce.html + \nextpage creator-vcs-subversion.html + + \title Using Perforce + + Perforce is a fast software configuration management system developed by + Perforce Software. + + When you start \QC, it looks for the executable specified + in the \uicontrol{P4 command} field in \uicontrol{Tools > Options > Version + Control > Perforce}. If the file is not found, the following error + message is displayed in the \uicontrol {Version Control} output pane: + \uicontrol {Perforce: Unable to determine the repository: "p4.exe" + terminated with exit code 1}. If you use Perforce, check that the + path to the executable is specified correctly in the \uicontrol{P4 command} + field. + + If you do not use Perforce, you can disable the Perforce plugin to + get rid of the error message. Choose \uicontrol {Help > About Plugins} and + deselect the \uicontrol Load check box for the \uicontrol Perforce plugin in + the \uicontrol {Version Control} group. + + \section1 Using Additional Perforce Functions + + In the Perforce options, you can specify workspace details: + \uicontrol {P4 user}, \uicontrol {P4 client}, and \uicontrol {P4 port}. To + specify the details individually for several projects, use configuration + files instead. Create a \c {p4config.txt} configuration file for each + project in the top level project directory. + + The \uicontrol Perforce submenu contains the following additional items: + + \table + \header + \li Menu Item + \li Description + \row + \li \uicontrol{Describe} + \li View information about changelists and the files in them. + \row + \li \uicontrol{Edit File} + \li Open a file for editing. + \row + \li \uicontrol{Opened} + \li List files that are open for editing. + \row + \li \uicontrol{Pending Changes} + \li Group files for commit. + \endtable +*/ diff --git a/doc/src/vcs/creator-vcs-subversion.qdoc b/doc/src/vcs/creator-vcs-subversion.qdoc new file mode 100644 index 00000000000..a83fe37fc99 --- /dev/null +++ b/doc/src/vcs/creator-vcs-subversion.qdoc @@ -0,0 +1,45 @@ +/**************************************************************************** +** +** Copyright (C) 2016 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 {Qt Creator Manual} + \previouspage creator-vcs-perforce.html + \page creator-vcs-subversion.html + \nextpage creator-configuring-projects.html + + \title Using Subversion + + Subversion is an open source version control system. + + In addition to the standard version control system functions, you can + select \uicontrol Tools > \uicontrol Subversion > \uicontrol Describe + to display commit log messages for a revision. +*/ diff --git a/doc/src/vcs/creator-vcs.qdoc b/doc/src/vcs/creator-vcs.qdoc new file mode 100644 index 00000000000..d32fc9147b2 --- /dev/null +++ b/doc/src/vcs/creator-vcs.qdoc @@ -0,0 +1,289 @@ +/**************************************************************************** +** +** Copyright (C) 2016 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 {Qt Creator Manual} + \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 + \row + \li \l{Using CVS}{CVS} + \li \l{http://www.cvshome.org} + \li + \row + \li \l{Using Git}{Git} + \li \l{http://git-scm.com/} + \li Git version 1.8.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 or specify the path to + the command line client executables in \uicontrol{Tools} > \uicontrol{Options} > + \uicontrol {Version Control}. + + 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 msysGit on Windows, see + \l {Using msysGit on 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{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 jdoe + Hans Mustermann hm + \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 {Patch command} specifies the path to the patch utility that is + used to apply changes in the format used to represent the diff + output. The \uicontrol Revert command uses the patch utility to revert + partial changes. + + \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. + + \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. + + \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. +*/