gtt

A command line interface for GitLabs time tracking feature.

gtt monitors the time you spent on an issue or merge request locally and syncs it to GitLab. It also allows you to create reports in various formats from time tracking data stored on GitLab.

requirements

• node.js version >= 6
• npm or yarn

installation

Install the gtt command line interface using yarn:

yarn global add gitlab-time-tracker --prefix /usr/local

... or using npm:

npm install -g gitlab-time-tracker

Run the config command to create a config file and open it in your default editor. If nothing happens, open the file manually: ~/.gtt/config.yml

gtt config

Add your GitLab API url and your GitLab API personal token to the config file and save it afterwards:

url: https://gitlab.com/api/v4/
token: 01234567891011

updating

Update gtt via yarn:

yarn global upgrade gitlab-time-tracker

... or npm:

npm install -g gitlab-time-tracker

commands

configuration

Click here for a complete list of configuration options.

Edit/create the global configuration file, stored in your home directory:

gtt config

Edit/create a local configuration file .gtt.yml in the current working directory:

gtt config --local

If a local configuration file is present it's used instead of the global one. So you can use gtt on a per project basis. Make sure to add .gtt.yml to your gitignore file if using a local configuration.

time tracking

Time tracking enables you to monitor the time you spent on an issue or merge request locally. When you're done, you can sync these time records to GitLab: gtt adds the time spent to the given issue or merge request and automagically keeps everything in sync with your local data.

Did you forgot to stop time monitoring locally and accidentally synced it to GitLab? No worries, just edit the local record and run sync again.

Start local time monitoring for the given project and id:

gtt start "kriskbx/example-project" 15
gtt start 15

If you configured a project in your config you can omit the project.

Show the current time monitoring status:

gtt status

Stop local time monitoring and save as a new time record:

gtt stop

Cancel local time monitoring and discard the time record:

gtt cancel

Show a list of all local time records (including their ids and meta data):

gtt log

Edit a local time record by the given id:

gtt edit 2XZkV5LNM
gtt edit

You can omit the id to edit the last added time record.

Delete a local time record by the given id:

gtt delete 2XZkV5LNM
gtt delete

You can omit the id to delete the last added time record.

Sync local time records with time tracking data on Gitlab:

gtt sync
gtt sync --proxy="http://localhost:8888"

You can pass an url to the proxy option if you want to use a proxy server.

reports

Get a report for your project from GitLab.

This command pulls data from GitLab and is not using your LOCAL time records.

# you can omit the project if stored on your config.
# you can pass multiple ids too
gtt report ["namespace/project"] [issue_id]
gtt report "kriskbx/example-project"
gtt report "kriskbx/example-project" 145
gtt report "kriskbx/example-project" 145 209 45 54
gtt report
gtt report 145
gtt report 123 345 123

# timeframe
gtt report --from="2017-03-01" --to="2017-04-01"

# include closed issues/merge_requests
gtt report --closed=true

# limit to a user
gtt report --user=username

# limit to a milestone
gtt report --milestone=milestone_name

# query only one data type: issues, merge_requests
gtt report --query=merge_requests

# limit the parts included in the report: stats, issues, merge_requests, records
gtt report --report=stats --report=records

# hide headlines in the report
gtt report --no_headlines

# hide warnings in the report
gtt report --no_warnings

# set date format
# format options: http://momentjs.com/docs/#/displaying/format/
gtt report --date_format="DD.MM.YYYY HH:mm:ss"

# set time format
# for options, see configuration
gtt report --time_format="[%sign][%days>d ][%hours>h ][%minutes>m ][%seconds>s]"

# set columns for time records list
gtt report --record_columns=user --record_columns=date --record_columns=time

# set columns for issue list
gtt report --issue_columns=iid --issue_columns=title --issue_columns=time_username

# set columns for merge request list
gtt report --merge_request_columns=iid --merge_request_columns=title --merge_request_columns=time_username

# add time columns for all available users to issues and merge requests
gtt report --user_columns

# only include issues and merge requests that have the following labels
gtt report --include_by_labels=critical --include_by_labels=important

# exclude issues and merge requests that have the following labels
gtt report --exclude_by_labels=wont-fix --exclude_by_labels=ignore

# only include the given labels in the results
gtt report --include_labels=pending --include_labels=approved

# exclude the given labels from the results
gtt report --exclude_labels=bug --exclude_labels=feature

# include issues and merge requests in the report hat have no time records
gtt report --show_without_times

# use a proxy server
gtt report --proxy="http://localhost:8080"

# choose a different output than a stdout table
gtt report --output=markdown --file=filename.md
gtt report --output=csv --file=filename.csv
gtt report --output=pdf --file=filename.pdf

configuration options

Here's a sample configuration file including all available options:

# url to the gitlab api. make sure there's a trailing slash
url: http://gitlab.com/api/v4/

# your api token
token: abcdefghijklmnopqrst

# use a proxy server (defaults to false)
proxy: http://localhost:8080

# default project
project: namespace/projectname

# include closed by default
closed: true

# default milestone to filter issues by
milestone: milestone_name

# hours per day
hoursPerDay: 8

# issue columns to include in the report
# available columns: id, iid, title, project_id, description, labels, milestone,
# assignee, author, closed, updated_at, created_at, state, spent, total_spent, 
# total_estimate
#
# you can include time spent by a specific user by adding a column that follows 
# this convention: time_username
issueColumns:
- iid
- title
- estimation

# merge request columns to include in the report
# available columns: id, iid, title, project_id, description, labels, milestone,
# assignee, author, updated_at, created_at, state, spent, total_spent, total_estimate
#
# you can include time spent by a specific user by adding a column that follows 
# this convention: time_username
mergeRequestColumns:
- iid
- title
- estimation

# columns of time records to include in the report
# available columns: user, date, type, iid, time
recordColumns:
- user
- iid
- time

# add time columns for all available users to issues and merge requests
userColumns: true

# date format
# format options: http://momentjs.com/docs/#/displaying/format/
dateFormat: DD.MM.YYYY HH:mm:ss

# time format
#
# [%sign], [%days], [%hours], [%minutes], [%seconds] 
# -> prints out the raw data
#
# [%days>string], [%hours>string], [%minutes>string], [%seconds>string] 
# -> is a conditional and prints out the data and appends the given string
#    if the data is greater than zero
#
# [%Days], [%Hours], [%Minutes], ...
# -> uppercase adds leading zeros
#
# [%days_overall], [%hours_overall], [%minutes_overall], ...
# -> instead of printing out the second-/minute-/hour-/day-part of the time
#    this prints the complete time in seconds/minutes/hours/days
#
# [%days_overall_comma], [%hours_overall_comma], [%minutes_overall_comma] 
# -> use a comma instead of a dot for those float values
timeFormat: "[%sign][%days>d ][%hours>h ][%minutes>m ][%seconds>s]"

# default output, available: csv, table, markdown, pdf
output: markdown

# exclude issues and merge requests that have the following labels
excludeByLabels:
- wont-fix
- ignore

# only include issues and merge request that have the following labels
includeByLabels:
- critical
- important

# exclude the following labels in the results
excludeLabels:
- bug
- feature

# only include the following labels in the result
includeLabels:
- pending
- approved

# query only the given data types: issues, merge_requests
query:
- issues

# include the given parts in the report: stats, issues, merge_requests, records
report:
- stats
- records

# hide headlines in report
noHeadlines: true

# hide warnings in report
noWarnings: true

# include issues and merge requests in the report hat have no time records
showWithoutTimes: true

# change number of concurrent connections. 
# handle with care, we don't want to spam GitLabs API too much
_parallel: 4

# change rows per page (max. 100)
_perPage: 100

use as a library

# install as dependency
yarn add gitlab-time-tracker

// require modules
const Config = require('gitlab-time-tracker/include/config');
const Report = require('gitlab-time-tracker/model/report');

// create a default config
let config = new Config();

// set some vars on config
config.set('token', 'abcdefghijklmnopqrst');
config.set('project', 'namespace/project');

// create report
let report = new Report(config);

// chain promises to query and process data
report.project()
      .then(report.issues, error => {})
      .then(report.mergeRequests, error => {})
      .then(report.processIssues, error => {})
      .then(report.processMergeRequests, error => {});
      
// access data on report
report.issues.forEach(issue => {
    console.log(issue.times);
    console.log(issue.times[0].time);
});
report.mergeRequests.forEach(mergeRequest => {
    console.log(mergeRequests.times);
    console.log(issue.times[0].user);
});

faqs

What is the difference between 'total spent' and 'spent'?

total spent is the total amount of time spent in all issues after filtering. It can include times outside the queried time frame. spent on the other hand is the total amount of time spent in the given time frame.

license

GPL v2