0024722: Move functionality of WOK command wgendoc to OCCT tool gendoc
[occt.git] / dox / dev_guides / git_guide / git_guide.md
CommitLineData
ba06f8bb 1Guide to installing and using Git for OCCT development {#occt_dev_guides__git_guide}
bf62b306 2=================================
3
4@tableofcontents
5
6@section occt_gitguide_1 Overview
7
8@subsection occt_gitguide_1_1 Purpose
9
10 The purpose of this document is to provide a practical introduction to Git
11 to OCCT developers who are not familiar with this tool
12 and to facilitate the use of the official OCCT Git repository for code contribution to OCCT.
13
14 Reading this document does not exempt from the need to learn Git concepts and tools.
15 Please consult a book or manual describing Git to get acquainted with this tool.
16 Many good books on Git can be found at http://git-scm.com/documentation
17
18 For the experienced Git users it can be enough to read sections 1 and 3
19 of this document to start working with the repository.
20
21 Please make sure to get familiar with the Contribution Workflow document
22 that describes how Git is used for processing contributions to OCCT.
23
24 This and related documents are available at the Resources page
25 of the OCCT development portal at http://dev.opencascade.org/index.php?q=home/resources.
26
27@subsection occt_gitguide_1_2 Git URL
28
29 URL of the official OCCT source code Git repository (accessed by SSH protocol) is:
30
dd21889e 31 gitolite@git.dev.opencascade.org:occt
bf62b306 32
33 or
34
dd21889e 35 ssh://gitolite@dev.opencascade.org/occt.git
bf62b306 36
37@subsection occt_gitguide_1_3 Content
38
39The official repository contains:
40
41 * The current certified version of OCCT: the "master" branch. This branch is updated by the Bugmaster only. Official OCCT releases are marked by tags.
42 * Topic branches created by contributors to submit changes for review / testing or for collaborative development. The topic branches should be named by the pattern "CR12345" where 12345 is the ID of the relevant issue registered in Mantis (without leading zeroes), and "CR" stands for "Change Request". The name can have an additional postfix used if more than one branch was created for the same issue.
43 * Occasionally topic branches with non-standard names can be created by the Bugmaster for special needs.
44
45@subsection occt_gitguide_1_4 Short rules of use
46
47 The name specified in the user.name field in Git configuration should correspond
48 to your login name on the OCCT development portal.
49 This is important to clearly identify the authorship of commits.
50 (The full real name can be used as well; in this case add the login username in parentheses.)
51
52 By default, contributors are allowed to push branches only with the names starting with CR
53 (followed by the relevant Mantis issue ID).
54 Possibility to work with other branches can be enabled by the Bugmaster on request.
55
56 The branch is created by the developer in his local repository when the development of a contribution starts.
57 The branch for new developments is to be created from the current master.
58 The branch for integration of patches or developments based on an obsolete version
59 is created from a relevant tag or commit. The branch should be pushed to the official repo
60 only when sharing with other people (for collaborative work or review / testing) is needed.
61
62 Rebasing the local branch to the current master is encouraged before the first submission
63 to the official repository. If rebasing was needed after the branch is pushed to the official repo,
64 the rebased branch should have a different name (use suffix).
65
66 Integration of contributions that have passed certification testing is made exclusively by the Bugmaster.
67 Normally this is made by rebasing the contribution branch on the current master
68 and squashing it into a single commit. This is made to have the master branch history plain and clean,
69 following the general rule “one issue – one commit”.
70 The description of the commit integrated to the master branch is taken from the Mantis issue
71 (ID, 'Summary', followed by the information from 'Documentation' field if present).
72
73 In special cases when it is important to save the commits history in the branch
74 (e.g. in case of a long-term development integration) it can be integrated by merge (no fast-forward).
75
76 The authorship of the contribution is respected by preserving the Author field of the commit when integrating.
77 Branches are removed from the official repository when integrated to the master.
78 The Bugmaster can also remove branches which have no commits during one-month period.
79
80 The Bugmaster may ask the developer (normally the one who produced the contribution)
81 to rebase a branch on the current master, in the case if merge conflicts appear during integration.
82
83@subsection occt_gitguide_1_5 Version of Git
84
85 The repository is tested to work with Git 1.7.6 to 1.7.9.
86 Please do not use versions below 1.7.1 as they are known to cause troubles.
87
88@section occt_gitguide_2 Installing Tools for Work with Git
89
90@subsection occt_gitguide_2_1 Windows platform
91
92 Installation of Git for Windows (provided by MSysGit project) is required.
93
94 In addition, it is recommended to install TortoiseGit to work with Git on Windows.
95 If you do not install TortoiseGit or any other GUI tool,
96 you can use GitGui and Gitk GUI tools delivered with Git and available on all platforms.
97
98@subsubsection occt_gitguide_2_1_1 Installation of Git for Windows
99
100 Download Git for Windows distributive from http://code.google.com/p/msysgit/downloads/list.
101 During the installation:
102
103 * Select Windows Explorer integration options:
104 * Git Bash Here
105 * Git GUI Here
106
107@image html OCCT_GitGuide_V2_image001.png
108@image latex OCCT_GitGuide_V2_image001.png
109
110 * To avoid a mess in your PATH, we recommend selecting ‘Run Git from Windows Prompt’ in the environment settings dialog:
111
112@image html OCCT_GitGuide_V2_image002.png
113@image latex OCCT_GitGuide_V2_image002.png
114
115 * In "Configuring the line ending conversions" dialog, select "Checkout Windows-style, commit Unix style endings".
116
117@image html OCCT_GitGuide_V2_image003.png
118@image latex OCCT_GitGuide_V2_image003.png
119
120 Note that by default Git user interface is localized to the system default language.
121 If you prefer to work with the English interface, remove or rename .msg localization file
122 in subdirectories *share/git-gui/lib/msgs* and *share/gitk/lib/msgs* of the Git installation directory.
123
124 Before the first commit to the OCCT repository, make sure that your User Name in the Git configuration file (file *.gitconfig* in the $HOME directory) is equal to your username on the OCCT development portal.
125
126@subsubsection occt_gitguide_2_1_2 Installation and configuration of TortoiseGit
127
128 Download TortoiseGit distributive from http://code.google.com/p/tortoisegit/downloads/list.
129 Launch the installation.
130
131 * Select your SSH client. Choose OpenSSH if you prefer to use command-line tools
132 for SSH keys generation, or TortoisePLink if you prefer to use GUI tool (PuttyGen, see 3.2):
133
134@image html OCCT_GitGuide_V2_image004.png
135@image latex OCCT_GitGuide_V2_image004.png
136
137 * Complete the installation.
138
dd21889e 139 TortoiseGit integrates to Windows Explorer, thus it is possible to use context menu in Windows Explorer to access its functionality:
140
bf62b306 141@image html OCCT_GitGuide_V2_image005.png
142@image latex OCCT_GitGuide_V2_image005.png
143
dd21889e 144
bf62b306 145
146 Note that if you have installed MSysGit or have Git installed in non-default path,
147 on the first time you use TortoiseGit you may get the message demanding to define path to Git.
148 In such case, click on **Set MSysGit path** button and add the path to git.exe
149 and path to MigGW libraries in the Settings dialog.
150
151 * After the installation select Start -> Programs -> TortoiseGit Settings to configure TortoiseGit.
152
153 Select Git->Config to add your user name and Email address to the local .gitconfig file
154
155 @image html OCCT_GitGuide_V2_image006.png
156 @image latex OCCT_GitGuide_V2_image006.png
157
158@subsection occt_gitguide_2_2 Linux platform
159
160 We assume that Linux users have Git already installed and available in the PATH.
161
162 Make sure to configure Git so that the user name is equal to your username
163 on the OCCT development portal, and set SafeCrLf option to true:
164
165~~~~~
166 > git config --global user.name "Your User Name"
167 > git config --global user.email your@mail.address
168 > git config --global your@mail.address
169~~~~~
170
171@section occt_gitguide_3 Getting access to the repository
172
173@subsection occt_gitguide_3_1 Prerequisites
174
175 Access to the repository is granted to the users who have signed the Contributor License Agreement.
176
177 The repository is accessed by SSH protocol, thus you need to register your public SSH key
178 on the development portal to get access to the repository.
179
180 SSH keys are used for secure authentication of the user when accessing the Git server.
181 Private key is the one stored on the user workstation (optionally encrypted).
182 Open (or public) key is stored in the user account page on the web site.
183 When Git client accesses the remote repository through SSH,
184 it uses this key pair to identify the user and acquire relevant access rights.
185
186 Normally when you have Git installed, you should have also SSH client available.
187 On Unix/Linux it is installed by default in the system.
188 On Windows it is typical to have several SSH clients installed;
189 in particular they are included with Cygwin, Git, TortoiseGit.
190
191 It is highly recommended to use the tools that come
192 with the chosen Git client for generation of SSH keys.
193 Using incompatible tools (e.g. ssh-keygen.exe from Cygwin for code generation,
194 and TortoiseGit GUI with a default Putty client for connection to server)
195 may lead to authentication problems.
196
197@subsection occt_gitguide_3_2 How to generate a key
198
199@subsubsection occt_gitguide_3_2_1 Generating key with Putty
200
201 Use this option if you have installed TortoiseGit (or other GUI Git client on Windows)
202 and have chosen “TortoisePLink” (or other Putty client) as SSH client during installation.
203
204 To generate the key with this client, run Puttygen (e.g. from Start menu -> TortoiseGit -> Puttygen),
205 then click Generate and move mouse cursor over the blank area until the key is generated.
206
207@image html OCCT_GitGuide_V2_image007.png "Putty key generator"
208@image latex OCCT_GitGuide_V2_image007.png "Putty key generator"
209
210 After the key is generated, you will see GUI controls to define the public key comment
211 and / or specify the password for the private key protection.
212 When done, save both the public and the private key to the files of your choice
213 (make sure to store your private key in a secure place!).
214
215 Copy the public key as shown by Puttygen to the clipboard to add it in your account.
216 Do not copy the Putty public key file content -- it is formatted in a way not suitable for the web site.
217
218@subsubsection occt_gitguide_3_2_2 Generating key with command-line tools
219
220 Use this option if you work on Linux or if you have chosen “OpenSSH” as SSH client
221 during installation of TortoiseGit (or other Windows tool).
222
223 Make sure that you have *ssh* and *ssh-keygen* commands in the path.
224 On Windows, you might need to start 'Git Bash' command prompt window provided by Git for Windows.
225
226 Use the following command to generate SSH keys:
227~~~~~
228 > ssh-keygen -t rsa -C "your@mail.address"
229~~~~~
230
231 The last argument is an optional comment, which can be included with the public key and used to distinguish between different keys (if you have many). The common practice is to put here your mail address or workstation name.
232
233 The command will ask you where to store the keys. It is recommended to accept the default path *$HOME/.ssh/id_rsa*. Just press Enter for that. You will be warned if a key is already present in the specified file; you can either overwrite it by the new one, or stop generation and use the old key.
234
235 If you want to be on the safe side, enter password to encrypt the private key. You will be asked to enter this password each time you use that key (e.g. access a remote Git repository), unless you use the tool that caches the key (like TortoiseGit). If you do not want to bother, enter an empty string.
236
237 On Windows, make sure to note the complete path to the generated files (the location of your $HOME might be not obvious). Two key files will be created in the specified location (by default in $HOME/.ssh/):
238
239 * *id_rsa* - private key
240 * id_rsa.pub - public key
241
242 The content of the public key file (one text line) is the key to be added to the user account on the site (see below).
243
244@subsubsection occt_gitguide_3_2_3 Generating key with Git GUI
245
246 GitGUI (standard GUI interface included with Git) provides the option
247 to either generate the SSH key (if not present yet) or show the existing one.
248 Click Help/Show SSH key and copy the public key content for adding to the user account page (see below).
249
250@subsection occt_gitguide_3_3 Adding public key in your account
251
dd21889e 252Log in on the portal http://dev.opencascade.org and click on **My account** link to the right. If you have a Contributor status, you will see **SSH keys** tab to the right.
253Click on that tab, then click **Add a public key**, and paste the text of the public key (see above sections on how to generate the key) into the text box.
254 Click **Save** to input the key to the system.
bf62b306 255
dd21889e 256@image html OCCT_GitGuide_V2_image008.png
257@image latex OCCT_GitGuide_V2_image008.png
258
bf62b306 259 Note that a user can have several SSH keys.
260 You can distinguish between these keys by the Title field ID; by default it is taken from SSH key comment.
261 It is typical to use your e-mail address or workstation name for this field; no restrictions are set by the portal.
dd21889e 262
bf62b306 263
264 Please note that some time (5-10 min) is needed for the system
265 to update the configuration after the new key is added.
266 After that time, you can try accessing Git.
267
268@section occt_gitguide_4 WORK WITH REPOSITORY: DEVELOPER OPERATIONS
269
270@subsection occt_gitguide_4_1 General workflow
271
272 To start working with OCCT source repository, you need to create its clone in your local system.
273 This cloned repository will manage your working copy of the sources
274 and provide you the means to exchange code between your clone and the origin.
275
276 In most cases it is sufficient to have one clone of the repository;
277 your working copy will be updated automatically by Git when you switch branches.
278
279 The typical development cycle for an issue is as follows:
280
281 * Create a new branch for your development, basing on the selected version of the sources
282 (usually the current master) and switch your working copy to it
283 * Develop and test your change. Note that for the first time, and after any changes
284 made in CDL files you will have to re-generate build scripts or Visual Studio projects using WOK.
285 * Do as many commits in your branch as you feel convenient;
286 the general recommendation is to commit every stable state (even incomplete), to record the history of your development.
287 * Push your branch to the repository when your development is complete or when you need to share it with other people (e.g. for review)
288 * Before the first push, rebase your local branch on the latest master;
289 consider collapsing the history in one commit unless you think the history of your commits is interesting for others.
290 Make sure to provide a good commit message.
291 * Do not amend the commits that have been already pushed in the remote repository,
292 If you need to rebase your branch, commit the rebased branch under a different name, and remove the old branch.
293
294 You can switch to another branch at any moment
295 (unless you have some uncommitted changes in the working copy)
296 and return back to the branch when necessary (e.g. to take into account review remarks).
297 Note that only the sources that are different between the switched branches will be modified,
298 thus required recompilation should be reasonably small in most cases.
299
300@subsection occt_gitguide_4_2 Cloning official repository
301
302 Clone the official OCCT repository in one of following ways:
303
304 * From command line by command:
305
306~~~~~
307 > git clone gitolite@git.dev.opencascade.org:occt <path>
308~~~~~
309
ba06f8bb 310 where <i>\<path\></i> is the path to the new folder which will be created for the repository.
bf62b306 311
dd21889e 312 * In TortoiseGit: create a new folder, open it and right-click in the Explorer window, then choose **Git Clone** in the context menu:
bf62b306 313
314@image html OCCT_GitGuide_V2_image009.png
315@image latex OCCT_GitGuide_V2_image009.png
316
dd21889e 317 If you have chosen Putty as SSH client during TortoiseGit installation, check the **Load Putty Key** option and specify the location of the private key file saved by PuttyGen (see 3.2.1). This shall be done for the first time only.
bf62b306 318
dd21889e 319 Note that on the first connection to the repository server you may be requested to enter a password for your private SSH key; further you can get a message that the authenticity of the host cannot be established and will be asked if you want to continue connecting or not. Choose **Yes** to continue. The host’s key will be stored in <i>$HOME/.ssh/known_hosts</i> file.
bf62b306 320
321@subsection occt_gitguide_4_3 Branch creation
322
323 You need to create a branch when you are going to start development of a new change,
324 apply a patch, etc. It is recommended to fetch updates from the remote repository
325 before this operation, to make sure you work with the up-to-date version.
326
327 Create a branch from the current master branch unless you need to base your development on a particular version or revision.
328
329In the console:
330
331~~~~~
332 > git checkout -b CR12345 origin/master
333~~~~~
334
335In TortoiseGit:
336 * Go to the local copy of the repository.
dd21889e 337 * Right-click in the Explorer window, then choose **Git Create Branch**.
bf62b306 338
339@image html OCCT_GitGuide_V2_image011.png
340@image latex OCCT_GitGuide_V2_image011.png
341
dd21889e 342 * Select **Base On** Branch *remotes/origin/master*.
bf62b306 343
344@image html OCCT_GitGuide_V2_image012.png
345@image latex OCCT_GitGuide_V2_image012.png
346
dd21889e 347 Check option **Switch to new branch** if you are going to start working with the newly created branch immediately.
bf62b306 348
349@subsection occt_gitguide_4_4 Branch switching
350
351 If you need to switch to another branch, use Git command checkout for that.
352 In the console:
353
354~~~~~
355 > git checkout CR12345
356~~~~~
357
dd21889e 358 In TortoiseGit: right-click in the explorer window and select in the context menu **TortoiseGit** -> **Switch/Checkout**.
bf62b306 359
360@image html OCCT_GitGuide_V2_image013.png
361@image latex OCCT_GitGuide_V2_image013.png
362
363 Note that in order to work with the branch locally you need to set option
dd21889e 364 **Create new branch** when you checkout the branch from the remote repository for the first time.
365 Option **Track** stores association between the local branch and the original branch in a remote repository.
bf62b306 366
367@subsection occt_gitguide_4_5 Committing branch changes
368
369 Commit your changes locally as soon as a stable status of the work is reached.
370 Make sure to review carefully the committed changes beforehand to avoid unintentional commit of a wrong code.
371
372 * In the console:
373
374~~~~~
375 > git diff
376
377 > git commit -a -m "Write meaningful commit message here"
378~~~~~
379
380 Option –a tells the command to automatically include (stage) files
381 that have been modified or deleted, but it will omit the new files that might have been added by you.
382 To commit such new files, you must add (stage) them before commit command.
383
384 To find new unstaged files and them to commit, use commands:
385
386~~~~~
387 > git status -s
388 ?? file1.hxx
389 ?? file2.cxx
390 > git add file1.hxx file2.cxx
391~~~~~
392
dd21889e 393 * In TortoiseGit: right-click in the explorer window and select in the context menu <b>Git Commit -> CR…</b>:
bf62b306 394
395@image html OCCT_GitGuide_V2_image014.png
396@image latex OCCT_GitGuide_V2_image014.png
397
398 Unstaged files will be shown if you check the option ‘Show Unversioned Files’.
399 Double-clock on each modified file to see the changes to be committed (as a difference vs. the base version).
400
401@subsection occt_gitguide_4_6 Pushing branch to the remote repository
402
403 When the code developed in your local branch is ready for review,
404 or you need to share it with others, push your local changes to the remote repository.
405
406 * In the console:
407
408~~~~~
409 > git push "origin" CR12345:CR12345
410~~~~~
411
dd21889e 412 * In TortoiseGit: right-click in the explorer window and select in the context menu, TortoiseGit -> **Push**
bf62b306 413
414@image html OCCT_GitGuide_V2_image015.png
415@image latex OCCT_GitGuide_V2_image015.png
416
dd21889e 417Note that Git forbids pushing a branch if the corresponding remote branch already exists and has some changes, which are not in the history of your local branch. This may happen in different situations:
418 * You have amended the last commit which is already in the remote repository. If you are sure that nobody else uses your branch, push again with **Force** option.
419 * You have rebased your branch, so that now it is completely different from the branch in the remote repository. In this case, push it under a different name (add a suffix):
bf62b306 420
421@image html OCCT_GitGuide_V2_image016.png
422@image latex OCCT_GitGuide_V2_image016.png
423
dd21889e 424 Then remove the original remote branch so that other people recognize that it has been replaced by the new one. For that, select TortoiseGit -> **Push** again, select an empty line for your local branch name,
425 and enter the name of the branch to be removed in **Remote** field:
bf62b306 426
dd21889e 427 * The other developer has committed some changes in the remote branch. In this case, **Pull** changes from the remote repository to have them merged with your version, and push your branch after it is successfully merged.
bf62b306 428
429@subsection occt_gitguide_4_7 Synchronizing with remote repository
430
431 Maintain your repository synchronized with the remote one and clean unnecessary stuff regularly.
dd21889e 432
433 Use Git command *fetch* with option *prune* to get the update of all branches from the remote repository and to clean your local repository from the remote branches that have been deleted.
bf62b306 434
435 * In the console:
bf62b306 436~~~~~
437 > git fetch --prune
438~~~~~
439
dd21889e 440 * In TortoiseGit: right-click in the explorer window and select in the context menu **TortoiseGit** -> **Fetch**. Check in **Prune** check-box.
bf62b306 441
442@image html OCCT_GitGuide_V2_image018.png
443@image latex OCCT_GitGuide_V2_image018.png
444
dd21889e 445 If the branch you are working with has been changed in the remote repository, use Git command *pull* to get the remote changes and merge them with your local branch.
446
bf62b306 447 This operation is required in particular to update your local master branch when the remote master changes.
448
449 * In console:
450~~~~~
451 > git pull
452~~~~~
dd21889e 453
454 * In TortoiseGit: right-click in the explorer window and select in the context menu **TortoiseGit** -> **Pull**.
bf62b306 455
456@image html OCCT_GitGuide_V2_image019.png
457@image latex OCCT_GitGuide_V2_image019.png
458
dd21889e 459Note that the local branches of your repository are the primary place, where your changes are stored until they get integrated to the official version of OCCT (master branch). The branches submitted to official repository are for collaborative work, review, and integration - that repository should not be used for long-term storage of incomplete changes.
bf62b306 460
dd21889e 461Remove the local branches that you do not need any more. Note that you cannot delete the current branch. It means that you need to switch to another one (e.g. master) if the branch you are going to delete is the current one.
bf62b306 462
463 * In the console:
464~~~~~
465 > git branch -d CR12345
466~~~~~
467
dd21889e 468 * In TortoiseGit: right-click in the explorer window and select in the context menu **TortoiseGit** -> **Git Show Log**.
bf62b306 469
470@image html OCCT_GitGuide_V2_image020.png
471@image latex OCCT_GitGuide_V2_image020.png
472
dd21889e 473 Select **All branches** check-box to view all branches.
474 Right-click on the branch you want to delete and select **Delete** item in the context menu.
bf62b306 475
dd21889e 476Note that many functions described above can be accessed from the Log View, which is a very convenient tool to visualize and manage branches.
bf62b306 477
478@subsection occt_gitguide_4_8 Applying a fix made on older version of OCCT
479
dd21889e 480If you have a fix made on a previous version of OCCT, perform the following sequence of operations to prepare it for testing and integration to the current development version:
481 * Identify the version of OCCT on which the fix has been made. In most cases, this will be an OCCT release, e.g. OCCT 6.7.0.
482 * Find a tag or a commit corresponding to this version in the Git history log of the master branch.
bf62b306 483 * Create a branch basing on this tag or commit. In TortoiseGit history log: right-click on the base commit, then select **Create branch at this version**.
484
485@image html OCCT_GitGuide_V2_image021.png
486@image latex OCCT_GitGuide_V2_image021.png
487
dd21889e 488 * Check option **Switch to the new branch** to start working within the new branch immediately, or switch to it separately afterwards.
bf62b306 489 * Put your fix in the working copy, build and check that it works, then commit to the branch.
dd21889e 490 * Rebase the branch on the current master. In TortoiseGit: right-click on the working directory, choose **TortoiseGit** -> **Rebase**, select *remotes/origin/master* as UpStream revision, and click **Start**:
bf62b306 491
492@image html OCCT_GitGuide_V2_image022.png
493@image latex OCCT_GitGuide_V2_image022.png
494
dd21889e 495Note that you can get some conflicts during rebase. To resolve them, double-click on each conflicted file (highlighted by red in the file list) to open visual merge tool. Switch between conflicting fragments by red arrows, and for each one decide if the code of one or both conflicting versions is to be taken.
bf62b306 496
497@subsection occt_gitguide_4_9 Rebasing with history clean-up
498
dd21889e 499At some moments you might need to rebase your branch on the latest version of the master.
bf62b306 500
dd21889e 501We recommend rebasing before the first submission of the branch for review or when the master has diverged substantially from your branch.
bf62b306 502
dd21889e 503Rebasing is a good occasion to clean-up the history of commits in the branch. Consider collapsing (squashing, in terms of Git) the history of your branch into a single commit unless you deem that having separate commits is important for your future work with the branch or its code reviewing. Git also allows changing the order of commits, edit commit contents and messages, etc.
bf62b306 504
dd21889e 505To rebase your branch into a single commit, you need to do the following:
bf62b306 506 * Switch to your branch (e.g. “CR12345”)
dd21889e 507 * In TortoiseGit history log, select a branch to rebase on *(remotes/origin/master)* and in the context menu choose **Rebase “CR12345” onto this**.
508 * In the **Rebase** dialog, check **Squash All**. You can also change the order of commits and define for each commit whether it should be kept (**Pick**), edited, or just skipped.
509
bf62b306 510@image html OCCT_GitGuide_V2_image023.png
511@image latex OCCT_GitGuide_V2_image023.png
512
bf62b306 513 * Click **Start**.
dd21889e 514 * The process will stop if a conflict is detected. In that case, find files with status **Conflicted** in the list (marked by red), and double-click on them to resolve the conflict. When all conflicts are resolved, click **Continue**.
bf62b306 515
516@image html OCCT_GitGuide_V2_image024.png
517@image latex OCCT_GitGuide_V2_image024.png
518
519 * At the end of the process, edit the final commit message (it should start from the issue ID and a description from Mantis in the first line, followed by a summary of actual changes), and click **Commit**.
520
521@image html OCCT_GitGuide_V2_image025.png
522@image latex OCCT_GitGuide_V2_image025.png
523
524@section occt_gitguide_5 Work with repository: Reviewer operations
525
526@subsection occt_gitguide_5_1 Review branch changes using GitWeb
527
528 The changes made in the branch can be reviewed without direct access to Git, using GitWeb interface:
529
530 * Open GitWeb in your web browser: http://git.dev.opencascade.org/gitweb/?p=occt.git
dd21889e 531 * Locate the branch you want to review among **heads** (click ‘…’ at the bottom of the page to see the full list).
532 * Click **log** (or **shortlog**) to see the history of the branch.
bf62b306 533
dd21889e 534 **Note** that the branch can contain more than one commit, and you need to distinguish commits that belong to that branch (those to be reviewed) from the commits corresponding to the previous state of the master branch. Normally the first commit in the list that starts from the ID of the other issue indicates the branching point; commits above it are the ones to be reviewed.
bf62b306 535
dd21889e 536 * Click **commitdiff** on each log entry to review the changes (highlighted with color format).
bf62b306 537
538@subsection occt_gitguide_5_2 Review branch changes with TortoiseGit
539
540 Use of TortoiseGit is recommended for convenient code review:
541
dd21889e 542 * Fetch the changes from the remote repository as described in <a href="#occt_gitguide_4_7">Synchronizing with remote repository</a> section.
543 * Right-click on the repository, choose **TortoiseGit** -> **Show** log;
bf62b306 544 * Locate the remote branch you need to review;
dd21889e 545 * To review commits one-by-one, select each commit in the log. The list of changed files is shown at the bottom of the window; double-click on the file will open visual compare tool.
546 * To review all changes made in the branch at once, or to compare two arbitrary revisions, select the corresponding commits in the log (e.g. the last commit in the branch and the branching point), ight-click for the context menu, and choose **Compare revisions**.
bf62b306 547
548@image html OCCT_GitGuide_V2_image026.png
549@image latex OCCT_GitGuide_V2_image026.png
550