*taskwiki.txt* Taskwarrior tasks in Vimwiki v0.8.4 ~ _____ _ __ ___ _ _ ~ a |_ _|_ _ ___| | _\ \ / (_) | _(_) a ~ command-line | |/ _` / __| |/ /\ \ /\ / /| | |/ / | personal wiki ~ todo list | | (_| \__ \ < \ V V / | | <| | for vim ~ manager |_|\__,_|___/_|\_\ \_/\_/ |_|_|\_\_| ~ ~ ============================================================================== QUICK-REFERENCE -- use "t" and one of: -- *taskwiki-quickref* | a annotate | C calendar | Ga ghistory annual | p projects | | bd burndown daily | d done | hm history month | s summary | | bw burndown weekly | D delete | ha history annual | S stats | | bm burndown monthly | e edit | i (or ) info | t tags | | cp choose project | g grid | l back-link | + start | | ct choose tag | Gm ghistory month | m modify | - stop | ============================================================================== CONTENTS *taskwiki-contents* 1. Introduction |taskwiki| 2. Requirements |taskwiki-requires| 3. Installing |taskwiki-install| 4. Optional enhancements |taskwiki-optional| 5. Mapping |taskwiki-mapping| 6. Commands |taskwiki-commands| 7. Settings |taskwiki-settings| 8. Troubleshooting |taskwiki-trouble| 9. Contributing |taskwiki-contribute| 10. Credits |taskwiki-credits| 11. License |taskwiki-license| ============================================================================= 1. INTRODUCTION *taskwiki* Taskwiki enhances simple vimwiki task lists by storing the task metadata in Taskwarrior. Taskwarrior uses plaintext data files as a backend, and taskwiki uses Taskwarrior as a backend. This allows taskwiki to leverage its powerful features, such as filtering, recurrent tasks, user defined attributes or hooks. ---------------------------------------------------------------------------- Individual tasks ~ * [ ] Install Taskwiki Such tasks get synced to TaskWarrior when the file is saved. Additional metadata, as project, tags, priority, can be stored with this task. Some of that metadata gets visually represented in vim, and is updated if the representation changes in vim. ~ * [ ] Install Taskwiki !!! (2015-08-23 19:00) ---------------------------------------------------------------------------- Task lists Tasks can be grouped - simply written in one block. This has the advantage of any child tasks being marked as dependencies of the parent tasks. ~ * [ ] Get married ~ * [ ] Find a girlfriend ~ * [ ] Buy a ring ~ * [ ] Propose ---------------------------------------------------------------------------- Viewports Viewport is a header with a task query (filter) embedded, generating the corresponding task list. These tasks can be modified and changes will be synced back to task data. A simple viewport can look as follows: ~ == Home tasks | project:Home == Filter query is concealed. Upon saving, this will generate the list of matching tasks, in a tree-like fashion (respecting dependencies). ~ == Home tasks | project:Home == ~ * [ ] Feed the dog (2015-08-08) ~ * [ ] Tidy up the house !! ~ * [ ] Wash the dishes ~ * [ ] Declare war on the cobwebs Tasks added (written) to the task list under the viewport inherit the defaults from its filter. ~ == Home tasks | project:Home == ~ * [ ] Feed the dog ~ * [ ] Tidy up the house !! ~ * [ ] Wash the dishes ~ * [ ] Declare war on the cobwebs ~ * [ ] Call the landlord about rent payment (2015-08-23) ~ ^ the task above will have project:Home set automatically For some more complex filters, defaults cannot be automatically derived. In such case, you can specify the defaults explicitly: ~ == Urgent tasks | +OVERDUE or +urgent | +urgent == ~ ^ defaults definition Viewports can be inspected by hitting [CR] with cursor above them. ---------------------------------------------------------------------------- Report splits Taskwiki can provide additional information reports on a task list (selected, or part of a viewport) and on individial tasks as well. These reports are shown in dynamic temporary splits. ~ * [ ] Tidy up the house !! (2015-08-23 00:00) For example, hitting [CR] on the above task runs :TaskWikiInfo and displays: Name Value ------------- --------------------------------------------------------- ID 6 Description Tidy up the house 2015-08-22 21:29:35 Tip: Use roomba for vacuum-cleaning Status Pending Project Home Entered 2015-08-22 21:27:26 (2 minutes) Due 2015-08-23 00:00:00 Last modified 2015-08-22 21:30:21 (1 second) Virtual tags ANNOTATED MONTH PENDING READY UNBLOCKED YEAR UUID 448c2fa9-6a06-454e-a2bc-b0c8ae91994f Urgency 9.895 Priority H Date Modification ------------------- ------------------------------------------------------------ 2015-08-14 21:29:35 Annotation of 'Tip: Use roomba for vacuum-cleaning' added. 2015-08-14 21:30:11 Due set to '2015-08-23 00:00:00'. Running the :TaskWikiSummary can produce side-split like this: Project Remaining Avg age Complete 0% 100% ------------------ --------- -------- -------- ------------------------------ Work 18 4 weeks 74% ====================== Designs Feature X 3 4 weeks 89% ========================== Feature Y 7 2 weeks 47% ========= Tickets 5 3 weeks 79% ====================== Blog 1 4 months 50% =============== There are many more reports (burndown, calendar, history, projects, stats, summary, tags,..), but for the sake of brevity, they will not be described here. They work in a similiar fashion. ============================================================================= 2. REQUIREMENTS *taskwiki-requires* * Vim 7.4 or newer, compiled with +python * [Vimwiki](https://github.com/vimwiki/vimwiki/tree/dev) (the dev branch) git clone https://github.com/vimwiki/vimwiki ~/.vim/bundle/ --branch dev * [Taskwarrior](http://taskwarrior.org) (version 2.4.0 or newer) - install either from [sources](http://taskwarrior.org/download/) or using your [package manager](http://taskwarrior.org/download/#dist) sudo dnf install task * [tasklib](https://github.com/tbabej/tasklib/tree/develop) (the develop branch) - Python library for Taskwarrior. sudo pip install --upgrade git+git://github.com/tbabej/tasklib@develop Taskwiki will automatically check whether the Vim and tasklib versions are sufficient, and raise error if not. ============================================================================= 3. INSTALLING *taskwiki-install* Using pathogen (or similiar vim plugin manager), the taskwiki install is as simple as: git clone https://github.com/tbabej/taskwiki ~/.vim/bundle/taskwiki However, make sure your box satisfies the requirements stated above. To access documentation, run :helptags and then :help taskwiki. ============================================================================= 4. OPTIONAL ENHANCEMENTS *taskwiki-optional* The following optional plugins enhance and integrate with TaskWiki. At very least,I'd recommend the AnsiEsc plugin - Taskwarrior charts are much more fun when they're colorful! * [vim-plugin-AnsiEsc](https://github.com/powerman/vim-plugin-AnsiEsc) adds color support in charts. git clone https://github.com/powerman/vim-plugin-AnsiEsc ~/.vim/bundle/ * [tagbar](https://github.com/majutsushi/tagbar) provides taskwiki file navigation. git clone https://github.com/majutsushi/tagbar ~/.vim/bundle/ * [vim-taskwarrior](https://github.com/farseer90718/vim-taskwarrior) enables grid view. git clone https://github.com/farseer90718/vim-taskwarrior ~/.vim/bundle/ ============================================================================= 5. MAPPING *taskwiki-mapping* n is mapped to show task info, VP details or follow vimwiki link After editing a task in insert mode, starts a new task Normal mode key mappings (those with "v" also work in visual mode) t + vn a |:TaskWikiAnnotate| n bd |:TaskWikiBurndownDaily| n bw |:TaskWikiBurndownWeekly| n bm |:TaskWikiBurndownMonthly| vn cp |:TaskWikiChooseProject| vn ct |:TaskWikiChooseTag| n C |:TaskWikiCalendar| vn d |:TaskWikiDone| vn D |:TaskWikiDelete| vn e |:TaskWikiEdit| vn g |:TaskWikiGrid| n Gm |:TaskWikiGhistoryMonthly| n Ga |:TaskWikiGhistoryAnnual| n hm |:TaskWikiHistoryMonthly| n ha |:TaskWikiHistoryAnnual| vn i |:TaskWikiInfo| vn l |:TaskWikiLink| vn m |:TaskWikiMod| n p |:TaskWikiProjects| n s |:TaskWikiProjectsSummary| n S |:TaskWikiStats| n t |:TaskWikiTags| vn + |:TaskWikiStart| vn - |:TaskWikiStop| ============================================================================= 6. COMMANDS *taskwiki-commands* ----------------------------------------------------------------------------- Split reports commands. This family of commands displays TaskWarrior reports in a read-only vertical/horizontal split. Size of these splits can be limited, see |taskwiki_max_split_height| and |taskwiki_max_split_width| options. These commands will by default use filter from the nearest viewport. If you want to display report window using global, non-filtered data, explicitly pass the 'global' argument, i.e: :TaskWikiStats global To specify an explicit filter, you can use the filter as the argument, i.e: :TaskWikiStats project:Home To close the split windows, just hit or "q". NOTE: To allow color output in the split windows, make sure you have AnsiEsc vim plugin installed, see |taskwiki-optional|. List of split report commands: *:TaskWikiBurndownDaily* [args] *:TaskWikiBurndownWeekly* [args] *:TaskWikiBurndownMonthly* [args] Opens a horizontal split window with the burndown report. *:TaskWikiCalendar* [args] Opens a horizontal split window with the calendar report. *:TaskWikiGhistoryMonthly* [args] *:TaskWikiGhistoryAnnual* [args] Opens a horizontal split window with the ghistory report. *:TaskWikiHistoryMonthly* [args] *:TaskWikiHistoryAnnual* [args] Opens a horizontal split window with the history report. *:TaskWikiProjects* [args] Opens a vertical split window with the projects report. *:TaskWikiProjectsSummary* [args] Opens a vertical split window with the summary report. *:TaskWikiStats* [args] Opens a vertical split window with the stats report. *:TaskWikiTags* [args] Opens a vertical split window with the tags report. ----------------------------------------------------------------------------- Commands operating on selected tasks. This group of commands operates on a selected tasks. Selected tasks can be either the task which is currently under cursor, or any group of visually selected tasks. *:TaskWikiAnnotate* Opens a prompt to add annotation to selected task(s). *:TaskWikiDone* Marks the selected task(s) as completed. *:TaskWikiDelete* Deletes the selected task(s). Removes them from the file. *:TaskWikiEdit* Opens the task in a separate vim instance using 'task edit'. *:TaskWikiGrid* Opens a new buffer with the selected ViewPort displayed as a grid. Requires vim-taskwarrior plugin, see |taskwiki-optional|. *:TaskWikiInfo* (or over a task) Opens a split window with the info report of task under the cursor. To close the split, use "q" or . NOTE: This split can have very big height for tasks with many past modifications. See |taskwiki_split_max_height|. *:TaskWikiLink* Adds an annotation to selected task(s) with ~/path/to/file.wiki. *:TaskWikiStart* "Starts" the selected task(s). *:TaskWikiStop* "Stops" the selected task(s). *:TaskWikiMod* [mods] Opens a prompt for task modification, for selected task(s). ---------------------------------------------------------------------------- Interactive commands. Following commands work similiarly as the previous group, they can operate on selected tasks. The modification is done via choosing the particular modification (project, tag) in a split window. *:TaskWikiChooseProject* Interactively choose project for selected task(s) by hitting over the desired value in the split window. Use "q" to close the split, without performing any modifications. *:TaskWikiChooseTag* Interactively choose tag for selected task(s) by hitting over the desired value in the split window. Use "q" to close the split, without performing any modifications. ---------------------------------------------------------------------------- Meta commands This group of commands is directly related to taskwiki or taskwiki specific constructs. *:TaskWikiBufferLoad* Updates the tasks from the Taskwarrior database. This command is run automatically when the taskwiki file is opened. *:TaskWikiBufferSave* Saves the changes to the Taskwarrior database. This parses and saves all the buffer-only changes (such as changing the description, or due date). This command is run automatically when the taskwiki file is saved. NOTE: Using commands such as |:TaskWikiDone| or |:TaskWikiMod| will save the modifications both in the buffer and the Taskwarrior database. *:TaskWikiInspect* (or over a viewport) Opens a split window with details of viewport under the cursor. To close the split, use "q" or . ============================================================================= 7. SETTINGS *taskwiki-settings* *taskwiki_taskrc_location* The location of the taskrc file used by taskwiki. Defaults to ~/.taskrc. *taskwiki_data_location* The location of the data directory for taskwarrior data used by taskwiki. Defaults to ~/.task. *taskwiki_extra_warriors* A dictionary containing alternative taskwarrior instance definitions. A key for any alternative taskwarrior definition must be a single, uppercase letter. Value is dictionary containing respective data_location and taskrc_location overrides. Example: let g:taskwiki_extra_warriors={'H': {'data_location': '/home/tbabej/.habit/', 'taskrc_location': '/home/tbabej/.habitrc'} Specifying particular extra warrior in the viewport can be done using #[KEY] at the end of the viewport definition, in this case: ~ === Home habits | project:Home #H === *taskwiki_sort_order* The default sort order used to sort the tasks within viewports. Defaults to 'due+,pri-,project+'. Expects a comma-separated list of attributes, optionally followed by + or - to denote the increasing or decreasing order, respectively. *taskwiki_sort_orders* The sort order can also be customized per viewport. This configuration variable stores a dictionary with the alternative sort order definitions, each indexed by a uppercase letter. Example: let g:taskwiki_sort_orders={"T": "project+,due-"} Specifying a particular sort order in the viewport can be achieved using $[KEY] at the end of the viewport definition, in this case: ~ === Work tasks by decreased due, grouped by project | project:Work $T === *taskwiki_split_max_width* Use to limit the width of any vertical split created by taskwiki. *taskwiki_split_max_height* Use to limit the height of any vertical split created by taskwiki. *taskwiki_source_tw_colors* If set, taskwiki will try to use the same colors for task highlighting as those defined in taskwarrior. *taskwiki_disable* Setting any value for this variable will disable taskwiki. *taskwiki_measure_coverage* Development only. Uses python-coverage to track how much of the code is covered by tests. ============================================================================= 8. TROUBLESHOOTING *taskwiki-trouble* Make sure both your taskwiki and tasklib versions are updated. If this does not resolve your issue, feel free to submit a bug report, or seek support on #taskwarrior IRC channgel on Freenode. ============================================================================= 9. CONTRIBUTIONS *taskwiki-contribute* Code and issue tracker is hosted at: https://github.com/tbabej/taskwiki Feel free to submit pull requests and/or file issues for bugs and suggestions. ============================================================================= 10. CREDITS *taskwiki-credits* Created by: Tomas Babej. Design suggestions contributed by: David J Patrick. Inspired by: [vimwiki-tasks plugin](https://github.com/teranex/vimwiki-tasks). Taskwiki wouldn't be possible without all the work and support from the Taskwarrior community. Come hang out at #taskwarrior on Freenode. ============================================================================= 11. LICENSE *taskwiki-license* Copyright 2014-2015 Tomas Babej http://github.com/tbabej/taskwiki This software is released under MIT licence. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. vim:tw=78:ts=8:ft=help