Permalink
Find file
b19a603 Jun 22, 2012
276 lines (233 sloc) 16.4 KB

How to install and configure the EGit plugin for Eclipse (and LassoLab) to work with the Knop Project on GitHub

EGit is a plugin to use git within any Eclipse-based IDE, including LassoLab. This document covers the process to install and configure the EGit plugin for LassoLab/Eclipse. In addition, you can use the EGit plugin to work with GitHub Issues (a public bug tracker), Gists (a code snippet sharing tool), and Pull Requests (a method to submit contributions to a project). We'll use the Knop Project on GitHub for this document.

This document is a companion to a video on YouTube by Steve Piercy, Install and configure the EGit plugin for Eclipse/LassoLab to work with the Knop Project on GitHub.

In LassoLab/Eclipse, there are many ways of doing the same thing. You can use menus, CTRL-click or right-click on an item to get a contextual menu, click on buttons in toolbars, or map keyboard shortcuts to specific functions. We'll use menus as they tend to be the easiest to locate.

We will also use the internal web browser in LassoLab/Eclipse for browsing the web, and maximize and minimize that view as needed. Here is one way to open the internal web browser:

  • Select Window > Show View > Other....
  • Filter: web.
  • Select General > Internal Web Browser.
  • Click button: OK.

Pre-requisites

Before you begin, you must do the following:

  • install and set up git
  • create your own free GitHub account
  • generate your SSH keys
  • enter your public SSH key into your GitHub account

See Git and GitHub Installation and Configuration Guide for complete instructions.

Install the EGit plugin

  1. Select menu Help > Install New Software.... A new window "Install" appears.
  2. Click button: Next >.
  3. Select "I accept the terms of the license agreement".
  4. Click button: Finish.
  5. Click button: Restart Now. LassoLab will relaunch.

Fork the Knop Project

Next we need to fork the Knop Project repository into our own account.

  1. While logged into your GitHub account, go to the following URL:

    https://github.com/knop-project/knop

  2. Click the Fork button. GitHub indicates "hard core forking action" takes place, then takes your to your fork in your account.

Clone your fork

After you have forked the Knop Project repository, you will have your own copy under your account. Now we're going to take your fork and clone it to your local computer. First we need to copy the URI of your fork.

  1. Click on the SSH button in your GitHub fork.

  2. Copy the URI to the clipboard.

  3. Select Window > Open Perspective > Other.... A slide-down pane appears.

  4. Select Git Repository Exploring

  5. Click button: OK. The Git Repository perspective opens.

  6. Select the Git Repositories view to make it active.

  7. Paste the URI you copied from Git. A new wizard "Clone Git Repository" appears with most of the information auto-populated. Complete required information for Source Git Repository.

    • URI: git@github.com:MYACCOUNT/knop.git
    • Host: github.com
    • Repository path: MYACCOUNT/knop.git
    • Connection > Protocol, select: ssh.
    • User: git.
    • Password: enter your password.
    • Check: Store in Secure Store.
    • Click button: Next >. The next step "Branch Selection" appears.
  8. Select the master branch.

  9. Click button: Next >. The next step "Local Destination" appears.

  10. Now you can browse to put the project anywhere on the file system. You can put it in your web root, your user directory, whatever is most familiar and convenient for you and your workflow. For the purpose of this tutorial, we will put it in the web root for Mac OS X and give it a unique name.

    /Library/WebServer/Documents/knop-project
    
  11. Click button: Finish >. Your fork will be cloned to your local computer, and will appear as a repository.

Configure remotes for your clone

Next we need to configure remotes to pull down upstream changes from the Knop Project's repo. EGit's UI is overly complex for this step, so we'll bypass it and directly edit the repository's configuration file.

  1. In the Git Repository view, navigate to knop-project > Working Directory > .git.

  2. Open the file config.

  3. Copy and paste the following three lines of code into the end of your git config file.

     [remote "upstream"]
     	url = git@github.com:knop-project/knop.git
     	fetch = +refs/heads/*:refs/remotes/upstream/*
    
  4. Save and close the file.

Create a new project in LassoLab/Eclipse for your clone

Finally we need to add the cloned local git repository into a new project in our workspace. Let's create a new Lasso project.

  1. Switch to the Lasso perspective.
  2. Select File > New... > Lasso Project. A new window "Create Lasso 9 Project" appears, with the initial step "Create a Lasso 9 project".
  3. Enter the following information.
    • Project name: knop-project
    • Under Contents, select Create project at existing location (from existing source).
    • Host: Localhost.
    • Directory: You can either enter the location or click the button Browse... to locate the directory that contains your local clone.
    • Click button: Next >. The next step "Script Settings" appears.
  4. Within the root directory knop-project, select all the folders marked with a small brown "source" icon.
    • docs
    • knop8/demo
    • knop8/LassoLibraries
    • knop8/LassoStartup
    • knop8/source
    • knop9/demo
    • knop9/knoplibs
    • knop9/LassoStartup
  5. Click the toolbar button: Remove from Build Path.
  6. Select the root directory knop-project.
  7. Click the toolbar button: Use as Source Folder.
  8. Select the directory .git.
  9. Click the toolbar button: Exclude.
  10. Click button: Finish.

Enable EGit menu and toolbar items

To facilitate working with EGit in LassoLab/Eclipse, it helps to enable menu and toolbar items. You can also set up keyboard shortcuts to perform routine tasks, such as commit and push.

Note that sometimes the settings for EGit in LassoLab/Eclipse do not always take effect, so you may need to toggle settings back and forth or even restart LassoLab/Eclipse.

  1. Make sure you start from the Lasso perspective.
  2. Select Window > Customize Perspective.... A new window "Customize Perspective - Lasso" appears.
  3. Click tab: Command Groups Availability.
  4. Under Available command groups:, check the following:
    • Git
    • Git Navigation Actions
  5. Click tab: Menu Visibility.
  6. Under Menu Structure:, uncheck, then check again, the following:
    • Git
  7. Click tab: Tool Bar Visibility.
  8. Under Tool Bar Structure:, uncheck, then check again, the following:
    • Git
  9. Click button: OK.

Now you're ready to start doing some work.

Modifying and contributing to the Knop Project

You can use EGit essentially as you would use git from the command line, but using a graphical user interface. The process is similar to that in the guide Using git with the Knop Project.

  1. Update your local repo. Before you start working on your local files, you should pull down all updates from the upstream repo to your local repo, and merge any changes into your working files.
    • Fetch any new changes from the original repo. Select Git > Fetch from Upstream.
    • Merge any changes fetched into your working files. Select Git > Pull.
  2. Create a branch. Branching allows you to test an idea or add new features to the project. Let's create a branch (MYBRANCH or whatever you like) and begin working in it.
    • Select Git > Switch to.... A new window "Branches" appears.
    • Click button New branch.... A new window "Create Branch" appears.
    • Select Source ref: refs/remotes/origin/master.
    • Branch name: MYBRANCH
    • Select Pull strategy: Merge.
    • Check Checkout new branch.
  3. You can switch between branches at any time and determine on which branch you are currently working.
    • Select Git > Switch to.... A new window "Branches" appears. The current branch is indicated with a white checkmark in a tiny black square.
    • Select a branch without the white checkmark. The button "Checkout" is enabled.
    • Click button: Checkout. When you edit files, changes are tracked according to whichever branch is current at that time. Thus you should always switch to the branch where you want to do your code editing before editing code.
  4. Once you are done editing files, you need to stage them (add them to the index) and commit them with a message.
    • Select Git > Commit.... A new window "Commit Changes" appears.
    • Enter a Commit message.
    • Click button: Commit.
  5. Next, push your branch from your clone up to your fork on GitHub.
    • Select Git > Push to Upstream. A new window "Push Results: knop-project - origin" appears. It displays information about what will be pushed.
    • Click button: OK.
  6. Finally, to contribute your changes to the Knop Project, submit a pull request through the GitHub website. The project administrators will review your request. Read details of how to use pull requests.

If you like to write documentation or produce demo videos, then you can contribute your work to the Knop Project. The Knop Project's documentation uses the Markdown syntax, which GitHub supports.

Steve Piercy produced a brief video of how to configure BBEdit to do syntax highlighting for the Markdown markup language and how to preview your changes in real-time.

BBEdit and Markdown syntax

GitHub Issues

You have already installed this component when you installed the EGit plugin. First let's configure our GitHub Issues Repository.

  1. Select Window > Show View > Other....
  2. Filter: task r.
  3. Select Mylyn > Task Repositories.
  4. Click button: OK. A new view "Task Repositories" appears.
  5. CTRL-click or right-click in the Task Repositories view, and select Add Task Repository.... A new wizard "Add Task Repository..." appears, with the initial step "Select a task repository type".
  6. Select: GitHub Issues.
  7. Click button: Next >. The next step "GitHub Issue Repository Settings" appears.
  8. Configure settings for the GitHub Issue repository:
    • Server: http://github.com/knop-project/knop.
    • Label: knop-project/knop issues (auto-entered, but you can change it).
    • User ID: enter your GitHub account.
    • Password: enter your GitHub password.
    • Optionally check Save Password.
    • Click button: Validate Settings. Either an error or success message will appear at the top of the wizard.
    • If successful, click button: Finish. A new window "Add new query" appears.
  9. To display and work with the issues in the task repository, we need to create a query to find the issues. When you first create a task repository, you will be prompted to create a query, so let's do that now. Click the button Yes. A new window "Edit Query" appears.
  10. Configure your query. Note: the UI to the filters is misleading. The checkboxes for labels actually perform an AND search, not an OR search. Therefore to view all items, select no labels.
    • Title: All Knop Project Issues.
    • Click button: Finish.
  11. Select Window > Show View > Other....
  12. Filter: task l.
  13. Select Mylyn > Task List. The view "Task List" appears with your recently created query.

From this point you can now view and work with the Knop Project Issues in LassoLab/Eclipse or through the GitHub website. Depending on your permissions, you will have different features enabled.

GitHub Gists

A Gist is a simple way to share snippets and pastes with others. All gists are git repositories, so they are automatically versioned, forkable and usable as a git repository.

To configure a GitHub Gist repository, follow steps 1-5 for GitHub Issues above, then proceed as follows.

  1. Select: GitHub Gists.
  2. Click button: Next >. The next step "GitHub repository settings" appears.
  3. Configure settings for the GitHub Gist repository:
    • Server: https://gist.github.com (auto-entered).
    • Label: Gists (auto-entered, but you can change it).
    • User ID: enter your GitHub account.
    • Password: enter your GitHub password.
    • Optionally check Save Password.
    • Click button: Validate Settings. Either an error or success message will appear at the top of the wizard.
    • If successful, click button: Finish. A new window "Add new query" appears.
  4. To display and work with the Gists in the task repository, we need to create a query to find the issues. When you first create a task repository, you will be prompted to create a query, so let's do that now. Click the button Yes. A new window "Edit Query" appears.
  5. Configure your query.
    • Title: My Gists.
    • User: enter your GitHub account.
  6. Select Window > Show View > Other....
  7. Filter: task l.
  8. Select Mylyn > Task List. The view "Task List" appears with your recently created query.
  9. To create a Gist:
    • Open or create a new file in the project.
    • Select either the file itself or a section of code in the file.
    • CTRL-click or right-click on the selection, and select either GitHub > Create Public Gist or GitHub > Create Private Gist. A new Gist is created in the Task List.
  10. To open a Gist, double-click it. Its repository appears.
  11. Under Files > Name, double-click the name of the file to open it.

From this point you can now view and work with all of your Gists in LassoLab/Eclipse or through the GitHub website.

GitHub Pull Requests

A Pull Request is a notification you send to a project maintainer to update their repository. EGit supports the display and opening of Pull Requests. As of this writing, EGit does not support the creation of Pull Requests. However you can use GitHub's website through the internal web browser of LassoLab/Eclipse to submit a Pull Request.

To configure a GitHub Pull Request repository, follow steps 1-5 for GitHub Issues above, then proceed as follows.

  1. Select: GitHub Pull Requests.
  2. Click button: Next >. The next step "Pull Request Repository" appears.
  3. Configure settings for the GitHub Pull Request repository:
    • Server: http://github.com/knop-project/knop.
    • Label: knop-project/knop issues (auto-entered, but you can change it).
    • User ID: enter your GitHub account.
    • Password: enter your GitHub password.
    • Optionally check Save Password.
    • Click button: Validate Settings. Either an error or success message will appear at the top of the wizard.
    • If successful, click button: Finish. A new window "Add new query" appears.
  4. To display and work with the Pull Requests in the task repository, we need to create a query to find the issues. When you first create a task repository, you will be prompted to create a query, so let's do that now. Click the button Yes. A new window "Edit Query" appears.
  5. Configure your query.
    • Title: Knop Project Pull Requests.
    • Status: check both Open and Closed.
    • Click button: Finish.
  6. Select Window > Show View > Other....
  7. Filter: task l.
  8. Select Mylyn > Task List. The view "Task List" appears with your recently created query.
  9. To open a Pull Request, double-click it in the Task List.

More Information