gitlab-time-tracker
Advanced tools
gtt
A fully featured command line interface for GitLab's 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.
Please support the development of this free software by donating or sharing!
| monitor your time | ... and get reports |
|---|---|
 |  |
Install the gtt command line interface using yarn:
yarn global add gitlab-time-tracker --prefix /usr/local
... or using npm (recommended on Windows operating systems):
npm install -g gitlab-time-tracker
Run the config command to create a config file and open it in your default editor.
In linux terminal, you must set your preferred editor in the environment. For example, use export EDITOR=vim to edit the files with vim (put this in .bashrc or similar to have it always configured).
If nothing happens, open the file manually: ~/.gtt/config.yml - on Windows: C:\Users\YourUserName\.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 from version <= 1.5? Please click here!
Update gtt via yarn:
yarn global upgrade gitlab-time-tracker
... or npm:
npm install -g gitlab-time-tracker
You don't need to have node and gtt installed on your system in order to use gtt, you can use the official Docker image as well:
docker run \
--rm -it \
-v ~:/root \
kriskbx/gitlab-time-tracker \
--help
--rm removes the container after running, -it makes it interactive, -v ~:/root mounts your home directory to the
home directory inside the container. If you want to store the config in another place, mount another directory:
docker run \
--rm -it \
-v /path/to/gtt-config:/root \
kriskbx/gitlab-time-tracker \
--help
... or use a Docker volume:
docker volume create gtt-config
docker run \
--rm -it \
-v gtt-config:/root \
kriskbx/gitlab-time-tracker \
--help
I highly recommend creating an alias and adding it to your bashrc:
echo "alias gtt='docker run --rm -it -v ~:/root kriskbx/gitlab-time-tracker'" >>~/.bashrc
Now you can simply write gtt instead of the bulky Docker command before. Try it out: gtt --help
Note: If you want to save reports via the --file parameter, make sure to save them in /root or another
mounted directory that you have access to on your host machine. Take a look at the Docker documentation about how Docker handles data and volumes.
Click here for a complete list of configuration options.
Edit/create the global configuration file, stored in your home directory:
gtt config
If nothing happens, open the file manually: ~/.gtt/config.yml - on Windows: C:\Users\YourUserName\.gtt\config.yml
Edit/create a local configuration file .gtt.yml in the current working directory:
gtt config --local
If a local configuration file is present it will extend of the global one and overwrites global settings.
If you don't want to extend the global configuration file, set the extend option in your local config to false.
So you can use gtt easily on a per project basis. Make sure to add .gtt.yml to your gitignore file if using a local configuration.
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 issue id:
gtt start "kriskbx/example-project" 15
gtt start 15
If you configured a project in your config you can omit the project.
Start local time monitoring for a merge request:
gtt start --type=merge_request "kriskbx/example-project" 15
gtt start --type=merge_request 15
Start local time monitoring and create a new issue or merge request with the given title:
gtt create "kriskbx/example-project" "New Issue"
gtt create "New Issue"
gtt create --type=merge_request "kriskbx/example-project" "New Issue"
gtt create --type=merge_request "New Issue"
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
Note: gtt log uses UTC as default timezone. If you want to display the times in a different timezone, make sure to use timezone: "Europe/Berlin" in your config.
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.
Get a report for the time tracking data stored on GitLab. If you want to include your local data make sure to sync it before running the report command. The report command has a lot of options to filter data and output, make sure to read through the docs before using it.
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
If you configured a project in your config file you can omit it. By passing a or multiple ids you can limit the
report to the given issues or merge requests. Note: if you're passing a or multiple ids, gtt will fetch issues
with these ids by default. If you want to fetch merge requests you can change the query type using the
--query option.
gtt report ["namespace"] --type=group
gtt report example-group --type=group
gtt report example-group --type=group --subgroups
Query all projects from the given group and combine the data into a single report. The option --subgroups
includes subgroups.
gtt report ["namespace/project"] ["namespace/project"] ...
gtt report "kriskbx/example-project" "kriskbx/example-project-2"
gtt report ["namespace"] ["namespace"] ... --type=group
gtt report example-group example-group-2 --type=group
Hint: use the project_id or project_namespace columns in your report.
gtt report --output=table
gtt report --output=markdown
gtt report --output=csv
gtt report --output=pdf --file=filename.pdf
Defaults to table. csv and markdown can be printed to stdout, pdf needs the file parameter.
gtt report --file=filename.txt
gtt report --from="2017-03-01" --to="2017-04-01"
Note: --from defaults to 1970-01-01, --to defaults to now. Make sure to use an ISO 8601 compatible time/date format.
There are some quick shorthands:
gtt report --today
gtt report --this_week
gtt report --this_month
gtt report --closed
gtt report --user=username
gtt report --milestone=milestone_name
gtt report --include_by_labels=critical --include_by_labels=important
gtt report --exclude_by_labels=wont-fix --exclude_by_labels=ignore
gtt report --query=issues
gtt report --query=merge_requests
gtt report --show_without_times
gtt report --report=stats --report=issues
Note: These parts are available: stats, issues, merge_requests, records
gtt report --no_headlines
gtt report --no_warnings
gtt report --date_format="DD.MM.YYYY HH:mm:ss"
Note: Click here for a further documentation on the date format.
gtt report --time_format="[%sign][%days>d ][%hours>h ][%minutes>m ][%seconds>s]"
Note: Click here for a further documentation on the time format.
gtt report --hours_per_day=6
gtt report --record_columns=user --record_columns=date --record_columns=time
Note: Available columns to choose from: user, date, type, iid, project_id, project_namespace, time
gtt report --issue_columns=iid --issue_columns=title --issue_columns=time_username
Note: Available columns to choose from: id, iid, title, project_id,
project_namespace, description, labels, milestone, assignee, author,
closed, updated_at, created_at, state, spent, total_spent, total_estimate
You can also include columns that show the total time spent by a specific user
by following this convention: time_username
gtt report --merge_request_columns=iid --merge_request_columns=title --merge_request_columns=time_username
Note: Available columns to choose from: id, iid, title, project_id,
project_namespace, description, labels, milestone, assignee, author,
updated_at, created_at, state, spent, total_spent, total_estimate
You can also include columns that show the total time spent by a specific user
by following this convention: time_username
gtt report --user_columns
gtt report --include_labels=pending --include_labels=approved
gtt report --exclude_labels=bug --exclude_labels=feature
gtt report --proxy="http://localhost:8080"
gtt report --verbose
The configuration uses the yaml file format. Click here for more information how to edit and create a config file.
Here's a sample configuration file including all available options:
# Url to the gitlab api
# Make sure there's a trailing slash
# [required]
url: http://gitlab.com/api/v4/
# GitLab personal api token
# [required]
token: abcdefghijklmnopqrst
# Use a proxy server
# defaults to false
proxy: http://localhost:8080
# Don't check SSL certificate
# defaults to false
insecure: true
# Project
# defaults to false
project: namespace/projectname
# Include closed issues and merge requests
# defaults to false
closed: true
# Limit to the given milestone
# defaults to false
milestone: milestone_name
# Exclude issues and merge requests that have the given labels
# defaults to an empty array
excludeByLabels:
- wont-fix
- ignore
# Limit issues and merge requests to the given labels
# defaults to an empty array
includeByLabels:
- critical
- important
# Limit the query to the given data type
# available: issues, merge_requests
# defaults to [issues, merge_requests]
query:
- issues
# Limit the parts in the final report
# available: stats, issues, merge_requests, records
# defaults to [stats, issues, merge_requests, records]
report:
- stats
- records
# Hide headlines in the report
# defaults to false
noHeadlines: true
# Hide warnings in the report
# defaults to false
noWarnings: true
# Include issues and merge requests in the report that have no time records
# defaults to false
showWithoutTimes: true
# Hours per day
# defaults to 8
hoursPerDay: 8
# Days per week
# defaults to 5
daysPerWeek: 5
# Weeks per month
# defaults to 4
weeksPerMonth: 4
# Include the given columns in the issue table
# See --issue_columns option for more information
# defaults to iid, title, spent, total_estimate
issueColumns:
- iid
- title
- total_estimate
# Include the given columns in the merge request table
# See --merge_request_columns option for more information
# defaults to iid, title, spent, total_estimate
mergeRequestColumns:
- iid
- title
- total_estimate
# Include the given columns in the time record table
# See --record_columns option for more information
# defaults to user, date, type, iid, time
recordColumns:
- user
- iid
- time
# Add columns for each project member to issue and
# merge request table, including their total time spent
# defaults to true
userColumns: true
# Date format
# Click here for format options: http://momentjs.com/docs/#/displaying/format/
# defaults to DD.MM.YYYY HH:mm:ss
dateFormat: DD.MM.YYYY HH:mm:ss
# Time format
# See time format configuration below
# defaults to "[%sign][%days>d ][%hours>h ][%minutes>m ][%seconds>s]"
timeFormat: "[%sign][%days>d ][%hours>h ][%minutes>m ][%seconds>s]"
# Time format for different parts of the report
# Instead of specifying one global time format you can specify one for every
# part of the report and the log command
timeFormat:
log: "[%sign][%hours_overall]"
stats: "[%sign][%days_overall]"
issues: "[%sign][%hours_overall]"
merge_requests: "[%sign][%hours_overall]"
records: "[%sign][%days>d ][%hours>h ][%minutes>m ][%seconds>s]"
# Change your timezone
# default: UTC
timezone: "Europe/Berlin"
# Output type
# Available: csv, table, markdown, pdf
# defaults to table
output: markdown
# Exclude the given labels from the report
# defaults to an empty array
excludeLabels:
- bug
- feature
# Only include the given labels in the report
# defaults to an empty array
includeLabels:
- pending
- approved
# Only works if using a local configuration file!
# Extend the global configuration if set to true, pass a string to extend
# the configuration file stored at the given path
# defaults to true
extend: true
# Change number of concurrent connections/http queries
# Note: Handle with care, we don't want to spam GitLabs API too much
# defaults to 10
_parallel: 20
# Change rows per page (max. 100)
# defaults to 100
_perPage: 100
# Verbose output
_verbose: false
# Check access token validity up front
_checkToken: false
# Skip parsing the issue/merge_request description for time records
_skipDescriptionParsing: false
[%sign], [%days], [%hours], [%minutes], [%seconds]Prints out the raw data.
Example config:
timeFormat: "[%sign][%days]d [%hours]h [%minutes]m [%seconds]s"
Example outputs:
0d 0h 30m 15s
-1d 10h 15m 0s
[%days>string], [%hours>string], [%minutes>string], [%seconds>string]This is a conditional: it prints out the raw data and appends the given string if the data is greater than zero.
Example config:
timeFormat: "[%sign][%days>d ][%hours>h ][%minutes>m ][%seconds>s]"
Example outputs:
30m 15s
-1d 10h 15m
[%Days], [%Hours], [%Minutes], [%Seconds], [%Days>string], [%Hours>string], [%Minutes>string], [%Seconds>string]First letter uppercase adds leading zeros.
Example config:
timeFormat: "[%sign][%Days]:[%Hours]:[%Minutes]:[%Seconds]"
Example outputs:
00:00:30:15
-01:10:15:00
[%days_overall], [%hours_overall], [%minutes_overall], [%seconds_overall]Instead of printing out the second-, minute-, hour-, day-part of the duration this prints the complete time in either seconds, minutes, hours or days.
Example config:
timeFormat: "[%sign][%minutes_overall]"
Example outputs:
30.25
1095
[%days_overall_comma], [%hours_overall_comma], [%minutes_overall_comma], [%seconds_overall_comma]Use a comma for float values instead of a point. (Useful for some european countries)
Example config:
timeFormat: "[%sign][%minutes_overall]"
Example outputs:
30,25
1095
[%hours_overall:2], [%days_overall:3]You can ceil any float value by adding the number of decimals to keep separated with a :.
Example config:
timeFormat: "[%sign][%hours_overall:2]"
Example outputs:
0,51
18,25
Add as a dependency using yarn:
yarn add gitlab-time-tracker
... or using npm:
npm install --save gitlab-time-tracker
Use it in your project:
// require modules
const Config = require('gitlab-time-tracker/src/include/config');
const Report = require('gitlab-time-tracker/src/models/report');
// create a default config
let config = new Config();
// set required parameters
config.set('token', 'abcdefghijklmnopqrst');
config.set('project', 'namespace/project');
// create report
let report = new Report(config);
// query and process data
try {
await report.getProject()
await report.getIssues()
await report.getMergeRequests()
await report.processIssues()
await report.processMergeRequests()
} catch (error) {
console.log(error)
}
// access data on report
report.issues.forEach(issue => {
// time records on issue
console.log(issue.times);
// time spent of single time record
console.log(issue.times[0].time);
});
report.mergeRequests.forEach(mergeRequest => {
// time records on merge requests
console.log(mergeRequest.times);
// user of single time record
console.log(mergeRequest.times[0].user);
});
Starting with 1.7.4 gtt can dump the results of all API requests within a report and use it on another machine without access to the GitLab instance itself. This is very useful for debugging purposes. If you stumble upon a bug which could be unique to your set of data, please rerun the report with these options to save a dump to the given file: --output=dump --file=/path/dump.json Check your dump for sensitive information and provide it when asked.
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.
I would love to integrate unit testing in this project, but unfortunately my knowledge of testing in the JavaScript/Node.js world is very limited. (I'm actually a PHP dev) So this would be a very helpful thing to contribute but of course all contributions are very welcome.
integrate-awesome-feature, fix-awful-bug, improve-this-crappy-docsdev branchgtt is an open source project, developed and maintained completely in my free time.
If you enjoy using gtt you can support the project by contributing to the code base, sharing it to your colleagues and co-workers or monetarily by donating via PayPal. Every type of support is helpful and thank you very much if you consider supporting the project or already have done so. 💜
GPL v2
FAQs
A command line interface for GitLabs time tracking feature.
The npm package gitlab-time-tracker receives a total of 100 weekly downloads. As such, gitlab-time-tracker popularity was classified as not popular.
We found that gitlab-time-tracker demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.