Configuration

The configuration file

Watson configuration and data are stored inside your user’s application folder. Depending on your system, the default path is likely:

• MacOSX: ~/Library/Application Support/watson/config
• Windows: %appdata%\watson\config, which usually expands to C:\Users\<user>\AppData\Roaming\watson\config
• Linux: ~/.config/watson/config

The configuration file is a typical python configuration (INI) file, that looks like:

[Simple Values]
key=value
spaces in keys=allowed
spaces in values=allowed as well
spaces around the delimiter = obviously
you can also use : to delimit keys from values

[All Values Are Strings]
values like this: 1000000
or this: 3.14159265359
are they treated as numbers? : no
integers, floats and booleans are held as: strings
can use the API to get converted values directly: true

[Multiline Values]
chorus: I'm a lumberjack, and I'm okay
    I sleep all night and I work all day


[No Values]
key_without_value
empty string value here =

[You can use comments]
# like this
; or this

# By default only in an empty line.
# Inline comments can be harmful because they prevent users
# from using the delimiting characters as parts of values.
# That being said, this can be customized.

    [Sections Can Be Indented]
        can_values_be_as_well = True
        does_that_mean_anything_special = False
        purpose = formatting for readability
        multiline_values = are
            handled just fine as
            long as they are indented
            deeper than the first line
            of a value
        # Did I mention we can indent comments, too?

This example configuration file has been taken from the official python documentation.

Editing

If you want to edit your configuration, the best is to use the config command.

You can edit your configuration on the fly with:

$ watson config SECTION.KEY VALUE

Example:

$ watson config backend.token 7e329263e329  # set configuration
$ watson config backend.token  # display configuration
7e329263e329

Or open an editor with:

$ watson config -e

Available settings

Backend

At this time there is no official backend for Watson. We are working on it. But in a near future, you will be able to synchronize Watson with a public (or your private) repository via the sync command. To configure your repository please set up the [backend] section.

backend.url (default: empty)

This is the API root url of your repository, e.g. https://my.server.com/api/

backend.token (default: empty)

To authenticate watson as an API client, once generated, you will need to set up your API token in your configuration, e.g. 7e329263e329.

Options

options.confirm_new_project (default: false)

If true, the user will be asked for confirmation before creating a new project. The option can be overriden in the command line with --confirm-new-project flag.

options.confirm_new_tag (default: false)

If true, the user will be asked for confirmation before creating a new tag. The option can be overriden in the command line with --confirm-new-tag flag.

options.date_format (default: %Y.%m.%d)

Globally configure how dates should be formatted. All python’s strftime directives are supported.

options.log_current (default: false)

If true, the output of the log command will include the currently running frame (if any) by default. The option can be overridden on the command line with the -c/-C resp. --current/--no-current flags.

options.pager (default: true)

If true, the output of the log and report command will be run through a pager by default. The option can be overridden on the command line with the -g/-G or --pager/--no-pager flags. If other commands output in colour, but log or report do not, try disabling the pager.

options.report_current (default: false)

If true, the output of the report command will include the currently running frame (if any) by default. The option can be overridden on the command line with the -c/-C resp. --current/--no-current flags.

options.reverse_log (default: true)

If true, the output of the log command will reverse the order of the days to display the latest day’s entries on top and the oldest day’s entries at the bottom. The option can be overridden on the command line with the -r/-R resp. --reverse/--no-reverse flags.

options.stop_on_start (default: false)

If true, starting a new project will stop running projects:

$ watson start samourai +pizza +cat
Starting project samourai [pizza, cat] at 11:14
$ watson start jayce +wheeled +warriors
Stopping project samourai [pizza, cat], started 2 minutes ago. (id: d08cdd0)
Starting project jayce [wheeled, warriors] at 11:16

Please, note that it also works with serious stuffs like:

$ watson start voyager2 +reactor +module
Stopping project jayce [wheeled, warriors], started 2 minutes ago. (id: 967965f)
Starting project voyager2 [reactor, module] at 11:18

options.stop_on_restart (default: false)

Similar to the options.stop_on_start option, but for the restart command.

options.time_format (default: %H:%M:%S%z)

Globally configure how time should be formatted. All python’s strftime directives are supported.

options.week_start (default: monday)

Globally configure which day corresponds to the start of a week. Allowable values are monday, tuesday, wednesday, thursday, friday, saturday, and sunday.

Default tags

Tags can be automatically added for selected projects. This is convenient when the same tags are always attached to a particular project.

These automatically attached tags are defined in the [default_tags] section of the configuration. Each option in that section is a project to which tags should be attached. The entries should follow the pattern: project = tag1 tag2.

You can set default tags for a project from the command line:

$ watson config default_tags.python101 'teaching python'

This corresponds to the following configuration file snippets:

[default_tags]
python101 = teaching python

With these default tags set, the tags “teaching” and “python” will automatically be attached to the project “python101”:

$ watson start python101
Starting project python101 [teaching, python] at 19:27

$ watson start python101 +lecture
Starting project python101 [lecture, teaching, python] at 19:28

Default tags can contain space characters when written in between quotes:

$ watson config default_tags.voyager2 'nasa "space mission"'

Or in the configuration file:

[default_tags]
voyager2 = nasa 'space mission'

Sample configuration file

A basic configuration file looks like the following:

# Watson configuration

[backend]
url = https://api.crick.fr
token = yourapitoken

[options]
stop_on_start = true
stop_on_restart = false
date_format = %Y.%m.%d
time_format = %H:%M:%S%z
week_start = monday
log_current = false
pager = true
report_current = false
reverse_log = true

Application folder

To override Watson’s default application folder (see first section), you can set the $WATSON_DIR environment variable to the desired path.

It may be defined globally in your shell profile:

# .bashrc or .profile
export WATSON_DIR=/path/to/watson/folder

or when calling Watson:

$ WATSON_DIR=/path/to/watson/folder watson status

This can be useful to preserve your real data when hacking with Watson :)