Using Github with Adobe and Aptana
Git has become a popular source code management system, and Github has contributed to its continually gaining popularity.
Though there is a learning curve, using basic features of Git is pretty intuitive, especially with several of the freely available tools available today. However; getting your environment configured to work with Github can be a test of patience.
This guide is relevant to any Eclipse-based IDE, but for demonstration purposes, I'll be showing how to connect Adobe ColdFusion Builder 2 to Github. This guide should also work for Adobe Flash Builder, CFEclipse, or any other Eclipse-based IDE.
There are many ways to accomplish this task, but I've chosen to incorporate Aptana Studio 3 into my Adobe development environments. Aptana Studio is known as a Rails-oriented plug in for Eclipse, but I started using it for it's strong JavaScript support. It happens to have one of the more straightforward Git connectors.
Install Aptana for ColdFusion Builder
For this guide, it does not matter whether you've installed ColdFusion Builder as a standalone product or as an Eclipse plug in. Both versions run on Eclipse, meaning both have the ability to install Eclipse plug ins.
Your installation must be in a location with local administrative privileges, or at least healthy write privileges. In my first attempt, I tried installing ColdFusion Builder on a Windows 7 system controlled by Active Directory. While I was able to install everything with elevated privileges, I could not run it with elevated privileges. As a result, everything appeared to work, until trying to sync with Github. At this point, it simply failed to sync with permission issues. If anyone has insight on how to fix that with an unprivileged account, I'd love to hear about it.
The simplest way to install Aptana Studio is through the Eclipse update feature. In ColdFusion/Flash Builder, this is found under:
Help → Install New Software
This brings up the installation screen. You'll need to add the Aptana Studio update site to the list by clicking on the Add button. Provide a name and the location of the update site as shown below:
Location: http://download.aptana.com/studio3/plugin/install
If prompted, restart ColdFusion Builder.
**With some installations, I've had some issues using the “Apply Changes Now” option.**
Aptana may prompt you to install msysgit, which will work, but I recommend using the Setup Git page for installing Git on your computer anyway. There may be times, especially while learning, where you may wish to use Git from the command line. It is also helpful in creating the SSH keys you'll need to connect to Github. Regardless of your choice, you should be able to create local Git repositories at this point.
For those new to Git, it is a source code management system. It works differently from CVS, Subversion, or SourceSafe. One important note is that you cannot directly connect to remote/hosted repositories like Github/BitBucket. All communication with these remote repositories is handled by a local repository stored on your computer. Aptana Studio and other Git tools help by auto-creating local repositories as well as communicating with remote repositories.
Connecting your project to Git
Right-click on the project you want to associate with Git and select
You'll be prompted for a repository type, which should be Aptana Git.
Next, the wizard will help create a local Git repository.
Select the Project and click the Create button. This will create your local Git repository. Then click finish. At this point, you've created your first Git repository! Now it's time to clean things up so our repository stays tidy.
Git uses a file called .gitignore to prevent certain files/directories from being included in your repository. It's typically good form to not include your .gitignore file in your repository, so step one is to make it ignore itself. Ignoring files and directories is pretty straightforward. Simply right click the file name and
It may be desirable to add wild card entries to your .gitignore file as well. For example, Eclipse users will be familiar with the .project file, and you may also see a .git directory in your project. I find it useful to ignore every file/directory in my project, as well as files that aren't relevant to my project (like .thumb). Gitignore, which is just a text file, can be edited to support wild cards. You can add the following:
This would ignore all files/directories that start with a dot or underscore, such as .project, .git, or _NOTES. It will also ignore the XML metadata settings file most Adobe products use to manage a project. As a result, these files will not end up in your remote project repository.
Github is just one of several Git services, but it is extremely popular. It's free for open source projects and inexpensive for private projects. BitBucket is an alternative that has free open and private projects in addition to a commercial service. Setup between the two is similar, but we'll stick to Github for this tutorial.
First, you must have a personal Github account, so sign up for a free account. Next, you'll need an SSH key to connect with your repositories. You'll need an SSH key on every computer you work on. Github allows you to add multiple keys, so I have repeated the same process on my laptop, desktops, and workstations.
The simplest and most common way to create an SSH key and add it to your Github account is described in detail at http://help.github.com/win-set-up-git/. This is the recommended method.
If you haven't already, create a Github repository. This is done from the Dashboard of your Github account:
I recommend starting with a free open source repository until you're comfortable with how everything works.
Connecting Your Project to Github with Aptana
At this point, you should have a Github repository created on Github.com and a local repository associated with your project. It's time to tie the two of them together.
The Aptana plug in provides a menu option for adding a remote repository, but I have had limited success with this. Therefore, I'm going to show how to manually configure a remote connection to Github.
Manual Remote Repository Configuration
In your project directory, you should see a .git directory. If you're working on a Mac, this directory may be hidden. This directory contains a file called config, which needs to be modified. When you open the file, you will see a core attribute only. We need to add a remote connection and identify the master branch, as shown below. For copy/paste purposes, I've provided a demo config below:
repositoryformatversion = 0
hideDotFiles = dotGitOnly
fetch = +refs/heads/*:refs/remotes/test/*
merge = refs/heads/master
Save this file and you're done.
Assuming you followed this guide and configured everything correctly, you should be able to push and pull from your remote repository. However; you first need to commit changes to your local repository. Remember, all interaction with a remote repository is done through your local repository. If there are no changes committed to your local repository, then no changes will be pushed to your remote repository. The advantage of doing this is you can make as many changes as you like before sharing with other developers. That means you can screw up and fix as much as you like before ever publishing to the world.
Once you've added some files to your project and are ready to push them to Github, right-click on the project and go to
You will need to stage any/all changes you've made and add a message, as shown below:
Click on the Commit button to save your changes in your local Git repository.
Now you can push your changes to Github. To do this, right click on the project and go to:
Select the remote repository that was configured in prior steps.
Once you push to the remote repository, you should see progress in the output console (if you have it open). Please note that the first time you push to a remote repository, it may be quite slow. You will also be prompted to accept the RSA fingerprint from Github (which you must do). This will add Github to your Known Hosts file if it isn't already there.
Finally, go check out your Github page. You should see your code there.
Now that you have a project working with Github, you should start to use the features and get familiar with it. Browse the documentation the Github website. Github has several interesting hooks and features that make it useful. A common feature is the Readme.md file. Github uses “Github Flavored Markdown” to create visually appealing documentation. If a Readme.md file is found in your project root, it will automatically be displayed on the page. This is how many developers provide introductory notes about their project for the community. Of course this can be expanded through use of the wiki or pages.
I anticipate covering Github issues and how to integrate Github issue management directly into ColdFusion/Flash/Eclipse Builder in an upcoming post.
Please let me know if you find this useful!
Feel free to find me on Github.
