Eclipse Che natively supports Git which is provided by JGit library. Versioning functionality is available in the IDE and in the terminal. Note: an SVN plugin also exists, but it’s not part of the default Che assembly.

The following sections describe how to connect and authenticate users to a remote git repository. Any operations that involve authentication on the remote repository will need to be done via the IDE interface unless authentication is setup separately for the workspace machine(terminal/commands).

Private repositories will require a secure SSH connection and most developers who plan to push to a repo will clone it via SSH, so an SSH key pair needs to be generated. SSH keys are saved in user preferences, so you need to generate the SSH key only once and it will be used in all workspaces.

Note: HTTPS git URL can only be used to push changes if you enable oAuth authentication as described in GitHub oAuth.

Generate/Upload SSH Keys

SSH keys can be generated at Profile > Preferences > SSH > VCS. Use the Generate Key button and manually save the resulting key to your Git hosting provider account. When prompted to provide the hostname for your repo, make sure it is a bare hostname (no www or http/https) as in the example below. After the key has been generated, you can view and copy it, and save to your repository hosting account.

IMPORTANT!. Hostname is an actual hostname of a VCS provider. Examples: github.com, bitbucket.org.

Use Existing SSH Keys

You can upload an existing public key instead of creating a new SSH key. When uploading a key add the hostname (using no www or http/https - as in the example below). Note that the public key > view button will not be available with this option as the public file should be generated already.

ssh keys

The following example is specific to GitHub and GitLab but can be used with all git or SVN repository providers that use SSH authentication. Please refer to documentation provided by other providers for additional assistance.

GitHub Example

If you don’t want to setup GitHub oAuth, you can manually upload a key. Add the associated public key to a repository/account using github.com, click your user icon(top right) then settings > ssh and gpg keys > new ssh key. Give a title to your liking and paste the public key copied from Che into form.

ssh github

GitLab Example

To add the associated public key to a git repository/account using gitlab.com click your user icon(top right) then Profile Settings > SSH Keys. Give a title to your liking and paste the public key copied from Che.

ssh gitlab

BitBucket Example

You can setup ssh to a dedicated BitBucket Server. Each user will still need to setup their own SSH key for authentication to the BitBucket Server which will be similar to GitHub/GitLab SSH examples.

GitHub oAuth

oAuth for Github allows users via the IDE git menu to import projects using SSH "git@", push to repository, and use pull request panel. To enable automatic SSH key upload to GitHub for users, register an application in your GitHub account Settings > Developer Settings > oAuth Apps with the callback http://${CHE_HOST}:${CHE_PORT}/api/oauth/callback:

github oauth

SINGLE-USER ONLY!. See: Setup GitHub oAuth for Multi-User Che

Set the following to environment variables in the che.env (See: Docker Config) or update your Che OpenShift deployment (See: OpenShift Config).

CHE_OAUTH_GITHUB_CLIENTID=your_github_client_id
CHE_OAUTH_GITHUB_CLIENTSECRET=your_github_secret
CHE_OAUTH_GITHUB_AUTHURI=https://github.com/login/oauth/authorize
CHE_OAUTH_GITHUB_TOKENURI=https://github.com/login/oauth/access_token
CHE_OAUTH_GITHUB_REDIRECTURIS=http://${CHE_HOST}:${CHE_PORT}/api/oauth/callback

Once the oAuth is setup, SSH keys are generated and uploaded automatically to GitHub by a user in workspace IDE Profile > Preferences > SSH > VCS by clicking the 'Octocat' icon. You can connect to your GitHub account and choose repos to clone, rather than manually type (or paste) GitHub project URL.

GitLab oAuth

Currently it is not possible for Che to use oAuth integration with GitLab. Although GitLab supports oAuth for clone operations, pushes are not supported. You can track this GitLab issue in their issue management system.

Built-In Pull Request Panel

Within Eclipse Che there is a pull request panel to simplify the creation of pull requests for GitHub, BitBucket or Microsoft VSTS (with git) repositories.

pr panel

Committer Name and Email

Committer name and email are set in Profile > Preferences > Git > Committer. Once set each commit will include this information.

Git Workspace Clients

After importing repository, you can perform the most common Git operations using interactive menus or as terminal commands. Terminal git commands require its own authentication setup, which means that keys generated in the IDE will work only when Git is used in the IDE menus. Git installed in a terminal is a different git system. You may generate keys in ~/.ssh there as well.

git

To faster access to the most frequently used git functionality one can use keyboard shortcuts:

  • Commit: Alt + C

  • Push to remote: Alt + Shift + C

  • Pull from remote: Alt + P

  • Work with branches: Ctrl + B

  • Compare current changes with the latest repository version: Ctrl + Alt + D

Git in Project Tree and Editor

Files in project explorer and editor tabs can be colored according to their Git Status:

project explorer editor tabs git colors
  • Green: new files that are staged in index.

  • Blue: files that contain changes.

  • Yellow: files that are not staged in index.

Editor displays change markers according to file edits:

editor git change markers
  • Yellow marker: modified line(s).

  • Green marker: new line(s).

  • White triangle: removed line(s).

Git Operations

Commit

Commit your changes at GitCommit…​ main menu or call it with Alt + C shortcut.

git commit tree view

You can select files which will be added to index and committed. All files in the selected package / folder in the project explorer will be checked by default. After selecting files, type commit message. Optionally you could select Amend previous commit to replace previous commit (for more details see git docs).

Push your commit to a remote repository by checking Push committed changes to check-box and selecting a remote branch.

Click Commit to proceed (the Commit button is active as long as at least 1 file is selected and a commit message is present or Amend previous commit is checked).

Behavior for files in the list view is the same as in compare window (see Reviewing changed files section). Double clicking a file will open diff window with it.

Push/Pull

Push your commits at GitRemotes…​Push from main menu or Alt + Shift + c shortcut.

git push

Choose a remote repository, local and remote branch. Optionally, you can force Force push. Get changes from a remote repo at GitRemotes…​Pull (Alt + P shortcut).

git pull

You can use Rebase instead of merge to keep your local commits on top (for more information see git docs).

Branches

Manage your git branches at GitBranches…​ from main menu or Ctrl + b shortcut.

git branches window

You can filter branches view by choosing to see only local or remote branches.

Compare

Git compare window is used to show files which was changed. This widget could be invoked from different places for different states, but the most frequently used way is to use GitCompare<Select-to-what> from main menu or use Ctrl + Alt + D shortcut to compare current state of code to the latest local commit. Another way is to select an object in project tree and click GitSelect-to-what from item’s context menu. Note, this widget shows changed files in the selected object in project explorer. To see all changes select project folder. Note, if only one file was changed, diff window will be shown instead of compare window.

git compare tree view

By default, affected files are listed as a tree.

Expand all directories and Collapse all directories will help you get a better view. View as list button switches the view of changed files to a list, where each file is shown with its full path. To return to the tree view just click Group by directories.

git compare list view

To view diff for a file, select it and click Compare or just double click on a file name.

You can review changes between two states of code. To view the diff, use Git→`Compare`→`<Select-to-what>` from main menu. If more than one file has changed the list of changed files will be opened first. To select a file to compare double-click on it or select a file, then click the Compare. Another way to open diff is to select a file in project explorer and click GitSelect-to-what from context menu or directly from editor’s context menu.

git diff widget

Your changes are displayed in the left editor and the file being compared to is on the right. The left editor can be used for editing and fixing your changes.

When you have multiple files to review you have the ability to navigate under all the files that are changed. The number of files that are reviewable is displayed in the title of the wizard. Navigate to the next or previous file with Next and Previous buttons.

For a keyboard navigation between the files you can use: Alt + . for Next and Alt + , for Previous.

The Refresh button updates difference links between editors.

SVN

SVN plugin isn’t included in the default Che build. You can, however, build your own Che assembly with this plugin.