cabdriver is a small helper application that helps you to fill in your hours in taxi. It currently support various sources (see below) to get entries in a taxi-friendly format.
- Configuration File
Make sure you have Node.js >= 8.10.0 installed.
To check the node version number, use the following command:
sudo npm install -g cabdriver
By installing cabdriver globally, you get both
cabdriver and the shorter
cab command to call this tool.
cabdriver has several commands available,
fetch is the default command.
$ cabdriver <command> [options]
$ cabdriver fetch -d today
$ cab -d today
$ cabdriver -n 10 -d yesterday 02/02/2016 # Tuesday xxx 09:00-10:00 Go-Live Planning xxx 09:30-09:45 Jazz Daily Stand-Up xxx 10:05-10:30 Weiteres Vorgehen Staging xxx 13:30-14:00 IPA-Besprechung xxx 16:00-19:00 Byebye Apero Lukas 03/02/2016 # Wednesday xxx 09:30-09:45 Jazz Daily Stand-Up xxx 10:00-10:30 Support Backlog xxx 10:45-11:45 Sprint 3 Planning 2
$ cabdriver --hours -d 03.02.2016 03/02/2016 # Wednesday xxx 0.25 Jazz Daily Stand-Up xxx 0.5 Support Backlog xxx 1 Sprint 3 Planning 2
Entries from 01.03.2016 until 05.03.2016, max. 100 results
$ cabdriver -d 01.03.2016-05.03.2016 -n 100
$ cabdriver --calendar
This uses the primary calendar associated with the Google account.
But you can specify another one, if you want (check the "Calendar ID" on the settings page):
$ cabdriver --calendar email@example.com
$ cabdriver --mail
To configure the output of the mail source, see the section below how to tweak the mail query in the config file.
$ cabdriver --slack
Graphic (pie chart):
$ cabdriver --slack --pie
Note: the Liip-specific Jira instance is pre-defined as host.
$ cabdriver --jira
Unfortunately the JIRA API does not provide the activitiy stream of a user, so that the issue search is used to find recently updated issues, that are related to the logged in user. In those issues the changelog and worklog are evaluated to generate taxi entries.
Find my commits in all git repositories in
$ cabdriver -g /home/odi/projects
If you omit the path all git repositories in the current working directory (recursively) are used.
Depending on the size of your file system, this might take some time.
You can use
--verbose to get an indicator of the progress.
$ cabdriver -g --verbose
Find zebra entries that you've already committed:
$ cabdriver -z -d last-week
$ cabdriver -z -p
This might be helpful to get a double check of the entries that are already in Zebra and to see if something is missing or to update your local taxi file with entries that you made on the web interface of Zebra. Because all those entries were already commited to zebra, they are commted out by default.
Generate entries based on GitHub activity this week:
$ cabdriver --github -d this-week
Generate entries based on GitLab activity:
$ cabdriver --gitlab
Note: GitLab API v4 is required (prefered API version since GitLab 9.0)
Find entries from Logbot:
$ cabdriver -l
For a complete help run
-n --numbernumber of entries to return (default: 250)
-d --datesupports date strings or ranges (default: today):
- past-week (7 days)
- last-month (month before the current)
- past-month (30 days)
- last-year (year before the current)
- past-year (365 days)
- today (up to current time)
- this-week (up to current time)
- this-month (up to current time)
- this-year (up to current time)
-c --calendarchoose the calendar for the entries (default: primary)
-m --mailgenerate entries from mails
-s --slackgenerate entries from slack
-l --logbotgenerate entries from logbot
-j --jiragenerate entries from jira
-z --zebragenerate entries from zebra
-g --git <path>generate entries from your local git repositories (defaults to current directory)
-G --githubgenerate entries from github activities
-L --gitlabgenerate entries from gitlab activities
-p --piegenerate pie chart instead of text (currently only for slack and zebra)
-H --hoursprefer output in hours instead of start/end date
-v --verboseverbose output
To generate empty taxi files (e.g. at the beginning of the month), you can use the
$ cabdriver sheet
Without any options, a sheet for the current month is generated.
To generate sheet for other months, use the
-m (month) and/or
-y (year) options:
$ cabdriver sheet -m this-month # current month $ cabdriver sheet -m next-month # next month $ cabdriver sheet -m 3 # March of current year $ cabdriver sheet -m feb # February of current year $ cabdriver sheet -m 13 # January of next year, numbers >12 will overflow to the following year $ cabdriver sheet -m 6 -y 2019 # June of 2019
The config file is a YAML file, which by default is in your home directory under
You can use the
--config CLI argument to specify a non-default location of the config file.
Default values (
Instead of typing all options, you can specify your default options in the config file. The file looks like this:
defaults: jira: true slack: true calendar: primary zebra: false git: /home/metaodi github: true gitlab: true
If you have the config file in place and you type
cabdriver these values will be applied.
You can use all comand line options in config file, simply use their long name.
NOTE: if you specify a source on the command line, the config file is not used, e.g. with
cabdriver -z will only list zebra entries
defaults key in the config file is really just meant as a place to write down your default values.
Custom project mapping (
cabdriver extracts the project name/alias for each source (e.g. the repository name for the
git source, or project name for
In many cases it's not easily possible to extract the correct alias from the source.
Instead of manually fixing all those entries, you can define a mapping in the config file.
Here is an example:
mapping: acme_dev: - 'dev' _internal: - 'Meeting' - 'Internal' - 'dev' _liiptalk: - 'Liip.*Talk' __comment__: - 'Lunch' __remove__: - 'Hours!'
As you can see, you can define a list of patterns (acutally a regular expression) for each alias.
In the above example, entries with "Meeting" or "Internal" in the project or text field will be mapped to
- all matches are done case-insensitive (using the
iflag of RegExp)
- list as many patterns as you want, if any matches, the project will be mapped
- Each entry will only be mapped once (except for the special keys mention below), i.e. if one match was found, no further matches will be searched (in the example above: entires that match
devwill be mapped to
acme_devand never to
_internal). So place more specific patterns on top and more general patterns on the bottom.
- The special key
__comment__is used to match entries that will be commented out in the final output (by prefixing them with a
- The special key
__remove__is used to match entries that will be removed from the final output. In the
--verbosemode, these entries will be commented out and marked with
- Consider all keys starting and ending with a double underscore to be special
Some intermediate results are cached locally to improve the overall performance of cabdriver. It's possible to tweak the cache settings in the config file:
cache: hours: 2 path: /home/myuser/cache
hours option specifies the amount of hours the results are cached (default:
path option, the location of the cache files can be changed (default:
Configure query and labels for mails
Gmail, which is used as the mail source of cabdriver, allows assign labels to mails and further has fairly powerful query language to search for emails.
cabdriver will simply return all emails in the specified time range.
In the config file you can change this behavior using 3 different method (they can be combined):
include: Define a list of labels that should be searched. Note that if you specify labels here, only emails having those labels will be returned
exclude: Define a list of labels that should be excluded from the results, so only mails that do not have these labels will be returned
query: This is a string to define your own custom query (e.g.
is:unreadto only return unread emails).
Here is a complete example of a mail configuration:
mail: include: - Jira - Education exclude: - Notification - Newsletter query: -to:firstname.lastname@example.org
It's possible to omit keys that are not needed (i.e. only use
exclude) or combine them. The above example would return all emails that have the label "Jira" or "Education", but not the label "Notification" or "Newsletter", mails sent to
email@example.com would be excluded as well.
To run the tests use the following command:
To create a new release follow these steps:
- Update the version number in
- Update the
- Create a new release/tag on GitHub
- The tagged release will automatically be published on NPM by the GitHub Actions workflow (to do it manually, run