Its almost Christmas time and that means presents.

It also means that sometime between today and December 25th you need to go out and buy other people some presents because you haven’t done it yet.

But there’s someone else special in your life that deserves an Xmas gift this year. That special someone is your open source projects.

You might think, “But, Dr Nic, what do I get for the open source project that already has everything? What gift would my open source projects possible appreciate?”

Its true – this year has been a boon for open source. You probably migrated your projects from SVN to Git this year. Specifically, you probably clicked the “create a new one” link on your GitHub home page a lot this year: either to migrate your old projects to github or start new ones. Lots of new ones.

And now that your code is on github, your README file is rendered beautifully on the home page, so you were more inclined to rename it to README.markdown or README.textile and thusforthly fill it full of education information about your projects.

More people would then instantaneously figure out what the f@#$ your project actually does, thus more people used it, thus more people wrote patches or forked your code and sent Pull Requests.

All round, in 2008, I bet your open source projects had a sweet year.

Nonetheless, it is Christmas time and you should now get them a present. Something they wouldn’t get for themselves. Something you wouldn’t have done for them except for the free loving spirit of Christmas.

The Gift for all Open Source projects

A website.

Oh sure, github renders your README.markdown file. Yeah, yeah, github gives you a wiki for your project. Sure, sure, Google Groups let you communicate with your co-developers and users. Certainly, you don’t need a website for your project.

That’s why its a Christmas gift. You’re going to do it because you care.

Websites sell your project. READMEs and Wikis educate. The project website will sell it and make people want to use your stuff.

A website could have a blog with an RSS/atom feed. Then you could post updates about your project. People could subscribe and also leave comments. Oh the novelty.

And if it only took 5 minutes to get all this setup – the website code, the blog engine, the RSS feed, the comments, and published to its own hosted server – then that would just be oh so sweet.

So we’re going to do some craft for our Xmas present. A little DIY project, if you will. You’ll need a few things that you’ll find around your house, a command-line interface, and a beer or perhaps some port or sherry. Christmas cake is good too.

The commands below take about 5 minutes to execute and you’ll have a sweet website for your project, setup on GitHub Pages, just like the macruby-tmbundle and jekyll_generator sites, and the sample image above.

Jekyll and GitHub Pages

Jekyll, by Tom Preston-Werner, is one of several static website generators. All your website content will be written in textile or markdown, rendered against some HTML layouts, and published on a website somewhere. We’re going to use GitHub Pages because they are new and shiny, and free, and I’ve written some sake tasks (below) to make it all easy peasy to get up and running.

There are a bunch of reasons we’re going to use Jekyll to render our website:

One, textile and markdown are much nicer to write/edit text than HTML.

Two, Jekyll is “blog enabled”. That is, some of your pages will be specifically “blog post” pages, and elsewhere in your layout you can programmatically list them. Like a blog. Yeah.

Three, GitHub Pages automatically supports Jekyll but no other static-website generators. This saves you from having to manually render your HTML from your Textile/Markdown pages before pushing the site to the remove server.

Four, I wrote a stand-alone generator to create a Jekyll website for any project. It is preconfigured with Disqus for comments, including badges for latest comments etc.

Living with a Jekyll

Jekyll comes as a RubyGem:

sudo gem source -a http://gems.github.com/
sudo gem install mojombo-jekyll

You can either read the Jekyll README and create your project website by hand (and then skip below to Living with GitHub Page).

Alternately, you can cheat and use a generator.

jekyll_generator

For the last few years, newgem has come with the ability to create a website for your project. For the jekyll_generator I decided to go with a separate generator so that any project – rubygem, rails plugin, javascript project, etc – can easily use it.

sudo gem install jekyll_generator
cd path/to/project
jekyll_generator website --title "Project Name"
cd website
jekyll
open _site/index.html

The final steps performs the local rendering of your website (jekyll) and then on OS X it opens the rendered website into your browser. Otherwise, manually open the index.html from the _site folder.

Currently the generator assumes that your project is already in a git repository that is hosted on github (specifically that you’ve added the github project as the origin remote).

Living with GitHub Pages

GitHub recently released GitHub Pages as a place for you to publish a personal website and websites for each of your projects. Instead of requiring you to rsync or “rake website” your way to publishing glory, you just use git.

Specifically, you put your website in a branch called “gh-pages”. When you push commits in that branch to github it will automatically refresh your website. No rsyncing required. Also, it will run your website through Jekyll.

So much delicious magic.

Except our website is not currently in another branch. Its in master. In a folder called website. Where it should be.

But the boffins at github say we need to move our shit across to a branch called gh-pages, and who are we to argue.

I personally will never be doing this migration manually. I figured it out once and slapped it into a sake task. It moves all the content in your website folder into this branch, and replaces it with a submodule link so you can access the website from your master branch. Didn't follow that? No, me neither. Let's just run the sake task and move on with our lives, and eat fresh prawns and Christmas pudding.

Sake tasks to get started with GitHub Pages

To install them from scratch (initial blog post):

sudo gem install sake
cd /tmp
git clone git://github.com/drnic/sake-tasks.git
cd sake-tasks
rake install:all

You can toss away the repo after installing the sake tasks.

You now have some tasks to manage github:pages:

sake github:pages:migrate_website   # Migrates an existing website folder into a gh-pages branch, and links back as submodule
sake github:pages:setup             # Creates the gh-pages branch, and links to it as 'website' as submodule

Since we've already created the website above, we're going to use the first task to migrate this folder into the required gh-pages branch.

sake github:pages:migrate_website

Um, and your done.

Note, if sake crashes and burns in your project it might be that you don't have a Rakefile. Try, "touch Rakefile" and rerun the sake command.

In 1-10 minutes your fancy new site will appear at http://username.github.com/projectname. It even has a complimentary first blog post. You might want to change it to something useful.

You can now update your website via your website folder, commit changes and they automatically appear, automatically rendered via Jekyll, on your website.

Disqus for comments

Since your new website is static text there is no way to support comments on the blog posts. I've bundled into the theme's layouts the access code for Disqus. Like the image above, each blog post has Disqus comments at the bottom, and the sidebar shows the latest comments from all your blog posts.

You need to create a Disqus account, and create a project with the same name as your github project name. For example, if jekyll_generator is the project name on github, then make it the name on Disqus.

In my example above, my github project name was jekyll_generator but I couldn't use underscores on Disqus, so it is jekyll-generator. Fortunately, the generator templates already know this, and have converted your underscored name to hyphens already.

You can skip the "Choose your platform to install" steps as this is all done by the generator templates.

If you reload your project's website it should have Disqus badges on the sidebar, and the posts should have comment boxes.

Lighthouse for tickets

Lighthouse offers free access for open source projects to track their bugs. After you've created your Lighthouse project, you need to change the TODO values in _layouts/default.html and _layouts/post.html to your Lighthouse project number.

Updating your website

Your website now appears within your project source under the website folder. Though if you change it, add new posts, etc, you won't be able to commit the changes back normally. The contents of the website folder are effectively another git repository.

To commit changes to your website, go into the website folder and proceed normally:

project(master) $ cd website
project/website(gh-pages) $ git commit -m "some changes"
project/website(gh-pages) $ git push origin gh-pages
project/website(gh-pages) $ cd ..
project(master) $

Now your submodule may be dirty and need updating:

git submodule update --init

Not sure what this is all about.

Summary

A website is a great way to show that your pride and joy isn't ignored by new visitors and reminds existing users just how awesome the project is, and by clever association, how awesome you are.

A sexy website has to be even better.

Jekyll is great, and the Github Pages concept seems fun. Perhaps it wouldn't be necessary if the Github Wiki content was available as its own git repo, or if you could theme your project's source browser like a diry MySpace page.

Hopefully the sake tasks make migration of any existing websites to the Github Pages system easy peasy, and hopefully the jekyll_generator is useful for any new projects.

Hopefully.

Merry Christmas.

Related posts:

1. Hacking someone’s gem with github and gemcutter Ever used a rubygem, found a bug, and just...
2. newgem 1.0.0 all thanks to Cucumber The New Gem Generator (newgem) was exciting, moderately revolutionary, and...
3. My attempt at sake task management I’ve used sake intermittently in my workflow. It competes...

Now you can instantly navigate from that erroneous line to the git commit where it was added, and then using github’s commenting system add a full-flavoured remark about that person’s code. I’m not sure if profanity is against the GitHub Terms of Service, but I’d rather ask forgiveness than permission.

TextMate + GitHub – how to comment/discuss on a line via GitHub from Dr Nic on Vimeo.

Download and installation instructions are available in all good bookstores.

Just for TextMate?

There is an editor for Windows – E-TextEditor – that was designed to support TextMate bundles. So far, the GitHub bundle doesn’t use any special features of TextMate’s latest-and-greatest UI libraries, so it should be usable on E-TextEditor.

Also, a VIM project has been created to port the GitHub bundle, by Christoph Blank. Cristoph can be found hanging around #hobo on irc as ’solars’, if you want more goodies in the VIM bundle.

Related posts:

1. Migrating project websites to github pages with sake tasks, new websites with jekyll_generator Its almost Christmas time and that means presents. It...
2. TextMate easter egg: find bundle commands by key combo I’ve dreamed of the ability to ask TextMate “what frigging...
3. Using Ruby within TextMate snippets and commands I didn’t know you could run Ruby within TextMate snippets....

Finally, I wanted to make a nice little video to show off the new GitHub.tmbundle.

TextMate and GitHub: Show the current file in GitHub from Dr Nic on Vimeo.

Which remote repository is it choosing?

If you have multiple remote references to github.com repositories, then the algorithm picks one in the following order:

1. A remote named ‘github’
2. A remote named ‘origin’
3. The first remote for a github.com repository

What else could go in a GitHub textmate bundle?

Related posts:

1. Migrating project websites to github pages with sake tasks, new websites with jekyll_generator Its almost Christmas time and that means presents. It...
2. TextMate easter egg: find bundle commands by key combo I’ve dreamed of the ability to ask TextMate “what frigging...
3. Using Ruby within TextMate snippets and commands I didn’t know you could run Ruby within TextMate snippets....

The killer app for JavaScript in the 90s was to take a perfectly readable sequence of words – aka “a sentence” – and turn every single character a different colour. You did that, then you went back to doing normal work.

The killer app for JavaScript in the 00s is widgets/badges. Taking perfectly useful stuff from one website – aka “data” – and re-posting it on your blog sidebar.

In both circumstances, across two decades, you did this to look cool. Sure, it never works but you do it anyway.

Thusly, riding high on the world-dominating success of GitHub there seems to be a vacancy in the department of “JavaScript badge for my blog to make me look cool” projects, in the sub-category of “GitHub”.

The first entrant and thus market leader of the “Blog Badges for GitHub” micro-industry is the “GitHub Badge” It is beautifully demonstrated in static image form above, or if you click the image through to the website (or here to my blog and its aesthetically appealing enhancement with said GitHub Badge) you’ll see it live and interactive.

Touch it. Feel it. Press the “Show more” link for hours of entertainment.

Installation

Then get it for yourself. Read the GitHub Badge website or just…

Slap the following into your blog sidebar:

<div id="github-badge"></div>
<script type="text/javascript" charset="utf-8">
  GITHUB_USERNAME="drnic";
  GITHUB_LIST_LENGTH=10;
  GITHUB_HEAD="div"; // e.g. change to "h2" for wordpress sidebars
</script>
<script src="http://drnicjavascript.rubyforge.org/github_badge/dist/github-badge-launcher.js" type="text/javascript"></script>

Only GITHUB_USERNAME is a required pre-set variable. The others above show the defaults, and can be changed by being specified.

For my WordPress sidebar, which uses <li> and <h2> for sections and headers, I use the following:

<li id="github-badge"></li>
<script type="text/javascript" charset="utf-8">
  GITHUB_USERNAME="drnic";
  GITHUB_HEAD="h2";
</script>
<script src="http://drnicjavascript.rubyforge.org/github_badge/dist/github-badge-launcher.js" type="text/javascript"></script>

Thus the badge is inserted in the <li> element, and the “My projects (drnic)” header is an <h2> instead of a <div>.

Source and tests on github

You can fetch the source from github – http://github.com/drnic/github_badges/tree/master – using:

git clone git://github.com/drnic/github_badges.git

You might want to add an option to turn off the auto-CSS generator so you can theme it yourself.

The JavaScript tests are in test/ folder. Either run them with rake test, or individually open the files in your browser.

Future cool things the badge could do…

Ultimately, when Chris Wanstrath (harass him on twitter) adds more fields and APIs to the GitHub API then the badge can do more. Currently it orders the projects in reverse order – that is, newest projects first. If I can get the network/watching counters then I can order the list using those values, etc.

Any other cool ideas for what the badge could do?

I’d like to be able to show project version numbers (e.g. gem version numbers) and other project meta-information. This would require GitHub to offer a CRUD UI for generic key/values and for the fields to be returned via their API.

If you know Chris and can throw heavy objects at him with moderate certainty of hitting him and not damaging any expensive equipment, please do so til he gives me this stuff.

Related posts:

1. Migrating project websites to github pages with sake tasks, new websites with jekyll_generator Its almost Christmas time and that means presents. It...
2. How to yell at people with GitHub from TextMate Sometimes when you are perusing code you ask the question:...
3. GitHub and TextMate Unite I wanted to go from a source file to the...

First there was CVS, then came SVN to RubyForge. Actually, I’m guessing that CVS was the sole SCM initially, and SVN was added later. I just can’t imagine them starting RubyForge from scratch and explicitly saying “yeah we’ll offer CVS because …”. I don’t know how that sentence would have finished. It must have been added first. There is no valid “because …”.

But now, with each RubyForge project there is a Git repository. This is great for two very good reasons:

1. the end is nigh for empty or unmaintained SVN repositories
2. less centralised decentralised development

GitHub + Gitorious are the go-to-guys for somewhere to hang your proverbial hat: somewhere you push your local git repository to so other people can access it.

Yet when I’m investigate someone’s new RubyGem or other project, the first place I look for its source is RubyForge. I assume the project name is the same as the gem name, and goto http://rubyforge.org/projects/pastiepacker for example.

Then I click on the SCM tab. Normally this gives SVN instructions. In this modern era, many projects SVN repos can now be blank or unmaintained with Git repos being preferred by many.

So, the reason to push your git repository to RubyForge’s new git system is to make life easier for me. I mean, I don’t know who else clicks on the SCM link, but I do.

While this is all well and great for new projects – you can select “git” instead of “svn” as per the first image above – but I’m not yet sure how to migrate old projects [follow support ticket].

The other reason is to actually help your distributed repository be distributed. Push it to github. Push it to gitorious. And now you can push it to rubyforge. Sweet.

Adding another remote repository

Since your default remote repository is probably called “origin”, you may wonder how such a naming schema could ever expand to multiple remote repositories? Might I suggest “rubyforge” as the name of the rubyforge repository?

git remote add rubyforge gitosis@rubyforge.org:pastiepacker.git
git push rubyforge master
git push origin master

If you do this for all your projects, perhaps a bash script is in order:

function gpall() {
  git push rubyforge master
  git push origin master
}

One project equals one repository, but multiple packages

Using a Rubyforge project’s git repository might be problematic where you release multiple packages/rubygems (codeforpeople, seattlerb, mongrel, drnicutilities, etc). Here I’d prefer one repository per package, rather than one repository for the whole “project”.

Perhaps you could push the master branch from your local repository for each package into different branches of the rubyforge git repository. Thoughts?

Can’t push to your rubyforge git repo?

From the FAQ:

RubyForge Git repositories are managed via gitosis; gitosis does authentication via public keys. This means that in order to push to a RubyForge Git repository you’ll need to upload a public key to your account – see notes on that here.

Generally, Git support is something we’ve just introduced, so feedback about it on the forums would be quite welcome.

What is Pastie Packer?

I can’t tell you. Its a secret.

Related posts:

1. GitHub and TextMate Unite I wanted to go from a source file to the...
2. Using Git within a project (forking around) In Star Wars, when Grand Moff Tarkin orders the...

In Star Wars, when Grand Moff Tarkin orders the destruction of the planet Alderaan, you must question his motivations. Historically, I think too much emphasis has been placed on “he’s an Evil Warlord doing the bidding of Darth Vader and the Emperor”, and “the Rebel scum must be tortured and punished.” But I’m not so sure this is the whole picture.

As developers, we know how exciting it is for a project/website to “go live”. You’ll get some praise from users, some bugs reports, but mostly, you will get the thrill of having finished something and seen it in action.

I’ve got to believe that when Tarkin gave the orders to “open up the taps on this baby,” there was a very different emotion at work amongst all his outwards “Give in to the Empire, Princess Leia” soapboxing. After flying around the emptiness of space in his brand new Death Star, never having actually used its main weapon, he just wanted to see if the thing actually worked.

If George Lucas hadn’t cut away from the cockpit of the Death Star to show us the planet Alderaan being obliterated, I guarantee you that Tarkin was waving his arms in the air, yelling “Oh that’s what I’m talkin’ ’bout,” with his lackies were all high-fiving each other in the background.

This brings me to Git.

Since moving the development of the Rails TextMate bundle to a git repository, several people have forked the repository.

When I pulled in the first “patch” from one of the forked repositories, I finally felt I’d “opened up the taps” on git. It was a sweet feeling.

Whilst Git was created by Linus for managing the Linux project, I get the feeling that Git’s raison d’être was to manage TextMate bundles. Weird since Linus probably doesn’t use TextMate.

A TextMate bundle is a combination of common/default snippets and personal snippets. Those personal snippets may even be useful for other people. Other people way want them. They may even join the set of default snippets.

Git’s system of forked repositories makes all this a reality. In a different, subversion-tainted reality, this scenario would mean that your local subversion checkout of the bundle becomes a mess of modified files and patch requests. With Git, you can stop caring about the central SCM. You make your own local changes, you push them to your own remote fork of the repository, and if they get absorbed into the common/default/central bundle so be it.

As I’m to understand it, this workflow is to Git as destroying planets is to the Death Star. Both Git and the Death Star are technologically impressive and to associate with them is to be seen as “cool”, but they can both do so much more.

Forking and Cloning

I’m not sure if I’m using official vocabulary, but I think of “forking” and “cloning” as different and I’ll use these terms until I’m educated otherwise.

Cloning is to make a copy of a remote repository into your local development environment. Your work machine. With the exception of IM, bittorrent and your shared iTunes library, that FTP server you don’t know is running, etc, no one’s got access to this machine or your clone.

You can make changes to your clone. For the TM bundles you could create a new snippet etc. You can then add and commit those changes into your local Git clone. They are committed now like a normal subversion repository commit. Except only you have them.

You could share the changes with a patch. You create the patch, then email it or upload it to wherever patches are uploaded to for your project.

Alternatively, you can push your changes to remote repositories (see “fork” below). If you have commit access to the original repository you cloned, you’d probably push your commits to this repository. If you don’t have commit rights, then you can fork the repository and push your commits there. “Freeeeeedooooom!!!” cried William Wallace whilst simultaneously having his Scottish testicles emasculated.

Forking is to clone an entire remote repository into another remote repository. Now you have two repositories based around the same code base. At that one point in time, they have the same set of files and the same history of changes.

As suggested above, you might do this because you don’t have commit rights to another fork, or because you are literally doing just as the name suggests: forking the project and going your own way. Either a moderate or radically different direction.

This is exactly what is wonderful about Git with TextMate bundles – there is no “one true path”.

If you wanted to fork the Rails TM bundle that I’ve hosted on github into another repository hosted on github then you click the “fork” button. [Email me for for the secret "I want to help make TM Rails Bundle awesome" github password if you need it to create an account]

Alternately you could fork and host your repository on any public git server. Dean Strelau forked it onto Gitorious. You could also fork it onto gitorious.org, you’ll just need to give it a different name; e.g. prefix/suffix your name.

“In the end, there can be only one”

No. No one needs to have their head cut off, Highlander-style, with Git. I mean, unlike Subversion, Git doesn’t force any organisational behaviour. All commits don’t have to make their way back into one “root” repository.

But, once you have committed changes to your fork you might like to let other forkers know about them; especially if there is one repository that is commonly known as the “root” repository. For the TM Rails bundle it would be my repository since I’ll then aggregate changes and push them down to the official Subversion repository and from there they get pushed out with future TextMate releases.

For the Rubinius project, you’d probably want all your commits investigated and pulled into Evan Pheonix’s personal git clone. He’s not good looking enough to just be a poster boy so I assume he knows how to build and distribute the project for download.

I’m not sure what the organisation hierarchy of evil that is being built around the Rubinius project, but you can probably post a notification of your commits and your repository URL to the Rubinius lighthouse tracker. Don’t have a fork? Just submit patch files. Already have commit rights to Evan’s repository? Push directly to it.

Three different ways to contribute. Which one to use? The organisation of the project decides. Rubinius has a how to contribute page.

For the Rails TextMate bundle project, the preferred way to contribute is either patch files from your local clone, or to fork the project and let me know of your fork URL. Discussion of the project happens on the Google Group.

So, once your project has multiple forks floating around – how do you as a project maintainer pull in the commits contributed by others?

How to pull friends and influence people

Let’s continue with the example of Dean’s fork of the TM bundle. After he forked it, he used the previous article’s instructions to clone his own fork, rather than my repository. To you, once you’ve forked a repository, then your repository is your git “origin” and the original repository you forked just becomes a fork to pull from when you want to synchronise your repositories. Make sense? Thought so.

Put another way, if you don’t fork my TextMate repository rather you just clone it and modify it, then your “origin” will be my repository. You’ll then contribute by emailing patch files.

Or you can fork my repository and then you clone this new repository locally. This new repository is your “origin”. You contribute by committing changes locally and pushing them to your origin (your fork). I then investigate them (see below), and merge them into my repository if I feel like it (gifts help too).

So, Dean’s got a fork. He’s cloned it locally, made changes, committed them locally and pushed them out to his fork. I know I’ve said the three times, but it confused the crap out of me so I think its worth repeating… a lot.

Now how do I pull in Dean’s commits into my local clone, investigate them, and then merge them into my repository? I’m glad you asked.

From within my local clone:

git checkout two_point_ooh
git remote add strelau git://gitorious.org/ruby-on-rails-tmbundle/mainline.git
git checkout -b strelau/two_point_ooh
git pull strelau two_point_ooh

The first line changes my local clone into the “two_point_ooh” branch. Dean has told me that he has made his commits into his own two_point_ooh branch. So, my own two_point_ooh branch is the closest so I’ll start here. Its probably irrelevant which branch you start with. Perhaps.

The second line stores the information about Dean’s fork into my .git/config file. I’ve given the fork a label “strelau”, to differentiate it from my own remote repository “origin”.

The third line creates a new branch of my local repository. This branch will not be pushed up into my remote repository later on, rather its just for my own personal collection. The name of this branch is arbitrary. I could call it “ginger_beer_cordial”, but “strelau/two_point_ooh” is more meaningful. “strelau” to remind me which fork I should pull from, and “two_point_ooh” to remind me which branch of “strelau” to pull from.

Note, you are best to run this “git checkout -b name” operation from within another branch that most closely matches the contents you are about to pull in. That’s why I did the first line – to change into my own two_point_ooh branch first.

The fourth line pulls down any changes from Dean’s two_point_ooh branch into the current branch – strelau/two_point_ooh. That is, you now have a copy of it locally.

UPDATE: I really think this needs a good diagram here to explain the existance of two remote repositories, and within the local clone, the existance of two branches: two_point_ooh, and strelau/two_point_ooh. Plus there’ll be other branches in the local clone: master, origin/master (my remote version), origin/two_point_ooh (my remote version that I’ll push too when I’ve merged in Dean’s changes).

I can now investigate his commits. gitk is a fun tool to see the various branches and differences. It also shows the unique SHA1 codes for each commit, if you want to cherry pick changes rather than merge all of Dean’s changes into your own code.

Later, when Dean has more commits to offer the world, I’ll just run:

git checkout strelau/two_point_ooh
git pull strelau two_point_ooh

See how the name of “Dean’s branch” helps remember what the “git pull” command is? TIP: Give meaningful name to remote branches.

What now?

Once you’ve pulled down someone else’s remote branch (from their fork) it is just another local branch. You can explore it in gitk and see how it compares to other branches, for example.

But what you’ll ultimately want to do is merge some/all of Dean’s commits into your branch, commit them, and push them out to your remote repository. If you have the “central” repository then this is akin to “accepting a patch”.

This process is now basic Git. Like driving the Death Star. Boring, and described elsewhere. Go back to your own branch, merge changes over, and push out to remote repo.

And now, Dean’s changes are in my remote repo:

And my gitk now show’s I’m sweet:

But what about Dean?

That’s like caring about the people on Alderaan…

What I mean to say is… Dean can now pull in my remote “two_point_ooh” branch into his local “two_point_ooh” branch. He may or may not like what I did to it.

I guess Dean and the people of Alderaan can blog about that one…

Related posts:

1. Hacking someone’s gem with github and gemcutter Ever used a rubygem, found a bug, and just...
2. Migrating project websites to github pages with sake tasks, new websites with jekyll_generator Its almost Christmas time and that means presents. It...
3. My attempt at sake task management I’ve used sake intermittently in my workflow. It competes...

Have you noticed lately that the Rails TextMate git pull origin two_point_oohbundle (also installed with e – the Text Editor for Windows) isn’t quite as helpful as it once was – guiding and amplifying your rails app development.

Your resourceful/restful rails apps are now filled with named routes, but none of the helpers (link_to, redirect_to, etc) use them. The default view template was still rhtml for a long time (latest svn trunk fixes this to be html.erb, though Marc Jeanson is having a crack at supporting both through a per-project config file).

Or perhaps you were hoping for some snippets for new features of Rails 2.0: assert_difference (asd), assert_select (ass), respond_to (rst).

Or just maybe, you’ve been updating your local bundle to Rails 2.0 already? Please say yes, please say yes. If you are saying “yes”, read at the bottom for how/where to send me the patches. If you are saying “no”, read at the bottom for how/where to start creating patches and sending them to me.

Firstly, DHH didn’t write the Rails bundle

I didn’t know this – I just assumed the guy who created Rails and helped promote TextMate also created the Ruby on Rails TextMate bundle. Instead if was WWF’s “The Rock” himself Duane Johnson (figurines sold separately, and may look different to the real Duane Johnson who writes Rails code instead of prancing around in his underpants with other adult males in confined spaces).

The TextMate SVN logs say that it the bundle was first committed in Jan 2005. Its now Jan 2008. That’s three years of maintaining a suite of code that thousands of people take for granted every day writing Rails code. What a champion.

Like the Australian Cricket team’s wicketkeeper, Adam Gilchrist, he’s also retiring at the top of his game.

New Maintainer… me

Instead of maintaining my own projects, I’ve decided to maintain this one. I love the TextMate bundles. Before I had a Mac, I ported them across to RadRails and many RadRailers entered a golden era of snippet happiness.

My bundle-fu may not be the equivalent of Bruce Lee, but I’m keen to see my favourite Rails tool live on strong.

Bleeding edge bundle

Whilst the TextMate SVN administrators process the maintainer change request (Allan is on holidays somewhere and he took the house keys with him), you might think all is lost!

Never.

The straight-off-the-cow bleeding edge Rails bundle can be accessed via Git. Specifically the branch two_point_ooh.

So, let’s all do away with our pre-existing Rails bundle and live on the edge.

cd ~/"Library/Application Support/TextMate/Bundles/"
mv "Ruby on Rails.tmbundle" "RoR.tmbundle.orig"
git clone git://github.com/drnic/ruby-on-rails-tmbundle.git "Ruby on Rails.tmbundle"
cd "Ruby on Rails.tmbundle"
git checkout --track -b two_point_ooh origin/two_point_ooh
git pull

Now, back in TextMate, go to menu “Bundles” > “Bundle Editor” > “Reload Bundles”.

You, my friend, are sitting pretty.

Upgrading to when newer blood is on the bleeding edge

Coming back for more?

cd ~/"Library/Application Support/TextMate/Bundles/Ruby on Rails.tmbundle"
git checkout two_point_ooh  # optional; only if you changed to another branch etc
git pull

Now, back in TextMate, go to menu “Bundles” > “Bundle Editor” > “Reload Bundles”.

Bathe yourself in glory. Splash it all over yourself.

Submitting patches

If you go into TextMate, launch the Bundle Editor (Cmd+Alt+Ctrl+B) and change something in the Ruby on Rails bundle, then files will added/changed within your local git clone.

What I mean is, you can very simply submit patches now. [When I say "simply", I mean, "I think this is the best approach but I could be completely wrong here..."] Git is so cool that I don’t know what its doing most of the time; but let’s hang in there as a team.

cd ~/"Library/Application Support/TextMate/Bundles/Ruby on Rails.tmbundle"
git add .   # to add any new files/snippets/commands you created; TextMate uses one file per snippet
git commit -a -m "Useful message about this patch goes here"
git diff -p HEAD^ HEAD

[Theoretically] this creates a patch based on your most recent commit. So you can easily create patches for changes even if your repository and the remote/central/bleeding edge repository look different.

If your patch was created over several commits, then replace HEAD^ with HEAD~4, if there were 4 commits.

I think. God I could be wrong about this though.

Just try your best and if it works, let me know and I’ll remove all this “I don’t know what I’m talking about” text and future readers will think I know everything. Web 2.0 rocks.

Send patches to…

Me drnicwilliams@gmail.com [update] or via the new Google Group.

Update: Note there is a new Google Group (rails-textmate) created in Feb 2009 due to Spam and loss of admin control on original group.

Want to fork the git repo? Use a free account at Gitorious or GitHub.

Ruby on Rails: TextMate

Visit this group

Trundle to Rails 2.0 Bundle

Arguably, we just keep patching the bundle forever and bleeding edges will continue to live happily within the blood and muck of said existence.

But, lots of other people want nicely zipped up bundles. No doubt “e – the Text Editor” will want a “released” version so they can clean it of all the ugly things they can’t yet replicate like Macros. And eventually I’ll push it all down to the SVN repo and it will be released with future TextMate upgrades.

So, there will be a “Rails 2.0 compatible” grand opening one day soon. Probably before 14th of March 2008, when I’m giving a “What’s new in Rails 2.0?” talk at QCON London. Showing off the new bundle will be sweet.

That gives us 6 wks to refactor this bundle to make it a shining example of all that is wonderful in Rails 2.0. Every patch helps.

[Please consider Rails 1.2.6 and before developers when conceiving of patches, and please consult your doctor if pain persists.]

Related posts:

1. Using CoffeeScript in Rails and even on Heroku I’m pretty excited about CoffeeScript as a clean-syntax replacement for...
2. First look at rails 3.0.pre This article is out of date in some aspects....
3. Rails themes can remember things I was getting annoyed at having to remember all the...

All my client projects are hosted on Subversion repos. All my OSS projects are hosted on Rubyforge Subversion repos.

And tomorrow I head off for the 2nd “no internet” RailsCamp megafest, being held outside of Melbourne. From what I heard about the 1st one, it involved a lot of Guitar Hero II and beer. This weekend I’m promised that someone is bringing a Wii – dear God I do love the tennis game.

Like MacDonalds burgers and Veganism, if there are two things that don’t go together its Subversion and “No Internet”.

Fortunately, for all RailsCampers, there is a solution to your fears that you won’t be able to hack on your favourite project, and will be forced into playing Guitar Hero II/III and/or the Wii for the whole weekend.

Git.

Specifically, the git-svn command.

More specifically, follow the following steps:

1. git-svn clone <your svn url> projectname.git
2. Go camping for the weekend.
3. Commit changes with git commit -a -m "hahaha I'm camping and working - doh!"
4. Come home from camping.
5. git-svn rebase to re-import any SVN changes that might have been committed whilst you were away. If there are conflicts, just follow the instructions.
6. git-svn dcommit and your svn repository will be updated with all your fancy changes; no one will ever know you used Git.

Installing Git

I remember having problems getting git-svn to run because the default path to the perl cmd is crap, and you need to specify PERL_PATH='/usr/bin/env perl', I think, before installation.

For MacPorts etc, its sudo port install git-core. I think the reason its not just called ‘git’ is to remind you that you know nothing about git. Which is fair. You don’t if you don’t know how to install it, I guess.

From source, get the tarball from the home page.

For Windows, use cygwin.

Gitify command

Want a utility cmd to create a Git repo in the parent folder of a Subversion project? That is, go to your Rails app that is checked out from a Subversion repo, and run gitify, and you will have a foldername.git folder in the parent folder.

Stick this code into ~/bin/gitify and add ~/bin to your path: