NAME

wt - command line work log client

SYNOPSIS

Available subcommands:

wt [add] [-d DATE|-y] [-c] [-f] INTERVAL ISSUE COMMENT
wt commit
wt start [-f] [-c] [ISSUE] [COMMENT]
wt report [-u USER] [RELATIVE-DATESPEC | START [END] [ISSUE]]
wt rm [-r] INDEX|all
wt move INDEX ISSUE [COMMENT]
wt issues [-a] [-s|-j] [-m NUM] STRING
wt alias [ALIAS [COMMAND ...]]
wt undo
wt
wt help [SUBCOMMAND]

DESCRIPTION

wt can be used to track, log, and query working time with a convenient command line interface. Working time entries (discrete intervals with a starting and ending time) are first collected in a local database, then committed to a JIRA instance. Work log entries previously committed, as well as JIRA issue names and descriptions, can be queried.

SUBCOMMANDS

ADD

wt [add] [-d DATE|-y] [-c] [-f] INTERVAL ISSUE COMMENT

Adds an entry to the local list of wt entries.

There are three mandatory arguments:

Interval

Starting and ending time in HH:MM:SS format, separated by a dash.

[HH[:MM[:SS]]]-[HH[:MM[:SS]]]

If seconds are omitted, HH:MM:00 is assumed (whole minutes). If minutes are omitted, HH:00:00 is assumed (whole hours).

If the starting time is omitted altogether, the saved start mark is used instead, if available. It is an error to omit the start if no start mark is available.

If the ending time is omitted altogether, the current time is assumed.

The ending time is also saved for the start mark of the next wt add command. Thus, the interval argument may consist of just a single dash in certain cases, meaning "from the end of the last entry till now".

Alternatively, a relative interval may be specified with a + (plus sign) and a time specifier (HH:MM:SS). Minutes and seconds may be omitted. Fractional hours may also be specified, and a h suffix may be added. A m suffix means minutes instead.

+HH[:MM[:SS]]
+HH.H[h]
+MMm

Starting time is taken from the start mark. The command fails if there is no start mark available.

Issue

Project or issue identifier, in PROJECT-NUMBER format. A single dash means to use the current project, if one is available.

Comment

Arbitrary text (can contain spaces etc. if quoted) to describe the task/bugfix etc. A single dash means to repeat the comment for the last entry (or the comment saved with wt start), if one is available.

Options to the add subcommand

-d Set date

By default, the date for the entry is the current date. This can be overridden by the -d or --date switch, which requires a date string in YYYY-MM-DD format. If the year or month is omitted, the current year or month is substituted.

-y Yesterday

The -y or --yesterday switch sets the date to yesterday.

-c Autocommit

By default, the add subcommand only adds the entry to the local list, which must be committed with wt commit separately.

This switch causes the entry to be committed immediately.

-f Force

By default, a new entry that overlaps with any previous (local) entry is rejected. This switch can be used to disable this check (JIRA doesn't seem to care anyway).

Lunch and breaks

Specifying lunch or break as the issue name will cause the following:

The project name will be substituted from the "lunch-project" key in wt.conf. If that key doesn't exist, or the value is empty, lunch breaks will not be committed, they will be silently dropped instead.

The comment becomes optional, if omitted, "lunch" will be substituted.

The add keyword may be omitted.

COMMIT

wt commit
wt ci

Attempt to commit local wt entries to JIRA. Successfully committed entries are deleted from the list.

START

wt start [-f|--force] [-c|--change] [ISSUE] [COMMENT]
wt s ...

Saves a timestamp with the current time. In effect, this command means "I'm starting work now". An optional project (issue) name can be specified, it will be saved as the current project.

The --change or -c option only changes the current issue, but does not reset the timestamp.

If there is already a timestamp for the current date (in other words, you have already used wt start today), the command will not overwrite it so as to prevent accidental clobbering of unlogged time. The -f or --force switch can be used in this case to enforce saving the timestamp.

-f and -c are mutually exclusive, using them together is an error.

REPORT

wt report [-u|--user USER]
wt report [today | yesterday | week [DATE|last] | month [DATE|last]]
wt report START [END] [ISSUE]
wt r ...

Queries worklog entries from JIRA. If this subcommand is called with two date arguments, worklog entries between the two date are queried from JIRA. Dates must be specified as YYYY-MM-DD. If the year or month is omitted, the current year or month is substituted. today can be used to mean the current date. yesterday can also be used with the expected meaning.

The end date may be omitted altogether, in which case the current date is assumed.

An optional third argument can be used to filter for project name.

Alternatively, certain magic relative date specifiers can be used in place of an explicit date string in the first argument.

If the first argument is month, worklog entries between the start and end of the current month are queried. In this mode the reported sum of logged hours is amended with a projection for the remainder of the month, assuming that the user will log 8 hours for the remaining working days (Monday to Friday).

An optional second argument after month in the format of YYYY-MM or MM causes worklogs from the specified month to be queried instead of the current month. As a special case, this second argument can be last, which queries worklogs from the month preceding the current month.

If the first argument is week, the effect is similar to that of month, expect worklogs between the start and end of the current week are queried. An optional second argument can be given to week too, but note that it will be parsed as a regular [[YYYY]-MM]-DD date string, so a single number will be interpreted as the day in the current month, and this will query worklogs from the week that contain the specified day. As a special case, this second argument can be last, which queries worklogs from last week.

If wt report is called without any arguments, it prints the results of the last query (but doesn't send a new query to JIRA).

By default, wt report queries your own worklogs. The -u or --user switch can be used to query someone else's worklogs. This will only work if you have the appropriate rights in JIRA (the target user is in your team).

ISSUES

wt issues [-a] [-s|-j] [-m NUM] [STRING]
wt : ...

Query issues matching STRING from JIRA and print the resulting list.

Each entry contains the issue number, status, assignee and summary.

The list is sorted by date, latest is on the bottom.

If STRING looks like a JIRA issue (e.g. CG-54), it is assumed to be an issue number, and the resulting list will contain that one issue (at most). Otherwise, it is assumed to be a project number, and all issues under that project are returned (if the project exists).

The -s or --summary switch can be used to search in the issue summaries instead. In this case all issues are reported whose summaries match STRING.

Alternatively, the -j or --jql switch can be used to pass a raw JQL query string to JIRA. The query string is not validated, just passed as is.

The -a or --assigned switch can be used to restrict the search to those issues that are assigned to the current user.

The -m or --max switch can be used to override the maximum number of issues reported, by default 100.

RM

wt rm [-r] INDEX|all

Without the -r or --remote switch, this subcommand deletes one local wt entry. The index number of the entry to be deleted is the same as reported by "wt" without arguments.

Alternatively, if called as "wt rm all", all local entries are deleted.

With the -r or --remote switch, this subcommand does something completely different: it removes an already committed entry from JIRA.

In this case the INDEX argument is understood as the index of the entry in the list of remote entries, as reported by the last wt query command.

MOVE

wt move INDEX ISSUE [COMMENT]

This command adjusts a previously committed worklog entry, that is, it "moves" the entry to a different issue, and optionally changes the worklog comment.

The INDEX argument is understood as the index of the entry in the list of remote entries, as reported by the last wt query command.

The ISSUE argument can be a single dash, meaning that the issue is not changed, only the comment (if given).

LIST

wt

(wt command without arguments) List local wt entries.

ALIAS

wt alias [ALIAS [COMMAND ...]]

This subcommand can be used to assign shortcuts to frequently used commands.

If called as e.g. wt alias foo add - ISSUE-1 foo, then from that point wt foo will be understood as an alias for wt add - ISSUE-1 foo.

Aliases are not expanded recursively, so only the default subcommands are allowed as the aliased command. However, any string is accepted as an alias, so even the default subcommands can be redefined.

If called with just an alias but without a definition, that alias is deleted.

If called without any parameters, the list of all defined aliases is printed.

UNDO

wt undo

Undoes the effect of the last wt add wt rm, or wt start command.

This subcommand only touches (or more precisely, restores) the local wt entry list, so entries already committed are not affected. In other words, wt commit cannot be undone.

There is only one level of undo.

HELP

wt help [SUBCOMMAND]

Prints available subcommands if called without arguments, or detailed help for a subcommand.

EXAMPLES

A typical session (working day) begins with issuing the

wt start

command, optionally with a JIRA issue identifier, to signify that you're starting work for the day.

The simplest way to log time is right away when you're finished with a work unit (bugfix, feature etc.):

wt add - - implemented foo in module bar

This command means in essence I've worked on the current issue, from the end of the last entry till now.

Work can be continued to be logged in this way until the end of the day, when you finally commit the day's work to JIRA:

wt commit

This is not mandatory, however, you can also opt to record your work log entries in one go at the end of the day, specifying explicit intervals and issue names:

wt add 9-12:30 BAR-42 implemented foo in module bar

or even

wt +50m BAR-42 foo

if you don't care about exact starting and ending times, just the amount of time.

You can use

wt : BAR

to search for issues in project BAR.

FILES

This program relies on two files called wt.conf and wt.state, used to store user preferences and persistent state, respectively.

These files are expected to be in a directory called .wt under the user's home directory.

wt.conf, the configuration file should be edited by the user before attempting to use the program. It must be a valid JSON file. The JSON object in it must have at least the following keys:

jira_base_url

The base URL of the JIRA instance to which the worklog entries are to be sent.

user_name

A valid JIRA user name, to be used for authentication.

The following optional keys are also recognized:

worklog_url

Override the standard REST API endpoint used by JIRA to submit/query worklog entries

search_url

Override the standard REST API endpoint used by JIRA to search issues

lunch_project

Specify a JIRA issue for the wt add - lunch feature

autocommit

Turns on autocommit mode: commit is called after each invocation of <wt add>. Boolean key.

no_overlap_check

Disables checking for overlapping time intervals in wt add. Boolean key.

holidays

An array of dates of fixed holidays that affect estimation of remaining working time for wt report month. Dates must be either in YYYY-MM-DD format (for non-fixed holidays like Easter or government-issued special holidays that only occur in a specific year), or in MM-DD format (for fixed holidays that apply to every year).

workdays

An array of dates that should count as workdays (despite falling on Saturday or Sunday). This also affects estimation of remaining working time. Dates must be in YYYY-MM-DD or MM-DD format (like above).

Example:

{
                "jira_base_url": "https://my.awesome.company.com/jira",
                "worklog_url": "/rest/tempo-timesheets/3/worklogs/",
                "search_url": "/rest/api/2/search",
                "user_name": "homer.simpson",
                "lunch_project": "CMPS-19",
                "autocommit": true,
                "holidays": ["01-01", "03-14", "03-15", "03-28", "05-01", "05-16", "08-20", "10-23", "10-31", "11-01", "12-24", "12-25", "12-26"],
                "workdays": ["03-05", "10-15"]
}

wt.state, the file to store persistent state between consequent runs of the program, is modified by most subcommands (the exceptions are wt without arguments and wt report without arguments). It is also a JSON file, however, it is not intended to be directly edited by the user.

SAVING JIRA PASSWORD

The commit, issues, rm --remote and report subcommand have to connect to the JIRA instance specified in the config file. This requires authentication, in the form of an user name and password. The user name is also specified in the config file, however, the password is not.

On systems that have a keyring (more precisely, any working keyring implementation supported by the Passwd::Keyring::Auto module, which must also be installed if keyring support is desired), the password is asked only once, then saved into the keyring safely.

On systems without keyring support the JIRA password is asked before every command that needs JIRA access.

Storing the password in plaintext is not supported (nor is it recommended).