dob 3.1.1

journal and time tracker, supercharged for the terminal

dob is an interactive, terminal-based time tracking application.

You’ll find Vim-like navigation, robust functionality, a customizable user experience, lots of great plugins, and an elegant, minimalistic interface.

dob is written in Python and installs easily with pip:

$ pip3 install dob

The best way to learn dob is to run the demo:

$ dob demo

For other setup options, read the installation guide.

• Hint: You might need to update PATH or find where pip installs dob.

Quick Peek

dob has lots of CLI commands, and it also includes an interactive terminal application.

Here’s a little taste of what the terminal application looks like.:

╭────────────────────────────────────────────────────────────────────────────────╮
│             Thu 16 Apr 2020 ◐ 02:13 PM — 03:52 PM                              │
╰────────────────────────────────────────────────────────────────────────────────╯

  duration........... :  1 hour  39 minutes
  start.............. : 2020-04-16 13:13:49
  end................ : 2020-04-16 14:52:50
  activity........... : dobumentation
  category........... : dob Development
  tags............... : #readme

┌────────────────────────────────────────────────────────────────────────────────┐
│I'm adding this Fact to the README. So meta.                                    │
│                                                                                │
│                                                                                │
│                                                                                │
│                                                                                │
│                                                                                │
│                                                                                │
└────────────────────────────────────────────────────────────────────────────────┘
Fact ID #22618                              [?]: Help / [C-S]: Save / [C-Q]: Quit

Though in your terminal, you’ll see colors and font ornamentation (bold, italic, and underline).

Status

dob is released to beta!

• You can demo dob to see how awesome it is!

• You can also start using dob!

  But just be aware that it has not been vetted yet for a larger audience — you might still encounter a few issues. But please report them, and we’ll get them fixed.

  We just don’t want you to have a bad first experience.

  Aka, you’ve been warned!

  (Nonetheless, the dob beta uses a backup file judiciously, so if it does crash, you should not lose any unsaved data.)

dob is already feature-rich, and it’s used daily (hourly!) by the authors.

To see what all the fuss is about, you can pip3 install dob and run dob demo right now to try it out.

Or, keep reading for an overview of dob, a list of its features, and then detailed documentation of the interactive editor commands.

OS Support

dob runs on any operating system that supports Python, including Linux, macOS, and Windows.

Please see the installation guide for help getting setup.

Quick Start

If you want to dive right in (after running the demo to get acquainted), try:

$ dob init
$ dob edit

The init command creates a config file and the database, and the edit command runs the interactive editor.

You can also run dob --help to see an overview of all commands.

Ethos

dob is a designed for developers, but suitable for any individual whose comfortable in the terminal.

dob is perfect for the person who asks, Why must I use my mouse to manage time tracking?

dob is even more suited for the person who asks, How can I manage time tracking with the fewest possible keystrokes?

dob is inspired by Hamster, a beloved but aged time tracking application for GNOME.

dob is emulative of Vim, an editor that enables users to concentrate on their work while the tool itself slips into the background.

Try dob today – you might like it!

• Demo dob to learn it.

• Then, start from scratch,

  or load a legacy database.

If you like dob, hopefully you’ll help us make it better!

Features

• Minimalist interactive console app fits elegantly into your terminal-based workflow.

• Robust configuration – and manageable via CLI if you want to avoid the config file.

• Fully customizable – change which keys map to which commands.

• Define your own user-specific paste commands – assign your own activities and tags.

• Undo and redo edits as you work – don’t worry if you make a mistake.

• Auto-complete makes it easy to set activities and tags – and shows useful stats, too.

• Edit text in your favorite $EDITOR – and set a file extension for highlighting.

• Use all the Unicode you want – spice up your notes!

• Personalize the interface colors – and style your own activity and tag names!

• Natural syntax lets you dob “offline” to a text file, that you can import later.

• Migrates legacy Hamster databases – and repairs integrity issues, too.

• Supports unrestricted plugin access – anyone can add their own commands and config.

• Includes command shortcuts – common command sequences mapped to a single keypress.

• Runs on the latest Python (3.6, 3.7, and 3.8).

• Broad desktop OS support – runs on Linux, macOS, and Windows.

• Suitably tested (though coverage could be better).

• Well documented – get help at runtime, on the command line, or online.

• Simple, smooth code base – follows best practices, and uses top libraries.

• Low bar of entry to get raw access to data – defaults to Sqlite3 file.

• Constant dogfooding (– I dob daily!)

• Free and open source – hack away!

Demo

Demo dob

Run the demo command to load an interactive tutorial:

$ dob demo

And then follow the walk-through.

Getting started

Read basic usage to learn how to create an empty data store, or how to import an existing database.

Learning dob

You’ll find lots of documentation online, including:

• Configure dob

• Choose your $EDITOR

• Run the Interactive Editor

• Exit, Save, and Undo/Redo

• Navigate Facts Quickly

• Edit Facts and Metadata

• Copy and Paste Metadata

• Useful Command Combinations

• Nudge Start and End Time

Plugins

Plugins make it easy for everyday dobbers to write their own features and to share them with the broader community.

The core development team has created the following plugins for non-essential and distribution-specific features.

Please note: these plugins are not yet published! (We just want to get you excited in the meantime.)

• The dob-plugin-export-commit plugin exports and commits changes to your dob database on every save.

• The dob-plugin-stale-fact-goader plugin displays a GNOME-style popup notification after some amount of inactivity to badger you to start a new Fact.

• The dob-plugin-git-hip plugin tags the active Fact based on the Git branch name pulled from the current directory.

Have a great idea for dob? Implement it as a plugin!

• Plugins have complete access to dob.

  Plugins can add their own commands.

  Plugins can add their own configuration.

  Plugins can run on startup, on exit, or whenever the user saves.

Plugins help keep dob lean, and they let you turn an idea into a feature quickly and easily!

Thanks!

We hope you enjoy using dob as much as we have had making it!

And if you like it, please tell your friends and colleagues about it. Tell the whole world!!

Keep on dobbin’!