A command line interface for time tracking by project.
Track time by Project
Tempo tracks time against projects. Projects can be nested, and tagged, and each time entry can have an additional description. Time reports are produced by day.
Future enhancements will include reports by project and time totals by day or by project.
All records are produced in YAML files, at the root user directory. These reports can be edited by hand, but keep in mind that any invalid data could cause problems when it is read back into the app. Make sure time formatting is valid and that they don't overlap, and that all ids are unique per page.
Each day's time records are designed to work independently. When adding or updating time records, only the records for the days in question are loaded into the app. The most recent day's records will also always be read in, to assure no running records are created earlier than existing records.
command line assistance
tempo help for a list of commands
tempo [command] --help for help on any command
All commands and command options can be abbreviated to the first letter:
# these two commands are the same:
Commands that manage the projects will use fuzzy matching for the project name. This means if you have a project called "put on my big boy pants" you will be able to checkout this project by running
tempo checkout pants. If you have a situation where fuzzy matching causes errors because it matches with more than one project, you can always use the --exact flag, and pass in an exact match.
Every project and time record has an id which can also be used to match against. Running commands with the global --id flag will include ids in the output. Time record ids are on a per-day basis, and begin again with an id of 1 on the next day.
Before you begin using tempo, you must have at least one project. Projects can be tagged, and organized as sub-projects. To view your projects, look at ~/tempo/tempo_projects.yaml
Manage the Projects that timed tasks are assigned to
tempo [global options] p [command options] "name of the project"
--add - Add a Project --delete=title - Delete a Project --exact - Exact Match --id - List by or perform command by project Id --list - List Projects --tag=tagword - Tag a Project --untag=tagword - Untag a Project
Manage the Projects that timed tasks are assigned to. By default, lists the current project, or with --list tag, lists all projects. The active project will be marked by an asterisk.
If supplied with arguments and no command options, a new project will be added.
# list current project
Checkout a project to track time against
tempo [global options] checkout [command options] "name of the project"
--add=title - Add and Checkout a new project --exact - use an exact match for project title --id - checkout by project id
Only one project is active at a time, and this project will be assigned to all new time records. You can checkout existing projects, or use this command to create a new active project
# checking out an existing project titled 'star gazing'
Arrange project hierarchy
tempo [global options] arrange [command options] [parent project] : child project
--exact - use an exact match for project title --id - checkout by project id
Arrange projects into a parent/child hierarchy
New projects are added as root projects by default. Use arrange to arrange existing projects as child or root projects. If no parent project is supplied (to the left of the semicolon) the project will become a root project.
# Arrange an existing project as a root project
Start a time entry
tempo [global options] start [command options] description
--at=time --end=time Starts a new time entry, and closes out any running time entries. You can also add a description of the time entry. To start a time entry at a time other than the current, pass it in as an argument to the --at flag. This will accept a number of human readable formats, multiple word time formats should be enclosed in quotes
# start a new time record at the current time with no description
End a time entry
tempo [global options] end [command options] time out, defaults to now
--at=time Closes out any running time entries. You can optionally add a description of the time entry, which will overwrite the current description. To end a time entry at a time other than the current, pass it in as an argument to the --at flag. This will accept a number of human readable formats, multiple word time formats should be enclosed in quotes.
# creating an entry at 4:55pm, then ending it 5 minutes later and changing the description
Update a time entry
tempo [global options] update [command options] [description]
--delete - Delete a Time Entry --end=time - Update the End Time --id=number - Select by Id --on=date - Select On Date --project - Update to the active project --start=time - Update the Start Time
update the project, start time, or end time for a time entry.
Defaults to the current time entry, or most recently completed time entry if none are running. Optionally, you can supply an id for a time entry on the current day, or a day and id to update previous time entries.
The description, if passed in, will be used to replace the existing description. You can also change the start or end time, or delete the entire time entry.
# update description for the last time entry
Report time entries
tempo [global options] report [command options] [day]
--from=time - begin time records on this date --to=time - end time records on this date Reports time entries for a day or a period of days. By default, lists the last recorded day's entries. To list a different day, supply a day as the args. To list a series of records, include a --from and --to value
# report current day's entries
Assumptions and Limitations
All records are rounded to the nearest minute. Time records are organized by day, and close out on the day they were started.
Tempo uses Chronic to parse time formats, which adds a lot of convenience functions such as "yesterday at 5:00". Chronic does have some limitations and inconsistencies as well, please see the https://github.com/mojombo/chronic/issues if you find problems with time parsing.
No overlapping projects
It is assumed only one time record can exist for any given time. Overlapping time entries will result in an error.
Only one running project
One entry can be running at any given time, and it must be the most recent entry. Older entries will be closed out when a new one is started, and if the entry is running on a previous day, it will be closed out on the last minute of that day.
Project development is on-going and in my spare time. Any error reporting, pull requests, and suggestions welcome.
- add a config file with global options.
- add an option to change the location of the tempo file structure (for syncing with Dropbox, for instance).
- add an archive capability, which hides inactive projects from project lists. This can be handled with an tag keyword 'archived'.
- allow adding a new project and listing all projects in the same command.
- Allow start to use a project other than the current one.
- Add a command to start the last time entry running again.
- Add a command to start a new time entry with the same details as a previous one.
Time format enhancements
- Updating time record start or end time using
--onshould not need the full date repeated for
- invalid times should be retried with the current (or most logical) date. Example: if '9:00' doesn't work, try 'today at 9:00'
- Recording output to file
- Reporting by project
- Composite view records (grouped time records by day or project), to allow nested list reporting
- Total hours by project or day
- Alternative formats: JSON, HTML
Running in development
You need to use
bundle exec bin/tempo to run in development
rakes default behavior is to run unit tests and all cucumber features
run unit tests only
bundle exec rake test to run unit tests only
run only some cucumber features
add @focus before specific features and run
bundle exec rake features focus
Testing creates a test directory at ~/testing/
You can cleanup the testing directories with
bundle exec rake clean
Other command line time tracking apps:
This is a very opinionated time tracking app, you may find others that suit your working method better:
If you would prefer to keep your data in a database, or run independant time sheets by project, here is a utility that uses SQLite:
Another one worth checking out for a lightweight time tracker: