Version control systems supported by Qt Creator are:

Setting Up Version Control Systems

Qt Creator 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 PATH environment variable or specify the path to the command line client executables in Tools > Options > 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 Qt Creator.

Using msysGit on Windows

If you configure Git for use with git bash, only, and use SSH authorization, Git looks for the SSH keys in the directory where the HOME environment points to. The variable is always set by 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 HOME environment variable from Qt Creator. Select Tools > Options > Version Control > Git. Select the Environment Variables and the Set "HOME" environment variable check boxes. HOME is set to %HOMEDRIVE%%HOMEPATH% when the Git executable is run and authorization works as it would with git bash.

Setting Up General Options

Select Tools > Options > Version Control > General to specify settings for submit messages:

• 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.
• 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:

  Jon Doe <Jon.Doe@company.com> jdoe <jdoe@somemail.com>
  Hans Mustermann <Hans.Mustermann@company.com> hm <info@company.com>

  After you specify a file in this field, you can select authors as values of the submit message fields in the Nicknames dialog.

• User fields configuration file is a simple text file consisting of lines specifying submit message fields that take authors as values, for example:

  Acked-by:
  Initial-patch-by:
  Reported-by:
  Rubber-stamped-by:
  Signed-off-by:
  Tested-by:

  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 User/alias configuration file, you can select authors in the Nicknames dialog.

• 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, ssh-askpass or x11-ssh-askpass, depending on the ssh-askpass implementation that you use.
• 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 Revert command uses the patch utility to revert partial changes.

Creating VCS Repositories for New Projects

Qt Creator 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 File > New File or Project, you can choose a version control system on the final wizard page.

You can also select Tools and then select Create Repository in the submenu for the version control system.

To import a project that is under version control, choose 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.

Using Version Control Systems

The Tools menu contains a submenu for each supported version control system.

The Version Control output pane displays the commands that are executed, a timestamp, and the relevant output. Select Window > Output Panes > Version Control to open the pane.

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.

Viewing Diff Output

All version control systems provide menu options to diff the current file or project: to compare it with the latest version stored in the repository and to display the differences. In Qt Creator, a diff is displayed in a read-only editor. If the file is accessible, you can double-click on a selected diff chunk and Qt Creator opens an editor displaying the file, scrolled to the line in question.

With Git, the diff is displayed side-by-side in a diff editor by default. To use the inline diff view instead, select the Switch to Text Diff Editor 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.

Viewing Versioning History and Change Details

Display the versioning history of a file by selecting Log or 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. Right-clicking on an identifier brings up a context menu that lets you show annotation views of previous versions (see Annotating Files). With Git you can also choose to cherry-pick or revert a change.

Annotating Files

Annotation views are obtained by selecting Annotate or Blame. Selecting Annotate or 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.

Committing Changes

Once you have finished making changes, submit them to the version control system by choosing Commit or Submit. Qt Creator 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.

When you have finished filling out the commit page information, click on Commit to start committing.

The 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 Open Documents pane in the sidebar.

Reverting Changes

All supported version control systems support reverting your project to known states. This functionality is generally called reverting.

The changes discarded depend on the version control system.

A version control system can replace the Revert menu option with other options.

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.

• Git > Current File > Undo Unstaged Changes reverts all changes and resets the current file to the state of the index.
• Git > Current File > 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.
• Git > Local Repository > 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 Soft reset that does not touch the index file nor the working tree at all, a Hard reset that discards all changes to tracked files in working tree, and a Mixed reset that resets HEAD and the index (nothing remains staged) without touching the working directory.

Viewing Status

You can select Status to view the status of the project or repository.

Updating the Working Tree

You can select 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.

Deleting Files

You can select 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.

Using Additional Bazaar Functions

Bazaar is a free version control system sponsored by Canonical.

The Bazaar submenu contains the following additional items:

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 Tools > Bazaar > Uncommit.

In the 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 Revision field.

To test the outcome of the Uncommit command without actually removing anything, select Dry Run.

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.

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 ClearCase submenu contains the following additional items:

Using Additional CVS Functions

CVS is an open source version control system.

In addition to the standard version control system functions, you can select Tools > CVS > Edit to open a file for editing. To discard the changes that you made in a file, select Unedit.

Using Additional Git Functions

Git is a fast decentralized version control system. Git is available for Windows, Linux and Mac.

You can use the Gerrit code review tool for projects that use Git.

Working with the Current File

In addition to the standard version control system functions, you can select Tools > Git > Current File > Stage File for Commit to mark a new or modified file for committing to the repository.

To undo this function, select Unstage File from Commit.

Working with the Current Project

In addition to the standard version control system functions, you can select Tools > Git > Current Project > Clean Project to clean the working directory. All files that are not under version control are displayed in the Clean Repository dialog. Ignored files are deselected by default. Select the files to delete and click Delete.

Working with Local Repositories

In addition to the standard version control system functions, you can select Tools > Git > Local Repository > Clean to clean the repository.

To apply latest changes to the last commit, select Tools > Git > Local Repository > Amend Last Commit. You can also edit the commit message.

To amend an earlier comment in a series of related commits, select Tools > Git > Local Repository > 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 Tools > Git > Local Repository > 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.

Working with Branches

To work with Git branches, select Branches. The checked out branch is shown in bold and underlined in the list of branches. Double-click branch names to edit them.

The following operations are supported:

Applying Patches

Patches are rewriting instructions that can be applied to a set of files. To apply a patch file that is open in Qt Creator, select Tools > Git > Local Repository > Apply from Editor.

To select the patch file to apply from the file system, select Apply from File.

Using Stashes

With Git, you can put your current set of changes onto a virtual shelf called a 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 Tools > Git > Local Repository > Stash > Stash. The working copy is reset to the state it had after the last commit.

To display a dialog that shows all known stashes with options to restore, display or delete them, select Stashes.

To save a snapshot of your current work under a name for later reference, select 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 Stash Pop.

Applying Actions to Commits

To browse a directory or the commit history and to apply actions on the commits, select Tools > Git > Actions on Commits. You can checkout, revert, or cherry-pick commits or view them in the diff editor.

Working with Remote Repositories

In addition to the standard version control system functions, you can select Tools > Git > Remote Repository > Pull to pull changes from the remote repository. If there are locally modified files, you are prompted to stash the changes. Select Tools > Options > Version Control > Git and then select the Pull with rebase check box to perform a rebase operation while pulling.

Managing Remote Repositories

To manage remote repositories available in Git, select Tools > Git > Remote Repository > Manage Remotes. Double-click the names and URLs of the remote repositories to edit them.

The following operations are supported:

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 Tools > Git > Remote Repository > Subversion > Fetch.

To view the Git Subversion log, select Log.

Reviewing Code with Gerrit

If your Git project uses Gerrit for code reviews, you can view your changes in Qt Creator.

Select Tools > Options > Version Control > Gerrit to specify the connection to the Gerrit server.

To push committed changes to Gerrit, select Tools > Git > Remote Repository > Push to Gerrit.

To view the same information about each change as in the Gerrit web interface, select Tools > Git > Remote Repository > Gerrit.

To view details of the selected change, select Show.

To cherry-pick the selected change to the local repository, select Cherry Pick. To remove the change after testing it, select Tools > Git > Local Repository > Reset. In the Undo Changes to dialog, select the state to reset the working directory to, and then select OK.

To check out the change in a headless state, select Checkout.

To refresh the list of changes, select Refresh.

Working with Git Tools

To start a graphical interface to Git, select Tools > Git > Git Tools > Git Gui.

Note: On OS X, the default Git installation does not contain Git Gui. To use Git Gui, install it separately. To start Git Gui from Qt Creator, select Preferences > Version Control > Git, and set the path to the environment that contains Git Gui in the Prepend to PATH field.

To start the commit viewer for Git, select Tools > Git > Git Tools > 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 Tools > Options > Version Control > Git.

To use some other application for viewing Git history, such as GitX or QGit viewer, select Tools > Options > Version Control > Git and specify the path to the application executable in the Command field. To start the application, select Tools > Git > Git Tools > Repository Browser.

To resolve merge conflicts, select Tools > Git > Git Tools > Merge Tool.

Using Additional Mercurial Functionality

Mercurial is a free, distributed source control management tool.

The Mercurial submenu contains the following additional items:

Using Additional Perforce Functions

Perforce is a fast software configuration management system developed by Perforce Software.

When you start Qt Creator, it looks for the executable specified in the P4 command field in Tools > Options > Version Control > Perforce. If the file is not found, the following error message is displayed in the Version Control output pane: 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 P4 command field.

If you do not use Perforce, you can disable the Perforce plugin to get rid of the error message. Choose Help > About Plugins and deselect the Load check box for the Perforce plugin in the Version Control group.

The Perforce submenu contains the following additional items:

Using Additional Subversion Functions

Subversion is an open source version control system.

In addition to the standard version control system functions, you can select Tools > Subversion > Describe to display commit log messages for a revision.