{ "info": { "author": "Andy Pearce", "author_email": "andy@andy-pearce.com", "bugtrack_url": null, "classifiers": [ "Development Status :: 5 - Production/Stable", "Environment :: Console", "Intended Audience :: End Users/Desktop", "License :: OSI Approved :: MIT License", "Natural Language :: English", "Operating System :: OS Independent", "Programming Language :: Python", "Programming Language :: Python :: 2", "Topic :: Office/Business", "Topic :: Office/Business :: News/Diary", "Topic :: Utilities" ], "description": "======\nTTrack\n======\n\nOverview\n========\n\nTTrack is a very simple command-line time-tracking tool written in Python.\nIt allows you to create tasks and then track time spent working on them.\nAggregate reports of the time spent on tasks can be produced, and arbitrary\ntags can be applied to tasks for flexible categorisation.\n\n TTrack was written for use on Unix-like platforms, and appears to\n work on both Linux and OSX. It hasn't been tested on Windows at all,\n although I would hope that any compatibility issues would be minor.\n\n\nInstallation\n============\n\nInstall the ``ttrack`` package from PyPI - note that it depends on the\n``cmdparser`` package, also available on PyPI. For example, to install using\n``pip``::\n\n pip install ttrack\n\nWhen first run, an SQLite database is created in your home directory in a file\ncalled ``.timetrackdb``. It's currently not possible to change the name used\nfor this file, although it would be a simple code change to do so. This file\ncontains the entire database - removing it will lose all data.\n\nAdditionally, the file ``.timetrackhistory`` is created in the same place to\nstore command history.\n\n\nTask Tracking Basics\n====================\n\nWhen executed with no arguments, TTrack enters interactive mode. Commands\ncan be entered at the ``ttrack>>>`` prompt, and tab-completion should work for\ncommand names and most arguments.\n\nThe ``help`` command can be used to list available commands, providing a\ncommand as an argument provides more detailed help for that command. For\nexample, try ``help create``.\n\nTTrack works on the basis of \"tasks\", which are referred to with a simple\nname. I suggest keeping names lower-case and avoiding spaces, but you can\nchoose any names you wish. If you wish to include spaces in any name, you'll\nneed to surround it with double-quotes at the ``ttrack>>>`` prompt (or use\nsuitable shell quoting if using command-line arguments).\n\nLet's run through some basic workflow as an example - don't worry, you can\neasily delete your ``~/.timetrackdb`` file to erase everything you do here.\n\nFirst, create some tasks::\n\n ttrack>>> create task projectx\n ttrack>>> create task projectz\n ttrack>>> create task bug1234\n\nYou can now list the tasks that you've created::\n\n ttrack>>> show tasks\n\nYou can use the ``start`` command to start work on a task::\n\n ttrack>>> start project2\n\nIf you omit the task name, the most recently-created task will be assumed.\n\nThe ``status`` command shows you what you're working on now, and what you were\nworking on previous to that, if anything::\n\n ttrack>>> status\n\nWhilst working on a task, you can add \"diary\" entries to it, which are\nintended to be small reminders of your progress. To do this, simply use the\n``diary`` command, where the remainder of the line becomes your diary entry::\n\n ttrack>>> diary Finished planning on Project X, on to phase 1 development.\n\nIf you just enter a blank ``diary`` command, TTrack will prompt you to enter\nan entry terminated by a full-stop (``.``) on a line by itself - this allows\nyou to enter multi-line diary comments.\n\nFeel free to add more diary entries. Each entry will be marked with the time\nat which you add it and the current task that was in effect at that time.\nYou can display your diary entries for this task with::\n\n ttrack>>> show diary task projectx\n\nYou can also track \"todo\" items for projects. These are just arbitrary text\nwhich are associated with a task and can be marked as completed. To add a new\n\"todo\" item to Project X::\n\n ttrack>>> todo projectx Implement phase 1.\n\nAny \"todo\" item on the currently active task can be marked as \"done\"::\n\n ttrack>>> todo done Impl\n\nNote that only a unqiue portion of the \"todo\" item text need be specified - you\nwill receive a warning if there is ambiguity within a task (but it's perfectly\nacceptable for \"todo\" text to be identical between tasks). Any completed \"todo\"\nitems will appear in the diary for a task, and any outstanding items can be\nshown with::\n\n ttrack>>> show todos\n\nIf you start working on a new task, the old task is automatically stopped::\n\n ttrack>>> start projectz\n\nIf you use the ``status`` command now you should see that the current task has\nchanged and the previous task is now filled in. You can switch between tasks\narbitrarily, and TTrack always allocates your time against the current task.\n\nSince work on tasks can often be interrupted, there is a command which allows\nyou to easily revert to the previously active task::\n\n ttrack>>> resume\n\nIf working on a task, this command will switch you back to the previous task.\nThis is simply a convenience for the equivalent ``start`` command, to avoid you\nhaving to type the task name again.\n\nYou can also stop allocating your time to anything - for example, when it's\ntime to leave the office or go to bed::\n\n ttrack>>> stop\n\nIf you execute ``resume`` whilst no task is active, it will restart whatever\ntask was most recently active.\n\n\nTags and Listing\n================\n\nTasks can be organised by using tags. A tag is a name which can be applied to\nany set of tasks, and reports can be generated based on these. Tags can be\nused as categories, but note that unlike conventional categories a task can\nhave multiple tags applied to it at once.\n\nThe links between tags and tasks can be changed at any point, and this change\nis applied retrospectively - in other words, reporting is always based on the\ncurrent state of tags, not the state as it was when the tasks were current.\nThis can be powerful, as it means that you can start recording task time\nquickly without worrying too much about how to report on it, and then assign\nand change tags later for reporting purposes.\n\nContinuing the example above, create some tags and add them to tasks::\n\n ttrack>>> create tag projects\n ttrack>>> create tag commercial\n ttrack>>> task projectx tag projects\n ttrack>>> task projecty tag projects\n ttrack>>> task projecty tag commercial\n\nIf you wish to remove a tag at a later stage, you can use ``task X untag Y``\nin the same way.\n\nAs a shortcut, when creating a task you can optionally specify a list of one\nor more tags after the task name, which saves additional ``task`` commands to\nadd them::\n\n ttrack>>> create task project-profit projects commercial\n\nWhen listing tasks, the tags for that task are shown after the task name::\n\n ttrack>>> show tasks\n All tasks:\n projectx (projects)\n projecty (projects, commercial)\n project-profit (projects, commercial)\n bug1234\n\nWhen listing tags with ``show tags``, the number of tasks with that tag\nattached is shown - this can be useful to determine which tags are obsolete.\n\nOn the subject of the ``show`` command, the ``diary`` and ``todos`` variants\ncan optionally filter by tag or task. For example, to show the diary entries\nfor only tasks tagged with ``projects``::\n\n ttrack>>> show diary tag projects\n\n\nReports\n=======\n\nNow you've created some tasks and tags, and allocated some time to them,\nit's time to learn how to generate reports based on that time. Reports are\nall generated with the ``summary`` command. It's syntax is a little\ncomplicated, but the examples below should help get you started.\n\nFirstly, reports can be generated split by task or split by tag - hence, the\nfirst argument is either ``task`` or ``tag`` to indicate which you want.\n\nThe second argument specifies the type of report that you can generate - there\nare currently four types:\n\n``time``\n This produces a report of the time spent on each entry.\n``switches``\n Shows the number of times the specified task interrupted others.\n``diary``\n Shows all diary entries.\n``entries``\n Shows raw task times.\n\nFollowing the report type, the period over which the report should be run is\nspecified - the syntax for this is fairly flexible and some examples of\nwhat will be accepted are:\n\n* ``yesterday``\n* ``2 weeks ago``\n* ``last month``\n* ``December 2012``\n* ``between 15/10/2011 and today``\n\n..\n\n When providing two dates to run the report, bear in mind that the\n first date will be inclusive but the second date will be exclusive (so the\n example \"between 15/10/2011 and today\" won't include today).\n\nFinally, if splitting by task (only), a the keyword ``tag`` followed by a tag\nname can be specified at the end of the command. If so, the list of tasks\ndisplayed will be filtered to be those with the specified tag applied.\n\nIn case you're thinking that all sounds a bit too complicated, here are some\nsimple examples which probably cover most of what you need, followed by an\nexplanation of what will be displayed.\n\n``summary task time this week``\n Display a summary of the time spent on each task so far this week.\n\n``summary tag time yesterday``\n Display a summary of the time spent yesterday on tasks in each tag.\n\n``summary task switches last month``\n Display the number of times each task interrupted another one in the\n previous month.\n\n``summary task diary this month tag projects``\n Display diary entries recorded so far this month for all tasks with tag\n ``projects``.\n\nNote that the ``entries`` summary mode is typically used when fixing up\nincorrectly recorded times, as it's the only way of determing the unique\nID of a time entry in the database. This is a more advanced usage which isn't\ncovered in this basic tutorial.\n\nThe ``switches`` report probably needs a little more explanation. The intention\nis to allow you to record interruptions (or \"context switches\") you suffer\nduring the day and get some idea of how frequently your flow is interrupted.\nFor this to work you'll have to create tasks to track all the things which\ndisturb you - for example, if you are interrupted by calls from customers,\nyou could create a task ``customersupport`` to track this.\n\nRemember that context switches are budgeted against the new task (i.e. the\n\"interrupting\" task), not the old one (i.e. the \"interrupted\" task).\n\nTo count as a context switch and be included in the totals for the ``switches``\nreport, a task must be different to the previous task and start less than a\nminute after the first one ended. When reporting by tag rather than task,\nthe switch is only counted if the new task has at least one tag which the old\ntask does not.\n\nFor example, if two different tasks both have only the ``coding`` tag then\nswitching between them will count as a context switch in a ``task`` report,\nbut not in a ``tag`` report. By comparison, if the old task was tagged\nwith ``A``, ``B`` and ``C`` and the new task tagged with ``C``, ``D`` and ``E``\nthen the context switches count would be incremented for tags ``D`` and ``E``\nonly as a result of the task switch.\n\n\nAdvanced Usage\n==============\n\nMany of the commands have additional arguments to fix problems when you've\nforgotten to start or stop tasks at the correct time - these allow the time\nat which the event occurs to be overridden. For example, if you leave work on\nFriday and forget to execute ``stop``, you can do so on Monday and make it\nretrspective by specifying a time: ``stop last Friday at 17:35``.\n\nUnfortunately, however, I haven't had chance to document these more advanced\nusages in this README, but the ``help`` command may give you the details you\nneed. TTrack tries its best to prevent you creating entries which overlap, on\nthe assumption that you can only be doing one task at a time, but it pays to\nbe a little cautious if you value the records you have in the database so far.\nIf in doubt, you can take a copy of the ``~/.timetrackdb`` file before playing\naround, and re-instate the old data by simply copying it back into place\nif things seem to be broken.\n\n\nFeedback\n========\n\nIf you have any questions, problems or requests, please get in touch with me\nat andy@andy-pearce.com. If you want to submit a bug, please do so via\n`GitHub's issue tracker`_.\n\nIf you want to make changes, the source code is available at GitHub_ - feel\nfree to send me pull requests if you make an improvement you feel others would\nfind useful.\n\n.. _GitHub: https://github.com/Cartroo/ttrack\n.. _`GitHub's issue tracker`: https://github.com/Cartroo/ttrack/issues", "description_content_type": null, "docs_url": null, "download_url": "UNKNOWN", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "http://cartroo.github.com/ttrack/", "keywords": null, "license": "LICENSE.txt", "maintainer": null, "maintainer_email": null, "name": "ttrack", "package_url": "https://pypi.org/project/ttrack/", "platform": "UNKNOWN", "project_url": "https://pypi.org/project/ttrack/", "project_urls": { "Download": "UNKNOWN", "Homepage": "http://cartroo.github.com/ttrack/" }, "release_url": "https://pypi.org/project/ttrack/1.1.0/", "requires_dist": null, "requires_python": null, "summary": "Command-line time tracking utility", "version": "1.1.0" }, "last_serial": 800994, "releases": { "1.0.0": [ { "comment_text": "", "digests": { "md5": "2087ffc7292829e054f7fbf9c055ec49", "sha256": "4e4863d286f6b46fa19cb49b1af4417b004813ac0870a4ebc592cf237870e8b9" }, "downloads": -1, "filename": "ttrack-1.0.0.tar.gz", "has_sig": false, "md5_digest": "2087ffc7292829e054f7fbf9c055ec49", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 31796, "upload_time": "2012-12-18T13:35:08", "url": "https://files.pythonhosted.org/packages/2e/c2/f4a8b4e5f07c34f5e58320af8abdf4d199fbff07bb0bbc86577bbf2d1a2c/ttrack-1.0.0.tar.gz" } ], "1.1.0": [ { "comment_text": "", "digests": { "md5": "3c31c29fbcd5ed33c85b2f6095e33b4f", "sha256": "e9068e0f60b5eb06aab987a2b01367f3bb8f17d2fd9a876fec5636733e1b6ca6" }, "downloads": -1, "filename": "ttrack-1.1.0.tar.gz", "has_sig": false, "md5_digest": "3c31c29fbcd5ed33c85b2f6095e33b4f", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 34018, "upload_time": "2013-03-26T12:27:19", "url": "https://files.pythonhosted.org/packages/e6/aa/82e996742ad9756c149e96f91581973774a72901faf872f597824927bb55/ttrack-1.1.0.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "3c31c29fbcd5ed33c85b2f6095e33b4f", "sha256": "e9068e0f60b5eb06aab987a2b01367f3bb8f17d2fd9a876fec5636733e1b6ca6" }, "downloads": -1, "filename": "ttrack-1.1.0.tar.gz", "has_sig": false, "md5_digest": "3c31c29fbcd5ed33c85b2f6095e33b4f", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 34018, "upload_time": "2013-03-26T12:27:19", "url": "https://files.pythonhosted.org/packages/e6/aa/82e996742ad9756c149e96f91581973774a72901faf872f597824927bb55/ttrack-1.1.0.tar.gz" } ] }