.TH timew 1 2016-06-20 "${PACKAGE_STRING}" "User Manuals" .SH NAME timew \- A command line time tracker. .SH SYNOPSIS .B timew [ ...] .SH DESCRIPTION Timewarrior is a command line time tracker. It allows you to very easily track your time spent on projects, and generate summary reports. .SH SUBCOMMANDS Timewarrior supports many commands. Alphabetically: .TP .B timew .br When run with no arguments, the default command is run, which indicates whether there is any active tracking, and if so, shows a summary, and exits with a code 0. If there is no active time tracking, exit code is 1. .TP .B timew cancel If there is an open interval, closes and abandons it. See also 'stop'. .TP .B timew config [ [ | '']] Allows setting and removing configuration values, as an alternative to directly editing your ~/.timewarrior/timewarrior.cfg file. For example: $ timew config verbose yes $ timew config verbose '' $ timew config verbose The first command sets 'verbose' to 'yes'. The second sets it to a blank value which overrides the default value. The third example deletes the 'verbose' setting. When modifying configuration in this way, interactive confirmation will be sought. To override this confirmation, use the ':yes' hint: $ timew config verbose '' :yes If no arguments are provided, all configuration settings are shown: $ timew config verbose = yes ... See also 'hints', 'show'. .TP .B timew continue Resumes tracking the most recently closed interval. For example: $ timew track yesterday 9am - 5pm tag1 tag2 $ timew continue The 'continue' command creates a new interval, starting now, and using the tags 'tag1' and 'tag2'. See also 'start', 'stop'. .TP .B timew day [] [ ...] The day command shows a chart depicting a single day (today by default), with colored blocks drawn on a timeline. The chart summarizes the tracked and untracked time. Accepts date ranges and tags for filtering, or shortcut hints: $ timew day monday - today $ timew day :week $ timew day :month The 'reports.day.range' configuration setting overrides the default date range. The default date range shown is ':day'. The ':blank' hint causes only the excluded time to be shown, with no tracked time. For more details, and precise times, use the 'summary' report. See also 'week', 'month', 'summary'. .TP .B timew diagnostics This command shows details about your version of Timewarrior, platform, how it was built, compiler features, configuration, file access, extensions and more. The purpose of this command is to help diagnose configuration problems, and provide supplemental information when reporting a problem. See also 'extensions'. .TP .B timew export [] [ ...] Exports all the tracked time in JSON format. See also 'import'. .TP .B timew extensions Displays the directory containing the extension programs, and a table showing each extention and its status. See also 'diagnostics'. .TP .B timew gaps [] [ ...] Displays a summary of time that is neither tracked, nor excluded from tracking. The 'reports.gaps.range' configuration setting overrides the default date range. The ':blank' hint causes only the excluded time to be shown, with no tracked time. The default date range shown is ':day'. See also 'summary'. .TP .B timew help [ | interval | hints | date | duration] The help command shows detailed descriptions and examples of commands, interval syntax, supported hints, date and duration formats. For example: $ timew help $ timew help start $ timew help hints $ timew help interval $ timew help date $ timew help duration .TP .B timew join @ @ Joins two intervals, by using the earlier of the two start times, and the later of the two end times, and the combined set of tags. Using the 'summary' command, and specifying the ':ids' hint shows interval IDs. Using the correct IDs, you can identify an intervals to join. For example, show the IDs: $ timew summary :week :ids Then having selected '@1' and '@2' as the intervals you wish to join: $ timew join @1 @2 See also 'split', 'lengthen', 'shorten'. .TP .B timew lengthen @ [@ ...] The 'lengthen' command is used to defer the end date of a closed interval. Using the 'summary' command, and specifying the ':ids' hint shows interval IDs. Using the right ID, you can identify an interval to lengthen. For example, show the IDs: $ timew summary :week :ids Then having selected '@2' as the interval you wish to lengthen: $ timew lengthen @2 10mins Note that you can lengthen multiple intervals,: $ timew lengthen @2 @10 @23 1hour See also 'summary', 'tag', 'untag', 'shorten'. .TP .B timew month [] [ ...] The month command shows a chart depicting a single month (current month by default), with colored blocks drawn on a timeline. The chart summarizes the tracked and untracked time. Accepts date ranges and tags for filtering, or shortcut hints: $ timew month 1st - today $ timew month :week The 'reports.month.range' configuration setting overrides the default date range. The default date range shown is ':month'. The ':blank' hint causes only the excluded time to be shown, with no tracked time. For more details, and precise times, use the 'summary' report. See also 'day', 'week', 'summary'. .TP .B timew move @ The 'move' command is used to relocate an interval intact to a new start time. Using the 'summary' command, and specifying the ':ids' hint shows interval IDs. Using the right ID, you can identify an interval to move. For example, show the IDs: $ timew summary :week :ids Then having selected '@2' as the interval you wish to move: $ timew move @2 9am See also 'summary', 'tag', 'untag', 'lengthen', 'shorten'. .TP .B timew [report] [] [ ...] Runs an extension report, and supports filtering data. The 'report' command itself is optional, which means that these two commands are equivalent: $ timew report foo :week $ timew foo :week This does however assume there is a 'foo' extension installed. .TP .B timew shorten @ [@ ...] The 'shorten' command is used to advance the end date of a closed interval. Using the 'summary' command, and specifying the ':ids' hint shows interval IDs. Using the right ID, you can identify an interval to shorten. For example, show the IDs: $ timew summary :week :ids Then having selected '@2' as the interval you wish to shorten: $ timew shorten @2 10mins Note that you can shorten multiple intervals,: $ timew shorten @2 @10 @23 1hour See also 'summary', 'tag', 'untag', 'lengthen'. .TP .B timew show Displays the effective configuration, in hierarchical form. See also 'config'. .TP .B timew split @ [@ ...] Š…plits an interval into two equally sized, adjacent intervals, with the same tags. Using the 'summary' command, and specifying the ':ids' hint shows interval IDs. Using the right ID, you can identify an interval to split. For example, show the IDs: $ timew summary :week :ids Then having selected '@2' as the interval you wish to split: $ timew split @2 See also 'lengthen', 'shorten'. .TP .B timew start [] [ ...] Begins tracking using the current time, and the specified optional set of tags. If a tag contains multiple words, and therefore contains spaces, use quotes to surround the whole tag. For example, this command specifies two tags ('weekend' and 'Home & Garden'), the second of which requires quotes. $ timew start weekend 'Home & Garden' An optional date may be specified to indicate the intended start of the tracked time: $ timew start 8am weekend 'Home & Garden' Quotes are harmless if used unnecessarily. See also 'continue', 'stop', 'track'. .TP .B timew stop [ ...] Stops tracking time. If tags are specified, then they are no longer tracked. If no tags are specified, all tracking stops. For example: $ timew start tag1 tag2 ... $ timew stop tag1 Initially time is tracked for both 'tag1' and 'tag2', then 'tag1' tracking is stopped, leaving tag2 active. To stop all tracking: $ timew stop See also 'cancel', 'continue', 'start', 'track'. .TP .B timew summary [] [ ...] Displays a report summarizing tracked and untracked time for the current day by default. Accepts date ranges and tags for filtering, or shortcut hints: $ timew summary monday - today $ timew summary :week $ timew summary :month The ':ids' hint adds an 'IDS' column to the summary report output, for interval modification. See also 'day', 'week', 'month', 'shorten', 'lengthen', 'tag', 'untag'. .TP .B timew tag @ [@ ...] [ ...] The 'tag' command is used to add a tag to an interval. Using the 'summary' command, and specifying the ':ids' hint shows interval IDs. Using the right ID, you can identify an interval to tag. For example, show the IDs: $ timew summary :week :ids Then having selected '@2' as the interval you wish to tag: $ timew tag @2 'New Tag' Note that you can tag multiple intervals, with multiple tags: $ timew tag @2 @10 @23 'Tag One' tag2 tag3 See also 'summary', 'shorten', 'lengthen', 'untag'. .TP .B timew tags Displays all the tags that have been used. .TP .B timew track [ ...] The track command is used to add tracked time in the past. Perhaps you forgot to record time, or are just filling in old entries. For example: $ timew track :yesterday 'Training Course' $ timew track 9am - 11am 'Staff Meeting' Note that the track command expects a closed interval (start and end time), when recording. If a closed interval is not provided, the 'track' command behaves the same as the 'start' command. .TP .B timew untag @ [@ ...] [ ...] The 'untag' command is used to remove a tag from an interval. Using the 'summary' command, and specifying the ':ids' hint shows interval IDs. Using the right ID, you can identify an interval to untag. For example, show the IDs: $ timew summary :week :ids Then having selected '@2' as the interval you wish to untag: $ timew untag @2 'Old Tag' Note that you can untag multiple intervals, with multiple tags: $ timew untag @2 @10 @23 'Old Tag' tag2 tag3 See also 'summary', 'shorten', 'lengthen', 'tag'. .TP .B timew week [] [ ...] The week command shows a chart depicting a single week (current week by default), with colored blocks drawn on a timeline. The chart summarizes the tracked and untracked time. Accepts date ranges and tags for filtering, or shortcut hints: $ timew week $ timew week monday - today The 'reports.week.range' configuration setting overrides the default date range. The default date range shown is ':week'. The ':blank' hint causes only the excluded time to be shown, with no tracked time. For more details, and precise times, use the 'summary' report. See also 'day', 'month', 'summary'. .SH INTERVAL An interval defines a block of time that is tracked. The syntax for specifying an interval is flexible, and may be one of: [from] [from] to/- [from] for before/after ago [for] Examples are: from 9:00 from 9am - 11am from 9:00:00 to 11:00 from 9:00 for 2h 2h after 9am 2h before 11:00 2h ago for 2h An interval is said to be 'closed' if there is both a start and end, and 'open' if there is no end date. .SH HINTS Timewarrior supports hints, which are single-word command line features that start with a colon like this: :week Hints serve several purposes. This example is a shortcut for the date range that defines the current week. Other hints, such as: :quiet Are ways to control the behavior of Timewarrior, in this case eliminating all forms of feedback, for purposes of automation. The supported hints are: :quiet Turns off all feedback. For automation :debug Runs in debug mode, shows many runtime details :yes Overrides confirmation by answering 'yes' to the questions :color Force color on, even if not connected to a TTY :nocolor Force color off, even if connected to a TTY :blank Leaves tracked time out of a report :fill Expand time to fill surrounding available gap Only functions when exclusions are provided :ids Displays interval ID numbers in the summary report Range hints provide convenient shortcuts to date ranges: :yesterday The 24 hours of the previous day :day The 24 hours of the current day :week This week :month This month :quarter This quarter :year This year :lastweek Last week :lastmonth Last month :lastquarter Last quarter :lastyear Last year .SH DATES Timewarrior supports the following date formats based on ISO-8601: [T ] Extended date, optional extended time [T