Sharing code snippets with GIST + Sublime

As developers we often find ourselves doing tasks very similar (sometimes identical) to ones that we had previouly done. In this post I'll explain how to maintain our version controlled library so we can easily find, re-use and share code snippets with everyone (or only with a few people) as well as integrate it in our regular workflow.

 

 

 

Depending on the complexity, Drupal's best practices encourages us not to repeat ourselves by relying on features, custom modules or profiles so we can save a lot of time and minimize errors. However, there are times in which we only want to re-use relatively small parts of code that achieve certain functionallity and it's not worth (or not even possible) to create a module for that. This is the perfect scenario in which managing a library of code snippets for further re-use turns to be really handy. Althoug we often have our own snippets' library, this is not enough if we want to share it (and find it later) with other members of our team or with a whole community. This can be achieved by using two well-known tools: Sublime text and Github's Gists.

Installing and configuring Gist package in Sublime

These instructions assume that you already have Sublime Editor installed on your system and you already have an account at Github. If you haven't done so, there are a number of reasons to use these two tools (really) and there's plenty of documentation on how to do that.

  1. Install Package Control for Sublime Editor, which is a  package manager that makes it really simple to find, install and keep packages up-to-date within Sublime Editor. In order to do so, you only need to open Sublime's console (ctrl+`) and paste the code provided in the official website, which also provides more detailed instructions: https://sublime.wbond.net/installation
  2. Install Gist package using Package Control. In order to achieve that you need to run Command Pallete using the following shortcut ctrl+shift+p (Win, Linux) or cmd+shift+p (OS X)
  3. Configure your Gist plugin in order to link it with your existing github user.
    1. Log in into a Github account and generate a token to be used in Gist package.
      You can do so by visiting https://github.com/settings/applications. Github provides a detailed documentation covering this topic in this page.
    2. Open Gist plugin's configuration file and paste the previously generated token on the appropiate line. This file will automatically open the first time we want to execute a command from the Command Pallete or it can be accessed within this menu path: Preferences/Package Control/Gist.
    3. You may (or may not) want to fill in other optional settings provided by Gist package which are detailed in its excelent readme file.

Using Gist package

Gist package proves the following options that can be accessed from the Command Pallete. All of them are self-explanatory but the following ones are the most used ones:

  1. Insert a gist: it will display a list of all the gists within your account and will insert it in the current file, under the cursor.
  2. Open a gist: it will display a list of all the gists within your account and will open all its files in different tabs, so you can modify them and save them
  3. Create a private gist: it creates a gist that can be only accessed by you or with anyone that has the exact url.
  4. Create a public gist: it creates a public gist, so anyone can see, copy, modify or comment it.
  5. Add a file into gist: since a gist can contain several files, it adds the currently opened file into an existing gist.
  6. Update a gist: it will update the current gist and push the changes to gist.

Using Gist package is really easy: you only need to call it from the Command Pallete and then select the desired option (Protip: most of them provide their own shortcut that is displayed at the right of the Command Pallete dropdown).

Filling, sharing and commenting snippets in Gist

Well, it may be a little bit late to explain this now, but Gists are basically small repositories with a short description that ideally they should contain one file with a small piece of code, however there may be some scenarios that will require to contain several files. Descriptions are important, since they are the only way to search (and find) any gist from either your profile or all the community available gists. This means that your description has to be really descriptive, or you'll have real problems to find your own snippets in the future (Protip: you can use # in your description to tag your gists). Each user has a page in which you can see all their public gists (for example mine: https://gist.github.com/ccamara) and there's also a page that displays all the public gists: https://gist.github.com/discover/ from which you can search other snippets.

Being a web service based on git, it also has the following interesting features:

  1. You can star, watch or even fork someone else's gist.
  2. Each gist can be commented.
  3. You can clone your repo and work locally with your regular tools.
  4. It allows you to edit gists from the website.
  5. It allows you to embed a gist in another page, so it will be automatically updated if you ever make any change into your gist.

Bonus: Reasons for using sublime text:

Pros: Well documented, multiplattform, lightweight, plugabble architecture, it's fast: tons of shortcuts and commands using Command Pallete, huge community plugins

Cons: It's not opensource, does not provide debbugging tools, not aimed to OOP.

If you didn't know Sublime text or you are not using it you may want to read the following articles about it: