cabdriver
v4.0.1
Published
Helps you to fill in your hours with taxi
Downloads
40
Maintainers
Readme
cabdriver
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.
Content
Installation
Make sure you have Node.js >= 8.10.0 installed.
To check the node version number, use the following command:
node --version
Install cabdriver
globally:
sudo npm install -g cabdriver
By installing cabdriver globally, you get both cabdriver
and the shorter cab
command to call this tool.
Usage
cabdriver has several commands available, fetch
is the default command.
$ cabdriver <command> [options]
Example:
$ cabdriver fetch -d today
Or shorter:
$ cab -d today
fetch
command
$ 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
Google Calendar
$ 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 protected]
Google Mail
$ cabdriver --mail
To configure the output of the mail source, see the section below how to tweak the mail query in the config file.
Slack
Text entries:
$ cabdriver --slack
Graphic (pie chart):
$ cabdriver --slack --pie
Jira
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.
Git
Find my commits in all git repositories in /home/odi/projects
:
$ 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
Zebra
Find zebra entries that you've already committed:
$ cabdriver -z -d last-week
Pie chart:
$ 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.
Github
Generate entries based on GitHub activity this week:
$ cabdriver --github -d this-week
Gitlab
Generate entries based on GitLab activity:
$ cabdriver --gitlab
Note: GitLab API v4 is required (prefered API version since GitLab 9.0)
Logbot
Find entries from Logbot:
$ cabdriver -l
Options
For a complete help run cabdriver --help
.
-n --number
number of entries to return (default: 250)-d --date
supports date strings or ranges (default: today):- 31.12.2016
- 01.12.2016-31.12.2016
- yesterday
- last-week
- 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 --calendar
choose the calendar for the entries (default: primary)-m --mail
generate entries from mails-s --slack
generate entries from slack-l --logbot
generate entries from logbot-j --jira
generate entries from jira-z --zebra
generate entries from zebra-g --git <path>
generate entries from your local git repositories (defaults to current directory)-G --github
generate entries from github activities-L --gitlab
generate entries from gitlab activities-p --pie
generate pie chart instead of text (currently only for slack and zebra)-H --hours
prefer output in hours instead of start/end date-v --verbose
verbose output
sheet
command
To generate empty taxi files (e.g. at the beginning of the month), you can use the sheet
command:
$ 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
Configuration File
The config file is a YAML file, which by default is in your home directory under ~/.cabdriver/cabdriver.yml
.
You can use the -C
/--config
CLI argument to specify a non-default location of the config file.
Default values (defaults
)
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
The defaults
key in the config file is really just meant as a place to write down your default values.
Custom project mapping (mapping
)
cabdriver extracts the project name/alias for each source (e.g. the repository name for the git
source, or project name for jira
).
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 _internal
.
Some notes:
- all matches are done case-insensitive (using the
i
flag 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
dev
will be mapped toacme_dev
and 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#
character) - The special key
__remove__
is used to match entries that will be removed from the final output. In the--verbose
mode, these entries will be commented out and marked with[REMOVED]
- Consider all keys starting and ending with a double underscore to be special
Cache
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
The hours
option specifies the amount of hours the results are cached (default: 1
).
With the path
option, the location of the cache files can be changed (default: ~/.cabdriver/cache
)
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.
By default, 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 returnedexclude
: Define a list of labels that should be excluded from the results, so only mails that do not have these labels will be returnedquery
: This is a string to define your own custom query (e.g.is:unread
to only return unread emails).
Here is a complete example of a mail configuration:
mail:
include:
- Jira
- Education
exclude:
- Notification
- Newsletter
query: -to:[email protected]
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 protected]
would be excluded as well.
Tests
To run the tests use the following command:
npm test
Release
To create a new release follow these steps:
- Update the version number in
package.json
- Update the
CHANGELOG.md
- 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
npm publish
)