creator-vcs.qdoc 31.5 KB
Newer Older
1
2
/****************************************************************************
**
3
4
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
5
**
6
** This file is part of the Qt Creator documentation.
7
**
8
9
10
11
12
13
14
** 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.
15
**
16
** GNU Free Documentation License Usage
17
18
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
19
20
21
22
** 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.
23
24
25
26
27
28
29
30
31
32
**
****************************************************************************/

// **********************************************************************
// 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.
// **********************************************************************

/*!
33
    \contentspage {Qt Creator Manual}
34
    \previouspage creator-project-wizards-xml.html
35
    \page creator-version-control.html
36
    \nextpage creator-configuring-projects.html
37
38
39
40
41
42

    \title Using Version Control Systems

    Version control systems supported by \QC are:
    \table
        \header
43
44
45
            \li  Version Control System
            \li  Address
            \li  Notes
46
        \row
47
48
            \li Bazaar
            \li \l{http://bazaar.canonical.com/}
49
            \li
50
        \row
51
52
            \li ClearCase
            \li \l{http://www-01.ibm.com/software/awdtools/clearcase/}
53
            \li
54
        \row
55
56
57
            \li CVS
            \li \l{http://www.cvshome.org}
            \li
58
        \row
59
60
            \li Git
            \li \l{http://git-scm.com/}
Orgad Shaneh's avatar
Orgad Shaneh committed
61
            \li Git version 1.8.0, or later
62
63

                Gerrit version 2.6, or later
64
        \row
65
66
            \li Mercurial
            \li \l{http://mercurial.selenic.com/}
67
            \li
68
        \row
69
70
71
            \li Perforce
            \li \l{http://www.perforce.com}
            \li Server version 2006.1 and later
72
        \row
73
74
            \li Subversion
            \li \l{http://subversion.apache.org/}
75
            \li Subversion version 1.7.0 and later
76
77
78
79
80
81
82
    \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
83
84
    the command line client executables in \uicontrol{Tools} > \uicontrol{Options} >
    \uicontrol {Version Control}.
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99

    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.

100
101
102
    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
103
104
105
    to \c %HOMEDRIVE%%HOMEPATH% when the Git executable is run and authorization
    works as it would with \c {git bash}.

106
    \section1 Setting Up General Options
107

108
109
    Select \uicontrol{Tools} > \uicontrol{Options} > \uicontrol{Version Control}
    > \uicontrol{General}
110
111
112
113
    to specify settings for submit messages:

    \list

114
        \li \uicontrol{Submit message check script} is a script or program that
115
116
117
118
119
            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.

120
        \li \uicontrol{User/alias configuration file} is a text file that lists
121
122
123
            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:
124
125

            \code
126
            Jon Doe <Jon.Doe@company.com> jdoe <jdoe@somemail.com>
127
128
129
            Hans Mustermann <Hans.Mustermann@company.com> hm <info@company.com>
            \endcode

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

133
        \li \uicontrol{User fields configuration file} is a simple text file
134
            consisting of lines specifying submit message fields that take
135
            authors as values, for example:
136
137

            \code
138
139
140
141
            Acked-by:
            Initial-patch-by:
            Reported-by:
            Rubber-stamped-by:
142
            Signed-off-by:
143
            Tested-by:
144
145
            \endcode

146
147
            After you specify a file in this field, you can add authors as
            values of the submit message fields when submitting changes. If
148
149
            you also specified a \uicontrol{User/alias configuration file}, you can
            select authors in the \uicontrol Nicknames dialog.
150

151
        \li \uicontrol{SSH prompt command} specifies an ssh-askpass command that you
152
153
154
155
            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.

156
        \li \uicontrol {Patch command} specifies the path to the patch utility that is
Leena Miettinen's avatar
Leena Miettinen committed
157
            used to apply changes in the format used to represent the diff
158
            output. The \uicontrol Revert command uses the patch utility to revert
Leena Miettinen's avatar
Leena Miettinen committed
159
160
            partial changes.

161
162
163
164
165
166
    \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.
167
    When creating a new project by selecting \uicontrol File > \uicontrol{New File or
168
169
    Project}, you can choose a version control system on the final wizard page.

170
    You can also select \uicontrol Tools and then select \uicontrol {Create Repository}
171
172
    in the submenu for the version control system.

173
    To import a project that is under version control, choose \uicontrol {File >
174
175
176
177
178
179
    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

180
    The \uicontrol{Tools} menu contains a submenu for each supported version
181
182
    control system.

183
184
    The \uicontrol{Version Control} output pane displays the commands that are
    executed, a timestamp, and the relevant output. Select \uicontrol {Window > Output
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
    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

212
    With Git and Subversion, the diff is displayed side-by-side in a \l{Comparing Files}
Leena Miettinen's avatar
Leena Miettinen committed
213
    {diff editor} by default. To use the inline diff view instead, select the
Leena Miettinen's avatar
Leena Miettinen committed
214
    \uicontrol {Switch to Text Diff Editor} (1) option from the toolbar. In the inline
Leena Miettinen's avatar
Leena Miettinen committed
215
216
    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.
217

218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
    \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

239
240
    \section2 Viewing Versioning History and Change Details

241
242
    Display the versioning history of a file by selecting \uicontrol{Log}
    or \uicontrol{Filelog}. Typically, the log output contains the date, the commit
243
    message, and a change or revision identifier. Click on the identifier to
Leena Miettinen's avatar
Leena Miettinen committed
244
245
246
247
248
    display a description of the change including the diff in the
    \uicontrol {Git Show} view.

    \image qtcreator-vcs-show.png

249
250
    Right-clicking on an identifier brings up a context menu that lets you
    show annotation views of previous versions (see \l{Annotating Files}).
251
    With Git you can also choose to cherry-pick or revert a change.
252
253
254

    \section2 Annotating Files

255
256
    Annotation views are obtained by selecting \uicontrol{Annotate} or \uicontrol{Blame}.
    Selecting \uicontrol{Annotate} or \uicontrol{Blame} displays the lines of the file
257
258
259
260
261
262
263
    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
Leena Miettinen's avatar
Leena Miettinen committed
264
    it. It also works for Git and Mercurial using SHA-1.
265
266
267
268
269
270
271

    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
272
    system by choosing \uicontrol{Commit} or \uicontrol{Submit}. \QC displays a
273
274
275
276
277
278
    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
279
    \uicontrol{Commit} to start committing.
280

281
    The \uicontrol{Diff Selected Files} button brings up a diff view of the
282
    files selected in the file list. Since the commit page is just another
Leena Miettinen's avatar
Leena Miettinen committed
283
    editor, you can go back to it by closing the diff view. You can also switch
284
    to an open diff view by selecting it in the \uicontrol{Open Documents} pane in the
Leena Miettinen's avatar
Leena Miettinen committed
285
    sidebar.
286
287
288

    \section2 Reverting Changes

Leena Miettinen's avatar
Leena Miettinen committed
289
    All supported version control systems support reverting your project to
290
291
292
293
    known states. This functionality is generally called \e reverting.

    The changes discarded depend on the version control system.

294
    A version control system can replace the \uicontrol Revert menu option with other
295
296
297
298
299
    options.

    \section3 Reverting Changes Using Git

    The Git version control system has an index that is used to stage
Sergio Ahumada's avatar
Sergio Ahumada committed
300
    changes. The index is committed on the next commit. Git allows you to revert
301
302
303
304
305
    back to the state of the last commit as well as to the state staged in the
    index.

    \list

306
        \li \uicontrol Git > \uicontrol {Current File} > \uicontrol{Undo Unstaged Changes} reverts
Leena Miettinen's avatar
Leena Miettinen committed
307
            all changes and resets the current file to the state of the
Leena Miettinen's avatar
Leena Miettinen committed
308
            index.
309

310
        \li \uicontrol Git > \uicontrol {Current File} > \uicontrol {Undo Uncommitted Changes}
Leena Miettinen's avatar
Leena Miettinen committed
311
            reverts all changes, discarding the
Leena Miettinen's avatar
Leena Miettinen committed
312
            index. This returns the current file to the state it was in right
313
314
            after the last commit.

315
        \li \uicontrol Git > \uicontrol {Local Repository} > \uicontrol Reset opens a dialog
Leena Miettinen's avatar
Leena Miettinen committed
316
317
            where you can select the SHA-1 to reset the working directory to.
            This is useful after applying patches for review, for example. You
318
319
320
            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
321
322
            reset that resets HEAD and the index (nothing remains staged)
            without touching the working directory.
Leena Miettinen's avatar
Leena Miettinen committed
323

324
325
326
327
    \endlist

    \section2 Viewing Status

328
    You can select \uicontrol{Status} to view the status of the project or
329
330
331
332
    repository.

    \section2 Updating the Working Tree

333
    You can select \uicontrol Update to update your working tree with the latest
334
335
336
337
338
339
340
341
    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

342
    You can select \uicontrol Delete to delete obsolete files from the repository.
343
344
345
346
347
348
349
350

    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.

351
    The \uicontrol Bazaar submenu contains the following additional items:
352
353
354
355
356
357

    \table
        \header
            \li Menu Item
            \li Description
        \row
358
            \li \uicontrol Pull
359
360
            \li Turn the branch into a mirror of another branch.
        \row
361
            \li \uicontrol Push
362
363
            \li Update a mirror of the branch.
        \row
364
            \li \uicontrol Uncommit
365
366
367
368
369
370
371
            \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
372
    revision, select \uicontrol Tools > \uicontrol Bazaar > \uicontrol Uncommit.
373

374
    In the \uicontrol Uncommit dialog, select options to keep tags that point to
375
376
377
378
    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
379
    revision in the \uicontrol Revision field.
380

381
382
    To test the outcome of the \uicontrol Uncommit command without actually removing
    anything, select \uicontrol {Dry Run}.
383

384
    \uicontrol Uncommit leaves the working tree ready for a new commit. The only
385
386
    change it might make is restoring pending merges that were present before
    the commit.
387

388
389
390
391
    \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
392
393
    ClearCase client plugin is available on Linux and Windows for accessing a
    ClearCase server.
394

395
    The \uicontrol ClearCase submenu contains the following additional items:
396
397
398

    \table
        \header
399
400
            \li Menu Item
            \li Description
401
        \row
402
            \li \uicontrol{Check In}
403
            \li Create a permanent new version of the current file or all files
404
405
                in the versioned object base (VOB).
        \row
406
            \li \uicontrol{Check In Activity}
407
            \li Check in checked-out versions in the change set of the current
408
409
                Unified Change Management (UCM) activity.
        \row
410
            \li \uicontrol{Check Out}
411
            \li Create a writable copy of a branch. If you check out files in a
412
413
                UCM view, they are added to the change set of the UCM activity.
        \row
414
            \li \uicontrol{Undo Check Out}
415
            \li Cancel the checkout for a file and delete the checked-out
416
417
                version.
        \row
418
            \li \uicontrol{Undo Hijack}
419
            \li Resolve hijacked files. If you change the read-only attribute of
420
421
422
423
424
                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
425
426
427

    CVS is an open source version control system.

428
    In addition to the standard version control system functions, you can
429
430
    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.
431
432
433
434
435
436

    \section2 Using Additional Git Functions

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

Leena Miettinen's avatar
Leena Miettinen committed
437
    You can use the \l{http://code.google.com/p/gerrit/}{Gerrit} code review
438
    tool for projects that use Git.
Leena Miettinen's avatar
Leena Miettinen committed
439

Leena Miettinen's avatar
Leena Miettinen committed
440
    \section3 Working with the Current File
441

Leena Miettinen's avatar
Leena Miettinen committed
442
    In addition to the standard version control system functions, you can
443
444
    select \uicontrol Tools > \uicontrol Git > \uicontrol {Current File} >
    \uicontrol {Stage File for
Leena Miettinen's avatar
Leena Miettinen committed
445
    Commit} to mark a new or modified file for committing to the repository.
446

447
    To undo this function, select \uicontrol {Unstage File from Commit}.
448

Leena Miettinen's avatar
Leena Miettinen committed
449
450
451
    \section3 Working with the Current Project

    In addition to the standard version control system functions, you can
452
453
    select \uicontrol Tools > \uicontrol Git > \uicontrol {Current Project} >
    \uicontrol {Clean Project}
Leena Miettinen's avatar
Leena Miettinen committed
454
    to clean the working directory. All files that are not under version control
455
456
    are displayed in the \uicontrol {Clean Repository} dialog. Ignored files are
    deselected by default. Select the files to delete and click \uicontrol Delete.
Leena Miettinen's avatar
Leena Miettinen committed
457
458
459
460

    \section3 Working with Local Repositories

    In addition to the standard version control system functions, you can
461
462
    select \uicontrol Tools > \uicontrol Git > \uicontrol {Local Repository} >
    \uicontrol Clean to clean
Leena Miettinen's avatar
Leena Miettinen committed
463
464
    the repository.

465
466
    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
Leena Miettinen's avatar
Leena Miettinen committed
467
468
    commit message.

Leena Miettinen's avatar
Leena Miettinen committed
469
    To amend an earlier comment in a series of related commits, select
470
471
    \uicontrol Tools > \uicontrol Git > \uicontrol {Local Repository} >
    \uicontrol {Fixup Previous Commit}. This operation is done using interactive
Leena Miettinen's avatar
Leena Miettinen committed
472
473
    rebase. In case of conflicts, a merge tool is suggested.

474
475
    To change a series of commits in the local repository, select \uicontrol Tools >
    \uicontrol Git > \uicontrol {Local Repository} > \uicontrol {Interactive Rebase}. You can
Leena Miettinen's avatar
Leena Miettinen committed
476
477
478
    reorder or discard commits, squash them into a single commit, or edit the
    commit messages.

Leena Miettinen's avatar
Leena Miettinen committed
479
480
481
482
    The following sections describe how to manage local and remote branches,
    apply patches, and use stashes.

    \section4 Working with Branches
483

484
    To work with Git branches, select \uicontrol{Branches}. The checked out branch
485
486
487
488
489
490
491
492
493
    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
494
495
            \li Menu Item
            \li Description
Leena Miettinen's avatar
Leena Miettinen committed
496
        \row
497
            \li \uicontrol{Refresh}
Leena Miettinen's avatar
Leena Miettinen committed
498
            \li Refresh the list of branches.
499
        \row
500
            \li \uicontrol{Add}
501
            \li Create new tracking and non-tracking branches.
502
        \row
503
            \li \uicontrol{Remove}
504
            \li Remove a local branch. You cannot delete remote branches.
Leena Miettinen's avatar
Leena Miettinen committed
505
        \row
506
            \li \uicontrol Rename
Leena Miettinen's avatar
Leena Miettinen committed
507
            \li Rename a local branch.
Leena Miettinen's avatar
Leena Miettinen committed
508
        \row
509
            \li \uicontrol{Checkout}
Leena Miettinen's avatar
Leena Miettinen committed
510
511
            \li Check out the selected branch and make it current. You can stash
                changes you have made to tracked files.
512
        \row
513
            \li \uicontrol{Diff}
514
            \li Show the differences between the selected and the current
515
516
                branch.
        \row
517
            \li \uicontrol{Log}
518
            \li Show the changes in a branch.
519
        \row
520
            \li \uicontrol Merge
Leena Miettinen's avatar
Leena Miettinen committed
521
            \li Join the development histories in two branches together.
522
523
524
525

                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,
526
527
                select \uicontrol {Fast-Forward}. If you do not want to fast-forward
                the branch, select \uicontrol {No Fast-Forward}.
Leena Miettinen's avatar
Leena Miettinen committed
528
        \row
529
            \li \uicontrol Rebase
Leena Miettinen's avatar
Leena Miettinen committed
530
            \li Copy local commits to the updated upstream head.
Leena Miettinen's avatar
Leena Miettinen committed
531
        \row
532
            \li \uicontrol {Cherry Pick}
Leena Miettinen's avatar
Leena Miettinen committed
533
534
            \li Cherry pick the top commit from the selected branch.
        \row
535
            \li \uicontrol Track
Leena Miettinen's avatar
Leena Miettinen committed
536
            \li Set the current branch to track the selected one.
537
538
    \endtable

Leena Miettinen's avatar
Leena Miettinen committed
539
540
541
    \section4 Applying Patches

    Patches are rewriting instructions that can be applied to a set of files.
542
543
    To apply a patch file that is open in \QC, select \uicontrol Tools > \uicontrol Git >
    \uicontrol {Local Repository} > \uicontrol {Apply from Editor}.
Leena Miettinen's avatar
Leena Miettinen committed
544
545

    To select the patch file to apply from the file system, select
546
    \uicontrol {Apply from File}.
Leena Miettinen's avatar
Leena Miettinen committed
547
548
549
550
551
552
553
554

    \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.

555
556
    To stash all local changes, select \uicontrol Tools > \uicontrol Git >
    \uicontrol {Local Repository} > \uicontrol Stash > \uicontrol Stash. The working copy is reset
557
558
559
    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}.
Leena Miettinen's avatar
Leena Miettinen committed
560
561

    To display a dialog that shows all known stashes with options to restore,
562
    display or delete them, select \uicontrol Stashes.
Leena Miettinen's avatar
Leena Miettinen committed
563
564

    To save a snapshot of your current work under a name for later reference,
565
    select \uicontrol {Take Snapshot}. The working copy is unchanged. For example, if
Leena Miettinen's avatar
Leena Miettinen committed
566
567
568
569
    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
570
    the current working tree state, select \uicontrol {Stash Pop}.
Leena Miettinen's avatar
Leena Miettinen committed
571

Leena Miettinen's avatar
Leena Miettinen committed
572
573
574
    \section3 Applying Actions to Commits

    To browse a directory or the commit history and to apply actions on the
575
    commits, select \uicontrol Tools > \uicontrol Git > \uicontrol {Actions on Commits}. You can
Leena Miettinen's avatar
Leena Miettinen committed
576
577
578
579
    checkout, revert, or cherry-pick commits or view them in the diff editor.

    \image creator-git-commit-actions.png "Select a Git Commit dialog"

580
581
    \section3 Working with Remote Repositories

Leena Miettinen's avatar
Leena Miettinen committed
582
    In addition to the standard version control system functions, you can
583
    select \uicontrol Tools > \uicontrol Git > \uicontrol {Remote Repository} > \uicontrol Pull to
Leena Miettinen's avatar
Leena Miettinen committed
584
    pull changes from the remote repository. If there are locally modified
585
586
587
    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
Leena Miettinen's avatar
Leena Miettinen committed
588
589
590
591
    pulling.

    \section4 Managing Remote Repositories

592
593
    To manage remote repositories available in Git, select \uicontrol Tools > \uicontrol Git
    > \uicontrol {Remote Repository} > \uicontrol{Manage Remotes}. Double-click the names
Leena Miettinen's avatar
Leena Miettinen committed
594
    and URLs of the remote repositories to edit them.
595
596
597
598
599

    The following operations are supported:

    \table
        \header
600
601
            \li Menu Item
            \li Description
Leena Miettinen's avatar
Leena Miettinen committed
602
        \row
603
            \li \uicontrol{Refresh}
Leena Miettinen's avatar
Leena Miettinen committed
604
            \li Refresh the list of remote repositories.
605
        \row
606
            \li \uicontrol{Add}
607
            \li Add a new remote repository.
608
        \row
609
            \li \uicontrol{Fetch}
610
            \li Fetch all the branches and change information from a remote
611
                repository.
Leena Miettinen's avatar
Leena Miettinen committed
612
        \row
613
            \li \uicontrol Push
Leena Miettinen's avatar
Leena Miettinen committed
614
            \li Push committed changes to the remote repository.
615
        \row
616
            \li \uicontrol{Remove}
617
            \li Remove a remote repository.
Leena Miettinen's avatar
Leena Miettinen committed
618

619
620
    \endtable

Leena Miettinen's avatar
Leena Miettinen committed
621
    \section4 Using Git with Subversion
622

Leena Miettinen's avatar
Leena Miettinen committed
623
    You can use Git as a client for a Subversion server. To fetch changes from a
624
625
    Subversion repository to a Git repository, select \uicontrol Tools > \uicontrol Git >
    \uicontrol {Remote Repository} > \uicontrol Subversion > \uicontrol Fetch.
626

627
    To view the Git Subversion log, select \uicontrol Log.
628

Leena Miettinen's avatar
Leena Miettinen committed
629
    \section4 Reviewing Code with Gerrit
Leena Miettinen's avatar
Leena Miettinen committed
630
631
632
633

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

634
635
    Select \uicontrol Tools > \uicontrol Options > \uicontrol {Version Control}
    > \uicontrol Gerrit to
Leena Miettinen's avatar
Leena Miettinen committed
636
637
638
639
    specify the connection to the Gerrit server.

    \image qtcreator-gerrit-options.png

640
641
    To push committed changes to Gerrit, select \uicontrol Tools > \uicontrol Git >
    \uicontrol {Remote Repository} > \uicontrol {Push to Gerrit}.
Leena Miettinen's avatar
Leena Miettinen committed
642
643

    To view the same information about each change as in the Gerrit
644
645
    web interface, select \uicontrol Tools > \uicontrol Git > \uicontrol {Remote Repository} >
    \uicontrol Gerrit.
Leena Miettinen's avatar
Leena Miettinen committed
646
647
648

    \image qtcreator-gerrit.png

649
    To view details of the selected change, select \uicontrol Show.
Leena Miettinen's avatar
Leena Miettinen committed
650

651
    To cherry-pick the selected change to the local repository, select
652
653
654
655
    \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.
Leena Miettinen's avatar
Leena Miettinen committed
656

657
    To check out the change in a headless state, select \uicontrol Checkout.
Leena Miettinen's avatar
Leena Miettinen committed
658

659
    To refresh the list of changes, select \uicontrol Refresh.
Leena Miettinen's avatar
Leena Miettinen committed
660

Leena Miettinen's avatar
Leena Miettinen committed
661
662
    \section3 Working with Git Tools

663
664
    To start a graphical interface to Git, select \uicontrol Tools > \uicontrol Git >
    \uicontrol {Git Tools} > \uicontrol {Git Gui}.
Leena Miettinen's avatar
Leena Miettinen committed
665

666
    \note On OS X, the default Git installation does not contain Git Gui. To
Leena Miettinen's avatar
Leena Miettinen committed
667
    use Git Gui, install it separately. To start Git Gui from \QC, select
668
669
    \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.
Leena Miettinen's avatar
Leena Miettinen committed
670

671
672
    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
Leena Miettinen's avatar
Leena Miettinen committed
673
    the current document or in the folder that contains the current document.
674
675
    To specify arguments for running Gitk, select \uicontrol Tools > \uicontrol Options >
    \uicontrol {Version Control} > \uicontrol Git.
Leena Miettinen's avatar
Leena Miettinen committed
676
677

    To use some other application for viewing Git history, such as GitX or
678
679
680
681
    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}.
Leena Miettinen's avatar
Leena Miettinen committed
682

683
684
    To resolve merge conflicts, select \uicontrol Tools > \uicontrol Git > \uicontrol {Git Tools}
    > \uicontrol {Merge Tool}.
Leena Miettinen's avatar
Leena Miettinen committed
685

686
687
688
689
    \section2 Using Additional Mercurial Functionality

    Mercurial is a free, distributed source control management tool.

690
    The \uicontrol Mercurial submenu contains the following additional items:
691
692
693

    \table
        \header
694
695
            \li Menu Item
            \li Description
696
        \row
697
            \li \uicontrol{Import}
698
            \li Apply changes from a patch file.
699
        \row
700
            \li \uicontrol{Incoming}
701
            \li Monitor the status of a remote repository by listing
702
703
                the changes that will be pulled.
        \row
704
            \li \uicontrol{Outgoing}
705
            \li Monitor the status of a remote repository by listing
706
707
                the changes that will be pushed.
        \row
708
            \li \uicontrol{Pull}
709
            \li Pull changes from the remote repository.
710
        \row
711
            \li \uicontrol{Push}
712
            \li Push changes to the remote repository.
713
714
715
716
717
718
719
720
     \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
721
    in the \uicontrol{P4 command} field in \uicontrol{Tools > Options > Version
722
    Control > Perforce}. If the file is not found, the following error
723
724
    message is displayed in the \uicontrol {Version Control} output pane:
    \uicontrol {Perforce: Unable to determine the repository: "p4.exe"
725
    terminated with exit code 1}. If you use Perforce, check that the
726
    path to the executable is specified correctly in the \uicontrol{P4 command}
727
728
729
    field.

    If you do not use Perforce, you can disable the Perforce plugin to
730
731
732
    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.
733

734
735
736
737
738
739
    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.

740
    The \uicontrol Perforce submenu contains the following additional items:
741
742
743

    \table
        \header
744
745
            \li Menu Item
            \li Description
746
        \row
747
            \li \uicontrol{Describe}
748
            \li View information about changelists and the files in them.
749
        \row
750
            \li \uicontrol{Edit File}
751
            \li Open a file for editing.
752
        \row
753
            \li \uicontrol{Opened}
754
            \li List files that are open for editing.
755
        \row
756
            \li \uicontrol{Pending Changes}
757
            \li Group files for commit.
758
759
760
761
762
763
    \endtable

    \section2 Using Additional Subversion Functions

    Subversion is an open source version control system.

764
    In addition to the standard version control system functions, you can
765
    select \uicontrol Tools > \uicontrol Subversion > \uicontrol Describe to display commit log
766
    messages for a revision.
767
768

*/