0024514: Unclear guidelines to report issues in Mantis
[occt.git] / dox / dev_guides / git_guide / git_guide.md
index 03739bd..8126490 100644 (file)
@@ -1,4 +1,4 @@
-Guide to installing and using Git for OCCT development {#dev_guides__git_guide}
+Guide to installing and using Git for OCCT development {#occt_dev_guides__git_guide}
 =================================
 
 @tableofcontents 
@@ -97,46 +97,32 @@ The official repository contains:
 
 @subsubsection occt_gitguide_2_1_1 Installation of Git for Windows
 
-  Download Git for Windows distributive from http://code.google.com/p/msysgit/downloads/list.
+  Download Git for Windows distributive from https://git-for-windows.github.io/
   During the installation:
 
-  * Select Windows Explorer integration options:
-    * Git Bash Here
-    * Git GUI Here
-    
-@image html OCCT_GitGuide_V2_image001.png
-@image latex OCCT_GitGuide_V2_image001.png
-
-  * To avoid a mess in your PATH, we recommend selecting ‘Run Git from Windows Prompt’ in the environment settings dialog: 
-  
-@image html OCCT_GitGuide_V2_image002.png
-@image latex OCCT_GitGuide_V2_image002.png
-
+  * Check-in "Windows Explorer integration" options:
+    * "Git Bash Here";
+    * "Git GUI Here".
+  * To avoid a mess in your PATH, we recommend selecting "Run Git from Windows Prompt" in the environment settings dialog: 
   * In "Configuring the line ending conversions" dialog, select "Checkout Windows-style, commit Unix style endings".
-  
-@image html OCCT_GitGuide_V2_image003.png
-@image latex OCCT_GitGuide_V2_image003.png
  
   Note that by default Git user interface is localized to the system default language. 
   If you prefer to work with the English interface, remove or rename .msg localization file 
   in subdirectories *share/git-gui/lib/msgs* and *share/gitk/lib/msgs* of the Git installation directory.
   
-  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. 
+  Before the first commit to the OCCT repository, make sure that your User Name in the Git configuration file (file <i>.gitconfig</i> in the <i>$HOME</i> directory) is equal to your username on the OCCT development portal. 
 
 @subsubsection occt_gitguide_2_1_2 Installation and configuration of TortoiseGit
 
   Download TortoiseGit distributive from http://code.google.com/p/tortoisegit/downloads/list. 
   Launch the installation.
 
-  * Select your SSH client. Choose OpenSSH if you prefer to use command-line tools 
-   for SSH keys generation, or TortoisePLink if you prefer to use GUI tool (PuttyGen, see 3.2):
-   
-@image html OCCT_GitGuide_V2_image004.png
-@image latex OCCT_GitGuide_V2_image004.png
-
-  * Complete the installation.
+ * Select your SSH client. Choose option 
+         * "OpenSSH, Git default SSH Client" if you prefer to use command-line tools for SSH keys generation, or
+         * "TortoisePLink, coming from Putty, integrates with Windows better" if you prefer to use GUI tool (PuttyGen, see 3.2).
+ * Complete the installation.
   
-  TortoiseGit integrates to Windows Explorer, thus it is possible to use context menu in Windows Explorer to access its functionality:  
+  TortoiseGit integrates into Windows Explorer, thus it is possible to use context menu in Windows Explorer to access its functionality:  
   
 @image html OCCT_GitGuide_V2_image005.png
 @image latex OCCT_GitGuide_V2_image005.png
@@ -150,14 +136,14 @@ The official repository contains:
 
   * After the installation  select Start -> Programs -> TortoiseGit Settings to configure TortoiseGit.
   
-  Select Git->Config to add your user name and Email address to the local .gitconfig file
+  Select Git->Config to add your user name and Email address to the local <i>.gitconfig</i> file
   
   @image html OCCT_GitGuide_V2_image006.png
   @image latex OCCT_GitGuide_V2_image006.png
 
 @subsection occt_gitguide_2_2 Linux platform
 
-  We assume that Linux users have Git already installed and available in the PATH.
+  We assume that Linux users have Git already installed and available in the *PATH*.
   
   Make sure to configure Git so that the user name is equal to your username 
   on the OCCT development portal, and set SafeCrLf option to true:
@@ -190,7 +176,7 @@ The official repository contains:
   
   It is highly recommended to use the tools that come 
   with the chosen Git client for generation of SSH keys. 
-  Using incompatible tools (e.g. ssh-keygen.exe from Cygwin for code generation, 
+  Using incompatible tools (e.g. *ssh-keygen.exe* from Cygwin for code generation, 
   and TortoiseGit GUI with a default Putty client for connection to server) 
   may lead to authentication problems.
 
@@ -201,8 +187,8 @@ The official repository contains:
   Use this option if you have installed TortoiseGit (or other GUI Git client on Windows) 
   and have chosen “TortoisePLink” (or other Putty client) as SSH client during installation.
   
-  To generate the key with this client, run Puttygen (e.g. from Start menu -> TortoiseGit -> Puttygen), 
-  then click Generate and move mouse cursor over the blank area until the key is generated. 
+  To generate the key with this client, run **Puttygen** (e.g. from Start menu -> TortoiseGit -> Puttygen), 
+  then click **Generate** and move mouse cursor over the blank area until the key is generated. 
   
 @image html OCCT_GitGuide_V2_image007.png "Putty key generator"
 @image latex OCCT_GitGuide_V2_image007.png "Putty key generator"
@@ -221,7 +207,7 @@ The official repository contains:
   during installation of TortoiseGit (or other Windows tool).
   
   Make sure that you have *ssh* and *ssh-keygen* commands in the path. 
-  On Windows, you might need to start 'Git Bash' command prompt window provided by Git for Windows.
+  On Windows, you might need to start **Git Bash** command prompt window.
   
   Use the following command to generate SSH keys:
 ~~~~~  
@@ -230,14 +216,14 @@ The official repository contains:
 
   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.
   
-  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.
+  The command will ask you where to store the keys. It is recommended to accept the default path <i>$HOME/.ssh/id_rsa</i>. 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.
     
   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.  
   
   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/):
   
   * *id_rsa* - private key
-  * id_rsa.pub - public key
+  * *id_rsa.pub* - public key
   
   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).
 
@@ -250,11 +236,10 @@ The official repository contains:
 @subsection occt_gitguide_3_3 Adding public key in your account
 
 Log 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. 
+
 Click 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. 
-  Click **Save** to input the key to the system. 
-  
-@image html OCCT_GitGuide_V2_image008.png
-@image latex OCCT_GitGuide_V2_image008.png  
+
+Click **Save** to input the key to the system. 
 
   Note that a user can have several SSH keys. 
   You can distinguish between these keys by the Title field ID; by default it is taken from SSH key comment. 
@@ -265,7 +250,7 @@ Click on that tab, then click **Add a public key**, and paste the text of the pu
   to update the configuration after the new key is added. 
   After that time, you can try accessing Git.
 
-@section occt_gitguide_4 WORK WITH REPOSITORY: DEVELOPER OPERATIONS
+@section occt_gitguide_4 Work with repository: developer operations
 
 @subsection occt_gitguide_4_1 General workflow
 
@@ -307,7 +292,7 @@ Click on that tab, then click **Add a public key**, and paste the text of the pu
     > git clone gitolite@git.dev.opencascade.org:occt <path>
 ~~~~~
 
-  where <i><path></i> is the path to the new folder which will be created for the repository.
+  where <i>\<path\></i> is the path to the new folder which will be created for the repository.
     
   * In TortoiseGit: create a new folder, open it and right-click in the Explorer window, then choose **Git Clone** in the context menu:
  
@@ -335,10 +320,6 @@ In the console:
 In TortoiseGit: 
   * Go to the local copy of the repository. 
   * Right-click in the Explorer window, then choose **Git Create Branch**.
-  
-@image html OCCT_GitGuide_V2_image011.png
-@image latex OCCT_GitGuide_V2_image011.png
-
   * Select **Base On** Branch *remotes/origin/master*.  
 
 @image html OCCT_GitGuide_V2_image012.png
@@ -396,7 +377,7 @@ In TortoiseGit:
 @image latex OCCT_GitGuide_V2_image014.png
 
   Unstaged files will be shown if you check the option ‘Show Unversioned Files’. 
-  Double-clock on each modified file to see the changes to be committed (as a difference vs. the base version). 
+  Double-click on each modified file to see the changes to be committed (as a difference vs. the base version). 
 
 @subsection occt_gitguide_4_6 Pushing branch to the remote repository
 
@@ -504,7 +485,7 @@ Rebasing is a good occasion to clean-up the history of commits in the branch. Co
   
 To rebase your branch into a single commit, you need to do the following:
   * Switch to your branch (e.g. “CR12345”)
-  * In TortoiseGit history log, select a branch to rebase on *(remotes/origin/master)* and in the context menu choose **Rebase “CR12345” onto this**.
+  * In TortoiseGit history log, select a branch to rebase on <i>(remotes/origin/master)</i> and in the context menu choose **Rebase “CR12345” onto this**.
   * 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.
   
 @image html OCCT_GitGuide_V2_image023.png
@@ -539,7 +520,7 @@ To rebase your branch into a single commit, you need to do the following:
 
   Use of TortoiseGit is recommended for convenient code review:
 
-  * Fetch the changes from the remote repository as described in <a href="#occt_gitguide_4_7">Synchronizing with remote repository</a> section.   
+  * Fetch the changes from the remote repository as described in @ref occt_gitguide_4_7 "Synchronizing with remote repository" section.   
   * Right-click on the repository, choose **TortoiseGit** -> **Show** log;
   * Locate the remote branch you need to review;
   * 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.