Home

All of the documentation is now located, here, and maintained as a wiki so hopefully it can be collaboratively maintained.

Using Cron

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.

Control File

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.