-
Notifications
You must be signed in to change notification settings - Fork 39
Home
All of the documentation is now located, here, and maintained as a wiki so hopefully it can be collaboratively maintained.
With the forthcoming version, flashbake will have some external dependencies that will need to be installed. You can use Python’s easy_instsall to satisfy these dependencies. You may need to install easy_install, first. Under Linux, install the python-setup package.
easy_install enum
The published version uses Python’s nice installation capabilities. To install the scripts themselves, download the tarball, explode it, and run
sudo python setup.py install
in that exploded directory.
Flashbake can be run manually to generate a commit but is most effectively when run by a scheduler, such as cron. That is also when the quiet period starts to make since. For example, say you have a project in ~/my_novel/ that you want to track. Add a cron job like:
15/* * * * * flashbake ~/my_novel 5 > /dev/null
Cron will then run flashbake every fifteen minutes and commit any changes to hot files in the project that have not been changed in the last 5 minutes. If there have been recent changes, flashbake will pick them up next time cron runs it, assuming the files haven’t been edited within five minutes of that invocation. You can tweak that quiet interval argument to make flashbake more greedy, committing more often, or more cautious, waiting until edits have stopped for a considerable duration. I encourage some experimentation to find what suits you.
You can also completely disable the quiet period behavior by suing the value 0 or, as of version 0.19, completely omitting the quiet period argument. Disabling the quiet period means that when cron runs flashbake, all outstanding changes to hot files in a project will be committed.
Usage
In the previous section, you’ve already seen the two main arguments to flashbake, the project directory and the optional quiet period. There are a few other options that can be used, run “flashbake —help” to see the all with some explanatory notes.
For this early release, the to options of interest are -c or —context and -v or —verbose.
If you run
flashbake -c ~/my_novel
flashbake will not commit any changes, rather it will show you the commit message it would generate if run normal. This is useful for checking that you’ve entered the options in the control file correctly. As I work on the plugin system, this will also be useful for plugin authors to check their output.
I am also planning on adding a proper dry run option that will run the script against a project directory, report what would be done but not execute the git commands.
The verbose switch simply increases what flashbake reports to the console. I mention it in case you give flashbake a try and want to contact me for help. Capturing that verbose output and including it in help requests will ensure a quicker reponse and hopefully a faster fix.
I will document new options, here, as they become available and try to note in which version they were added.
git by default has its own way of indicating what files to track for versioning. This requires prehaps more of an understanding of git than someone looking to use flashbake may want to delve into. To drive the configuration information for commit messages, flashbake needs a configuration file of its own, anyway. It seemed like a good idea to use this for specifying hot files in a project directory in addition to providing that info.
The control file must be right in the project directory and be named “.control”. If it is not found, flashbake will complain clearly about its absence. flashbake will also complain if the project directory is not also a git repository.
Here’s a quick, annotated sample (yes, the .control file format supports comments and blank lines):
# URL to the RSS feed, Atom support is coming soon feed:http://www.mysite.com/feed # the author exactly as it appears in the author tag in the RSS # only the items matching this author will be pulled author:Joe Random # how many of the most recent items to pull limit:3 # right now, you need a local smtp server to send notice_to:joe@mysite.com # alternately, if you set up an ssh tunnel, you can set this and send through # the tunnel #smtp_port:5002 # hot files todo.txt my_novel.txt extra/character_notes.txt extra/story_bible.txt
The smtp support is for emailing a notice when there is a problem, either an error on a particular hot file or a hot file that doesn’t exist, yet. If you do not want email notices, enter a bogus address. The script will complain but will still work. I will work on gracefully disabling notices in a future version. I will also work on remote smtp auth if I get a willing guinea pi—er, tester.
flashbake will automatically add hot files that exist to the git repository for you, the only command you need to run is “git init” in the project directory.
0.19 (2/12/2009) – First public version, available as an installable Python project. This version has been tested on Linux and OS X with Python 2.5.2. Certain parts of it will not work on Windows. If anyone is interested in a Windows compatible version, let me know and I’ll see what I can do. This version has no external dependencies other than git. It does not use the git-python package though I am looking into that for a future release.
Once installed, you can run “flashbake —help” for information on how to run it. The project directory mentioned in the help must be a git repository and must have an additional .control file. It should give clear feedback on errors when you are running it.
Future Releases
The next big feature for flashbake is support for plugins. The four bits of information that make up the commit message (time zone, weather, uptime and rss items) are currently set up as stock plugins. I am working on the validation logic for vetting third party plugins and deciding on how to locate them. This would allow anyone who is comfortable hacking in Python to build their own plugins and to mix and match to generate their own customized, automated commit message.