-
Notifications
You must be signed in to change notification settings - Fork 39
Plugins
As of version 0.20, all of the parts of the commit message flashbake generates come from plugins.
As of version 0.22, the names of the stock plugins changed. This reflects the shift to implementing them as classes rather than modules.
There are many stock plugins. This list reflects available plugins for version 0.30 and up.
- flashbake.plugins.timezone:TimeZone
- flashbake.plugins.mail:Email
- flashbake.plugins.weather:Weather
- flashbake.plugins.timestamp:Timestamp
- flashbake.plugins.uptime:UpTime
- flashbake.plugins.feed:Feed
- flashbake.plugins.twitter:Twitter
- flashbake.plugins.growl:Growl
- flashbake.plugins.identica:Identica
- flashbake.plugins.lastfm:LastFM
- flashbake.plugins.music:Banshee
- flashbake.plugins.itunes:iTunes
- flashbake.plugins.music:Music
- flashbake.plugins.music:Rhythmbox
- flashbake.plugins.location:Location
- flashbake.plugins.scrivener:ScrivenerFile
- flashbake.plugins.scrivener:ScrivenerWordcountFile
- flashbake.plugins.scrivener:ScrivenerWordcountMessage
These are enabled by adding a “plugins:” line or lines to your .flashbake file.
Your plugins: entries might look like this:
plugins:flashbake.plugins.timezone:TimeZone,flashbake.plugins.weather:Weather plugins:flashbake.plugins.feed:Feed
flashbake will combine multiple “plugins:” lines to create the total list of plugins to use.
Plugins must be implemented in Python. If you create a ~/.flashbake/plugins/ directory, flashbake will add that to its Python path so any modules and classes there can be loaded. There is also a -p PLUGIN_DIR, —plugins=PLUGIN_DIR option if you want to specify some additional location. You do not need either the plugins directory in your home directory or the plugins option for the stock plugins to work, those are made available to Python and flashbake by following the proper installation. Also, if you are familiar with Python, you can make your modules available on its lookup path through any number of other means.
Plugins should extend the class flashbake.plugins.AbstractMessagePlugin. If a plugin uses the network, it should implementing an init that takes a plugin_spec string and call the super init passing in that string along with a True argument to indicate the plugin is connectable. See Feed and Weather for examples.
A plugin may implement an init method that takes a ControlConfig argument. In the init(self, config) method, the plugin may call the parent’s requireproperty and optionalproperty methods. These methods take a name argument, the name of an option in the control file that should be set as a property on the plugin itself. optionalproperty also takes an optional argument, a type, to which the option value string will be coerced. See Feed for examples of both of these methods being used.
There is also a shareproperty method from the flashbake.ControlConfig class that sets the option as a property on the config instance and on the plugin. See Weather for an example.
This plugin just adds the configured time zone on your computer to the commit message. It tries a few things to determine the timezone.
As of 0.22, the search for a TZ setting has been changed.
- It will look for a line, “timezone:” in the project’s flashbake file or the user’s .flashbake/config file and use that if present.
- It looks for an environment variable, TZ, which many Linux distros set.
- If that is not set, it will look for a file, “/etc/timezone”, and try to read it. Other Linux distros will create and write this file.
- If that fails, it will look for a symbolic link, “/etc/localtime”, and parse the name of the file to which it points. This is common on Macs.
If all of these fail, then it will write a line to that effect in the commit message.
This plugin will send you an email in the event of a problem such as a missing file. You need to have a terminal email client configured, and the plugin takes a few basic settings:
email_notice_to:
This option is the only one that is required. If you don’t configure an email_notice_from: option then the plugin will use the same email that is set here to send messages.
Other options include:
email_notice_from:
smtp_host: (the default is localhost)
smtp_port: (the default is 25)
As of 0.22, this plugin will first use a “weather_city:” option if the setting is in the user’s .flashbake config file or the project’s config.
If there is no “weather_city:” this plugin uses the same logic as the timezone plugin to get a timezone value. It then parses that as the most common timezone names follow the form of “Continent/City_name”. It will parse out the city and fix it to drop out the underscore, if there is one. It then calls the Open Weather Map API to get weather data as an XML file which it parses to construct a nice, readable line for the commit message.
As of October 2015, Open Weather Map requires an API key to access its data, which means you’ll need to sign up for a free Open Weather Map account if you want to use this plugin. To get started, go to the Open Weather Map sign-up page.
Once that’s done, go to home.weathermap.org and click the API keys tab and generate an API key. Copy the key and then drop it in your flashbake config file like so: weather_appid:[paste key here].
The Open Weather Map API allows up to 60 calls per minute per API key.
The weather plugin displays the temperature in Fahrenheit by default. For Celsius add weather_units: metric to your flashbake config.
This plugin read the file, “/proc/uptime”, and parses its contents to generate a human readable amount of time that your computer has been up and running. This plugin will only work on Linux.
This plugin requires some addition lines in your .flashbake configuration file.
As of 0.22 these have been renamed.
- feed_url: – where is the URL to a feed that you want the plugin to read. It can be any feed, but most likely you’ll want to use the one for your blog. As of 0.22, both RSS and Atom feeds should work.
- feed_author:<author’s name> – (optional as of 0.22) where <author’s name> is the name of the author in the feed, exactly as it appears in the feed. The plugin will only output feed items that match this author value.
- feed_limit: – (optional as of 0.22) where is the maximum number of items to pull from the feed, default is 5 if unset.
As of 0.22, if you use the feed plugin, feed_url must be specified.
The Twitter plugin pulls items from a single user’s public Twitter feed. It requires the installation of some additional Python tools, a Twitter developer account (it’s free), and some additional lines in your .flashbake configuration file. These instructions will walk you through the entire process.
The Twitter plugin requires the use of the Tweepy Python library, which interacts with the Twitter API for us. Before you can install Tweepy, however, you need PIP—a tool for installing other Python tools.
To install PIP in Ubuntu Linux do the following (pulled from SaltyCrane for Ubuntu 10.10 and up):
sudo apt-get install python-pip python-dev build-essential
sudo pip install --upgrade pip
sudo pip install --upgrade virtualenv
If you have an earlier version of Linux refer to the SaltyCrane link above. For Mac OSX refer to this article on softwaretester.info.
To install Tweepy do the following from the Bash command line:
python -m pip install tweepy
Now that all the extra tools are installed it’s on to getting our Twitter credentials. Go to apps.twitter.com, sign-in with your Twitter account, and click Create New App.
Give your new app a Name such as “flashbake-[your twitter username]”
For Description use something like “an app that adds contextual information to your git commits.”
Then for the Website entry use https://github.com/commandline/flashbake.
Leave the Callback URL section blank.
Click the check box to agree to Twitter’s terms and click Create your Twitter application.
Now we need four items from your newly created Twitter app: Consumer Key, Consumer Secret, Access Token, and Access Token Secret.
Click on the Keys and Access Tokens tab at the top of the page for your new application. At the top of this tab you’ll see that you already have a consumer key and secret. To create your access token and secret scroll down to the bottom and click Create my Access Token.
Now it’s just a matter of plugging everything into your .flashbake file. Here’s how the entire Twitter section should look:
- plugins:flashbake.plugins.twitter:Twitter
- twitter_consumer_key: XXXXXXXXXXXXXXXXXXX
- twitter_consumer_secret: XXXXXXXXXXXXXXXX
- twitter_access_key: XXXXXXXXXXXXXXXXXXXXX
- twitter_access_secret: XXXXXXXXXXXXXXXXXX
- twitter_username: [your twitter username]
- twitter_tweet_limit: [the number of recent tweets you want to add to your commit.]
Warning: Do not lose control of your access key and secret since it would give a malicious actor direct access to your account. To avoid this do not include your .flashbake file in a public GitHub repository or any other site where your repo could be made public. To be on the safe side use .gitignore to ensure your flashbake config file doesn’t end up where it shouldn’t. If you do lose control of your access key and secret, delete your Twitter app immediately and start over.
The LastFM plugin is an easy way to add what you’ve recently listened to on Spotify and other services to your flashbake commits. It requires several lines in your .flashbake configuration file:
- lastfm_user_name:[your LastFM username goes here]
- lastfm_api_key:[insert your API key here]
You can also use the optional song limit preference. If you don’t specify this option your last five songs will be retrieved:
- lastfm_limit:[specify your song limit]
To obtain an API key, sign-in to LastFM, and then go to the Create API account page. Name the application flashbake, add a short description of your choosing, leave Callback URL blank, and use “https://github.com/commandline/flashbake” as the application’s homepage. Click Submit and then copy the API key on the next page. Now paste it into your .flashbake file as specified above.
Flashbake 0.30 and up does not support this plugin as Banshee is no longer the default music player on Ubuntu. A Rhythmbox plugin is available instead.
This plugin fetches the most recent tracks played by the Banshee music player and writes out the track’s title, artist and last time played. It supports some optional properties in your .flashbake configuration file:
- banshee_db: – by default the plugin looks for ~/.config/banshee-1/banshee.db but if you know your database file is somewhere else, this lets you specify it
- banshee_limit: – by default, the plugin pulls the last three tracks played (this doesn’t include the currently playing track), you can configure it to pull more
- banshee_last_played_format: – if ommitted, the last played time is output per the C locale, if specified use format symbols similar the the unix date command (%H for hour, %M for minute, etc.)
This plugin fetches any tracks played in the last 10 minutes. The plugin does this by scanning Rhythmbox’s XML database. If you don’t see a song you expect in the commit message it’s likely due to Rhythmbox not updating its database in time for the commit.
There are currently no configuration options for this plugin.
This plugin doesn’t require any additional options but it does require a network connection. Accuracy of the plugin is limited by the free database it uses to convert your network address into a location.
This plugin is currently not available for version 0.30 and up. The plugin is being reworked and will return to Flashbake.
Before activating the plugin you’ll want to open Scrivener. Under
Preferences → General ensure “Enable Subversion/CVS-compatible saving
(slower)” is checked.
If you are just activating this setting, you may wish to force a save of
your Scrivener project (Cmd-S).
Add the following to your “plugins:” entry in your .flashbake (or
~/.flashbake/config) file:
flashbake.plugins.scrivener:ScrivenerFile,flashbake.plugins.scrivener:ScrivenerWordcountFile,flashbake.plugins.scrivener:ScrivenerWordcountMessage
The order is important.
(NOTE: the ScrivenerWordcount* plugins require ‘textutil’ to be
available which should be standard on Mac OS X 10.4+.)
Add either “*.scriv” or “MyDocument.scriv” (where “MyDocument” is the
name of your scrivener document) to your .flashbake file.
You may wish to test that the plugin is working by running:
$ flashbake —dryrun —context /path/to/project
You should see something similar to this in the output:
Wordcount: MyDocument.scriv
– Content 60165
– Synopsis 285
– Notes 2327
– All 62775
There are no configuration options for this plugin; however, for the plugin to work you must copy the current_track_itunes.scpt and place it in the root of your Documents folder. This was the easiest way to handle macOS file permissions and ensure the plugin works.
If iTunes is open and playing a track, the plugin will add a line with that info to the commit message. Otherwise, it will indicate that iTunes is not open.
There are no configuration options for this plugin; however, for the plugin to work you must copy the current_track.scpt and place it in the root of your Documents folder. This was the easiest way to handle macOS file permissions and ensure the plugin works.
If Music is open and playing a track, the plugin will add a line with that info to the commit message. Otherwise, it will indicate that Music is not open.
Configuration of this plugin is optional. If totally omitted, then the user must be logged in and have Growl running. You must install the growlnotify program to use this plugin, the program is included in the Extras folder in the Growl .dmg file. The optional config properties are:
- growl_host: specify a remote host to send Growl notices
- growl_port: specify the port of a remote host running Growl
- growl_password: it is recommended that you use a password when enabling remote notices with Growl, use this property to supply that password for a remote host
- growl_growlnotify: specify the path to the growlnotify program
- growl_title_prefix: specify a prefix to the title field in the Growl notices, defaults to “fb”
This plugin prints the time in your commit message using local or UTC time, and a 12- or 24-hour clock. It requires two additions to your flashbake configuration:
`timestamp_time_format:`
`timestamp_time_hours:`
Time format must be set to UTC or local. Time hours must be set to 12 or 24.