org.eclipse.egit.doc/help/EGit/User_Guide/User-Guide.html

   1 <?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   2 <html xmlns="http://www.w3.org/1999/xhtml">
   3         <head>
   4                 <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
   5                 <title>EGit User Guide</title>
   6                 <link type="text/css" rel="stylesheet" href="../../book.css"/>
   7         </head>
   8         <body>
   9                 <table class="navigation" style="width: 100%;" border="0" summary="navigation">
  10                         <tr>
  11                                 <th style="width: 100%" align="center" colspan="3">EGit User Guide</th>
  12                         </tr>
  13                         <tr>
  14                                 <td style="width: 20%" align="left"></td>
  15                                 <td style="width: 60%" align="center"></td>
  16                                 <td style="width: 20%" align="right">
  17                                         <a href="Concepts.html" title="Concepts">
  18                                                 <img alt="Next" border="0" src="../../images/next.gif"/>
  19                                         </a>
  20                                 </td>
  21                         </tr>
  22                         <tr>
  23                                 <td style="width: 20%" align="left" valign="top"></td>
  24                                 <td style="width: 60%" align="center"></td>
  25                                 <td style="width: 20%" align="right" valign="top">Concepts</td>
  26                         </tr>
  27                 </table><hr class="navigation-separator"/>
  28                 <h1 id="Getting_Started">Getting Started</h1>
  29                 <h2 id="Overview">Overview</h2>
  30                 <p>If you're new to Git or distributed version control systems generally, then you might want to read
  31                         <a href="../../EGit/Git_For_Eclipse_Users/Git-For-Eclipse-Users.html" title="EGit/Git For Eclipse Users">Git for Eclipse Users</a> first. More background and details can be found in the on-line book
  32                         <a href="https://git-scm.com/book/en/v2" target="egit_external">Pro Git</a>.
  33                 </p>
  34                 <p>If you are coming from CVS, you can find common CVS workflows for Git
  35                         <a href="https://wiki.eclipse.org/Platform-releng/Git_Workflows" title="Platform-releng/Git Workflows" target="egit_external">Platform-releng/Git Workflows</a>.
  36                 </p>
  37                 <h3 id="The_Preferences_Dialog">The Preferences Dialog</h3>
  38                 <p>Many of the configurations you will make in Eclipse are found in the Preferences Dialog.
  39                         The Preferences Dialog is spawned, naturally enough, from a menu item labeled Preferences.
  40                         But the Preferences menu item is somewhat hard to find.
  41                         Preferences is located, not under the File or Edit menus, but under the Window menu.</p>
  42                 <ul>
  43                         <li>Click
  44                                 <b>Window &gt; Preferences</b>
  45                         </li>
  46                 </ul>
  47                 <p>Within the Preferences Dialog itself specific git options are also
  48                         <i>not</i> visible on the surface, but are found under the Team heading. You can also find the Git items in the Preferences Dialog by entering <code>git</code> as a filter string in the box where it, initially, says
  49                         <i>type filter text</i>.
  50                 </p>
  51                 <h2 id="Basic_Tutorial:_Adding_a_project_to_version_control">Basic Tutorial: Adding a project to version control</h2>
  52                 <h3 id="Configuration">Configuration</h3>
  53                 <h4 id="Identifying_yourself">Identifying yourself</h4>
  54                 <p>Whenever the history of the repository is changed (technically, whenever a commit is created), Git keeps track of the user who created that commit. The identification consists of a name (typically a person's name) and an e-mail address. This information is stored in file <code>~/.gitconfig</code> under dedicated keys.
  55                         <br/>
  56                 </p>
  57                 <p>EGit will ask you for this information when you create your first commit. By default, this dialog is shown only once until you create a new workspace or tick the checkbox "Show initial configuration dialog" on the Git Preference page:</p>
  58                 <p>
  59                         <img border="0" src="images/Egit-0.11-initialConfigurationDialog.png"/>
  60                 </p>
  61                 <p>You can also untick "Don't show this dialog again" if you want to see it again later.</p>
  62                 <p>Instead of using this dialog, you can always change this information using the Git configuration:
  63                         <br/>
  64                 </p>
  65                 <ul>
  66                         <li>Click
  67                                 <b>Window &gt; Preferences &gt; Team &gt; Git &gt; Configuration</b>
  68                         </li>
  69                         <li>Click
  70                                 <b>New Entry</b> and enter the key value pairs <code>user.email</code> and <code>user.name</code>
  71                                 <br/>
  72                         </li>
  73                 </ul>
  74                 <p>
  75                         <img border="0" src="images/Egit-0.9-getstarted-email.png"/>
  76                 </p>
  77                 <p>
  78                         <img border="0" src="images/Egit-0.9-getstarted-name.png"/>
  79                 </p>
  80                 <h4 id="Setting_up_the_Home_Directory_on_Windows">Setting up the Home Directory on Windows</h4>
  81                 <p>Add the environment variable <code>HOME</code> to your environment variables.</p>
  82                 <ol>
  83                         <li>In Windows 7, type "environment" at the start menu.</li>
  84                         <li>Select "Edit environment variables for your account".</li>
  85                         <li>Under "User Variables", click the "New" button.</li>
  86                         <li>Enter "HOME" in the name field.</li>
  87                         <li>Enter "%USERPROFILE%" or some other path in the value field.</li>
  88                         <li>Click OK, and OK again. You have just added the Home directory on Windows.&lt;br /&gt;</li>
  89                         <li>File &gt; Exit, then restart the application.</li>
  90                 </ol>
  91                 <p>Note that if you use
  92                         <a href="http://www.cygwin.com/" target="egit_external">Cygwin</a>, you should already have <code>HOME</code> set. For example, if you installed Cygwin to <code>C:\cygwin</code> and your username is Fred, then Cygwin should have already set <code>HOME</code> to <code>C:\cygwin\home\Fred</code> (or something similar). You can verify this by entering <code>echo %HOME%</code> in the Windows command prompt, or <code>echo $HOME</code> in the Cygwin shell.
  93                 </p>
  94                 <p>EGit needs this path for looking up the user configuration (.gitconfig). <code>HOME</code> should point to your home directory e.g. <code>C:\Users\Tom</code>.
  95                         <b>Ensure correct case!</b> E.g. <code>C:\users</code> instead of <code>C:\Users</code> may cause problems!
  96                 </p>
  97                 <p>If the <code>HOME</code> variable is not defined the home directory will be calculated by concatenating <code>HOMEDRIVE</code> and <code>HOMEPATH</code>.</p>
  98                 <p>If both <code>HOME</code> and <code>HOMEDRIVE</code> are not defined <code>HOMESHARE</code> will be used.</p>
  99                 <p>EGit shows a warning if <code>HOME</code> is not defined explicitly. Keep in mind that if you set the HOME environment variable while Eclipse is running, you will still see following warning. You will have to restart Eclipse for it to recognize the HOME value.</p>
 100                 <p>
 101                         <img border="0" src="images/Egit_no_home.png"/>
 102                 </p>
 103                 <h4 id="Pointing_out_the_System_wide_configuration">Pointing out the System wide configuration</h4>
 104                 <p>If you use Git for Windows as a companion to EGit, make sure EGit knows where Git is installed so it can find the "system wide settings", e.g. how core.autocrlf is set. Go to the settings and look under Team&gt;Git&gt;Configuration and then the System Settings tab. </p>
 105                 <p>If you selected one of the options to use Git from the Command Line Prompt when you installed Git for Windows, then the location of the system
 106                         wide settings is filled in with a path and everything is fine. If not, use the Browse button to locate where Git is installed, e.g. C:\Program Files(x86)\Git. </p>
 107                 <p>This advice also applies to users of other Git packagings, e.g. Git under Cygwin or TortoiseGit.</p>
 108                 <p>Non-Windows users should in theory check this setting, but the system wide settings are usually not used on non-Windows platforms.</p>
 109                 <h3 id="Create_Repository">Create Repository</h3>
 110                 <ul>
 111                         <li>Create a new Java project <code>HelloWorld</code>. (In this case, the project was built outside of your Eclipse Workspace.)</li>
 112                 </ul>
 113                 <p>
 114                         <img border="0" src="images/Egit-0.9-getstarted-project.png"/>
 115                 </p>
 116                 <ul>
 117                         <li>Select the project, click
 118                                 <b>File &gt; Team &gt; Share Project</b>.
 119                         </li>
 120                         <li>Select repository type
 121                                 <b>Git</b> and click
 122                                 <b>Next</b>.
 123                         </li>
 124                 </ul>
 125                 <p>
 126                         <img border="0" src="images/Egit-0.9-getstarted-share.png"/>
 127                 </p>
 128                 <ul>
 129                         <li>To configure the Git repository select the new project <code>HelloWorld</code>.</li>
 130                 </ul>
 131                 <p>
 132                         <img border="0" src="images/Egit-0.9-getstarted-create-project.png"/>
 133                 </p>
 134                 <ul>
 135                         <li>Click
 136                                 <b>Create Repository</b> to initialize a new Git repository for the <code>HelloWorld</code> project. If your project already resides in the working tree of an existing Git repository the repository is chosen automatically.
 137                         </li>
 138                 </ul>
 139                 <p>
 140                         <img border="0" src="images/Egit-0.9-getstarted-project-created.png"/>
 141                 </p>
 142                 <ul>
 143                         <li>Click
 144                                 <b>Finish</b> to close the wizard.
 145                         </li>
 146                         <li>The decorator text "[master]" behind the project shows that this project is tracked in a repository on the
 147                                 <i>master</i> branch and the question mark decorators show that the <code>.classpath</code> and <code>.project</code> and the <code>.settings</code> files are not yet under version control.
 148                         </li>
 149                 </ul>
 150                 <p>
 151                         <img border="0" src="images/Egit-0.9-getstarted-shared-project.png"/>
 152                 </p>
 153                 <h3 id="Track_Changes">Track Changes</h3>
 154                 <ul>
 155                         <li>Click
 156                                 <b>Team &gt; Add to Index</b> on the project node. (This menu item is named
 157                                 <b>Add</b> on older versions of Egit.)
 158                         </li>
 159                         <li>The
 160                                 <i>+</i> decorators show that now the project's files have been added to version control.
 161                         </li>
 162                         <li>Mark the "bin" folder as "ignored by Git", either by right-clicking on it and selecting
 163                                 <b>Team &gt; Ignore</b> or by creating a file <code>.gitignore</code> in the project folder with the following content:
 164                         </li>
 165                 </ul>
 166                 <pre>/bin
 167 </pre>
 168                 <ul>
 169                         <li>This excludes the <code>bin</code> folder from Git's list of tracked files.</li>
 170                         <li>Add <code>.gitignore</code> to version control (
 171                                 <b>Team &gt; Add</b>):
 172                         </li>
 173                 </ul>
 174                 <p>
 175                         <img border="0" src="images/Egit-0.11-getstarted-ignore-added.png"/>
 176                 </p>
 177                 <ul>
 178                         <li>You may have to set your Package Explorer filters in order to see <code>.gitignore</code> displayed in the Package Explorer. To access filters, select the down arrow on the right edge of the Package Explorer tab to display View Menu.</li>
 179                 </ul>
 180                 <p>
 181                         <img border="0" src="images/Pe_downarrow1.png"/>
 182                 </p>
 183                 <ul>
 184                         <li>Select
 185                                 <b>Filters...</b> from the View Menu and you will be presented with the Java Element Filters dialog. Unselect the top entry to display files that begin with . (period) such as <code>.gitignore</code>.
 186                         </li>
 187                 </ul>
 188                 <ul>
 189                         <li>Click
 190                                 <b>Team &gt; Commit</b> in the project context menu.
 191                         </li>
 192                         <li>Enter a commit message explaining your change, the first line (followed by an empty line) will become the short log for this commit. By default the author and committer are taken from the <code>.gitconfig</code> file in your home directory.</li>
 193                         <li>You may click
 194                                 <b>Add Signed-off-by</b> to add a
 195                                 <i>Signed-off-by:</i> tag.
 196                         </li>
 197                         <li>If you are committing the change of another author you may alter the author field to give the name and email address of the author.</li>
 198                         <li>Click
 199                                 <b>Commit</b> to commit your first change.
 200                         </li>
 201                 </ul>
 202                 <p>
 203                         <img border="0" src="images/Egit-0.9-getstarted-commit.png"/>
 204                 </p>
 205                 <ul>
 206                         <li>Note that the decorators of the committed files have changed as a result of your commit.</li>
 207                 </ul>
 208                 <p>
 209                         <img border="0" src="images/Egit-0.9-getstarted-commited.png"/>
 210                 </p>
 211                 <h3 id="Inspect_History">Inspect History</h3>
 212                 <ul>
 213                         <li>Click
 214                                 <b>Team &gt; Show in History</b> from the context menu to inspect the history of a resource:
 215                         </li>
 216                 </ul>
 217                 <p>
 218                         <img border="0" src="images/Egit-0.11-getstarted-history1.png"/>
 219                 </p>
 220                 <ul>
 221                         <li>Create a new Java class <code>Hello.java</code> and implement it.</li>
 222                         <li>Add it to version control and commit your change.</li>
 223                         <li>Improve your implementation and commit the improved class.</li>
 224                         <li>The resource history should now show 2 commits for this class.</li>
 225                 </ul>
 226                 <p>
 227                         <img border="0" src="images/Egit-0.9-getstarted-application.png"/>
 228                 </p>
 229                 <p>
 230                         <img border="0" src="images/Egit-0.11-getstarted-history2.png"/>
 231                 </p>
 232                 <ul>
 233                         <li>Click the
 234                                 <b>Compare Mode</b> toggle button in the History View.
 235                         </li>
 236                         <li>Double click <code>src/Hello.java</code> in the Resource list of the History View to open your last committed change in the Compare View.</li>
 237                 </ul>
 238                 <p>
 239                         <img border="0" src="images/Egit-0.11-getstarted-compare.png"/>
 240                 </p>
 241                 <p>
 242                         <br/>
 243
 244                         <b>Congratulations, you just have mastered your first project using Git&nbsp;!</b>
 245
 246                         <br/>
 247                         <br/>
 248                 </p>
 249                 <h2 id="GitHub_Tutorial">GitHub Tutorial</h2>
 250                 <h3 id="Create_Local_Repository">Create Local Repository</h3>
 251                 <ul>
 252                         <li>follow
 253                                 <a href="https://wiki.eclipse.org/EGit/User_Guide/Getting_Started" title="EGit/User Guide/Getting Started" target="egit_external">EGit/User Guide/Getting Started</a> to create a new local repository (with your content instead of the demo project).
 254                         </li>
 255                 </ul>
 256                 <h3 id="Create_Repository_at_GitHub">Create Repository at GitHub</h3>
 257                 <ul>
 258                         <li>create a new repository at GitHub:</li>
 259                 </ul>
 260                 <p>
 261                         <img border="0" src="images/Egit-0.10-github-create-repo.png"/>
 262                 </p>
 263                 <p>On the next screen you can see the URLs you may use to access your fresh new repository:</p>
 264                 <ul>
 265                         <li>click
 266                                 <b>SSH</b> to choose the
 267                                 <i>SSH protocol</i>. It can be used for read and write access.
 268                         </li>
 269                         <li>click
 270                                 <b>HTTP</b> to choose the
 271                                 <i>HTTP protocol</i>. It can also be used for read and write access.
 272                         </li>
 273                         <li>click
 274                                 <b>Git Read-Only</b> to choose the anonymous
 275                                 <i>git protocol</i> for cloning. It's the most efficient protocol git supports. Since the
 276                                 <i>git protocol</i> doesn't support authentication it's usually used to provide efficient read-only access to public repositories.
 277                         </li>
 278                 </ul>
 279                 <p>
 280                         <img border="0" src="images/Egit-0.10-github-cloneurl.png"/>
 281                 </p>
 282                 <h3 id="Eclipse_SSH_Configuration">Eclipse SSH Configuration</h3>
 283                 <ul>
 284                         <li>Open the Eclipse Preference Dialog (
 285                                 <b>Window &gt; Preferences</b>).  Navigate to and expand the Network Connections option and select SSH. Ensure that your SSH2 home is configured correctly (usually this is <tt>~/.ssh</tt>) and contains your SSH2 keys:
 286                         </li>
 287                 </ul>
 288                 <p>
 289                         <img border="0" src="images/Egit-0.10-ssh-preferences.png"/>
 290                 </p>
 291                 <ul>
 292                         <li>if you don't have SSH keys yet you may generate them on the second tab of this dialog (
 293                                 <b>Key Management</b>). Use a good pass phrase to protect your private key, for more details see
 294                                 <a href="http://help.github.com/working-with-key-passphrases/" target="egit_external">"working with key passphrases"</a>.
 295                         </li>
 296                         <li>upload your public SSH key to your
 297                                 <a href="https://github.com/settings/keys" target="egit_external">GitHub account</a> or
 298                                 <a href="https://gitlab.com/profile/keys" target="egit_external">GitLab profile</a> settings.
 299                         </li>
 300                 </ul>
 301                 <p>Further information about advanced SSH configuration (such as using Putty or another SSH agent with EGit) is available in the
 302                         <a href="https://wiki.eclipse.org/EGit/FAQ#SSH_config" title="EGit/FAQ#SSH_config" target="egit_external">EGit FAQ (section SSH)</a>.
 303                 </p>
 304                 <h3 id="Push_Upstream">Push Upstream</h3>
 305                 <ul>
 306                         <li>Click
 307                                 <b>Team &gt; Remote &gt; Push...</b> and copy and paste the SSH URL of your new GitHub repository.
 308                         </li>
 309                         <li>If you are behind a firewall which doesn't allow SSH traffic, use the GitHub HTTPS URL instead and provide your GitHub user and password instead of using the uploaded public SSH key. To store your credentials into the Eclipse secure store click
 310                                 <b>Store in Secure Store</b>.
 311                         </li>
 312                         <li>
 313                                 <b>Note:</b> many HTTP proxies are configured to block HTTP URLs containing a user name, since disclosing a user name in an HTTP URL is considered a security risk. In that case remove the user name from the HTTP URL and only provide it in the user field. It will be sent as an HTTP header.
 314                         </li>
 315                 </ul>
 316                 <p>
 317                         <img border="0" src="images/Egit-0.10-github-pushurl.png"/>
 318                 </p>
 319                 <ul>
 320                         <li>Click
 321                                 <b>Next</b> and on first connection accept GitHub's host key.
 322                         </li>
 323                 </ul>
 324                 <ul>
 325                         <li>Enter your SSH key's passphrase and click
 326                                 <b>OK</b>.
 327                         </li>
 328                 </ul>
 329                 <ul>
 330                         <li>On the next wizard page click
 331                                 <b>Add all branches spec</b> to map your local branch names to the same branch names in the destination repository (on a one-to-one basis).
 332                         </li>
 333                 </ul>
 334                 <p>
 335                         <img border="0" src="images/Egit-0.10-github-push-refspec.png"/>
 336                 </p>
 337                 <ul>
 338                         <li>Click
 339                                 <b>Next</b>. The push confirmation dialog will show a preview of the changes that will be pushed to the destination repository.
 340                         </li>
 341                 </ul>
 342                 <p>
 343                         <img border="0" src="images/Egit-0.10-github-push-preview.png"/>
 344                 </p>
 345                 <ul>
 346                         <li>Click
 347                                 <b>Finish</b> to confirm that you want to push these changes.
 348                         </li>
 349                 </ul>
 350                 <ul>
 351                         <li>The next dialog reports the result of the push operation.</li>
 352                 </ul>
 353                 <p>
 354                         <img border="0" src="images/Egit-0.10-github-pushresult.png"/>
 355                 </p>
 356                 <ul>
 357                         <li>Point your browser at your GitHub repository to see that your new repository content has arrived.</li>
 358                 </ul>
 359                 <p>
 360                         <img border="0" src="images/Egit-0.10-github-pushed-repo.png"/>
 361                 </p>
 362                 <p>
 363                         <br/>
 364                 </p>
 365                 <h2 id="EclipseCon_2012_Git_Tutorial">EclipseCon 2012 Git Tutorial</h2>
 366                 <p>Find all exercises and the slides
 367                         <a href="https://docs.google.com/open?id=0B4F_gjXVrHZVRXkydE0xVFBRRkc1WUpEcXdwQ2I1dw" target="egit_external">here</a>.
 368                 </p>
 369                 <p>Follow the
 370                         <a href="https://docs.google.com/document/d/1UCbNCvljiInc6-vwBsHHzOQ1ItC10f1bFAOi8T30DJ8/edit" target="egit_external">exercise #1</a> to prepare for the Git Tutorial.
 371                 </p><hr class="navigation-separator"/>
 372                 <table class="navigation" style="width: 100%;" border="0" summary="navigation">
 373                         <tr>
 374                                 <td style="width: 20%" align="left"></td>
 375                                 <td style="width: 60%" align="center"></td>
 376                                 <td style="width: 20%" align="right">
 377                                         <a href="Concepts.html" title="Concepts">
 378                                                 <img alt="Next" border="0" src="../../images/next.gif"/>
 379                                         </a>
 380                                 </td>
 381                         </tr>
 382                         <tr>
 383                                 <td style="width: 20%" align="left" valign="top"></td>
 384                                 <td style="width: 60%" align="center"></td>
 385                                 <td style="width: 20%" align="right" valign="top">Concepts</td>
 386                         </tr>
 387                 </table>
 388         </body>
 389 </html>