# 番茄武士

[English Document](./readme.md)

## 简介

蕃茄武士是一个集成了 [任务管理工具 taskwarrior](https://taskwarrior.org/docs/) 和 [时间统计工具 timewarrior](https://taskwarrior.org/docs/timewarrior/) 的工具，并在此基础上增加了如下主要功能：

* 任务拆分；
* 记录任务消耗的时间；
* 支持番茄工作法；
* 生成统计报告。

## 安装

### 安装到本地

1. 运行 `python2 bootstrap.py`；
2. 安装 [taskwarrior](https://taskwarrior.org/download/)；
3. 安装 [timewarrior](https://taskwarrior.org/docs/timewarrior/download.html)。

### 安装到网盘

比如想用 OneDrive 同步数据，且 OneDrive 同步盘的路径为 `~/OneDrive/`，则执行下面语句：

```bash
python2 bootstrap.py ~/OneDrive/task
```

### 关于网盘

对于国内用户，我非常推荐使用[坚果云](https://www.jianguoyun.com)。对比 OneDrive 等大厂产品的优势如下：

* 全平台：我因此几个不同系统的电脑有相同的开发环境和数据。
* 国内网络：速度快，不用翻墙。
* 数据有多个版本供回滚：`taskwarrior` 有时候数据会出问题，我因此还写了 `scripts/recover.py`，有了坚果云就用不到了。
* 配置灵活：不需要像 `bootstrap.py` 里那样把数据放到同步文件夹里，而是配置哪些文件（夹）是要同步的。

### 用法

因为番茄武士是在 [taskwarrior](https://taskwarrior.org/docs/) 和 [timewarrior](https://taskwarrior.org/docs/timewarrior/) 里通过 hooks 添加了一些方便的功能，所以使用番茄武士的前提是你已经掌握了这两个工具。

### 1. 拆分任务：`task <id> split <mods>`

为 `<id>` 所表示的任务添加一个子任务，子任务会继承其 project 属性并将其 block（所以被拆分的任务必须有 project 属性）。  
比如说：

```bash
>>> task add project:test "I'm a parent task"
Created task 1.
>>> task 1 split +next "I'm a child task"
Created task 2.
>>> task 1 split project:sub "I'm another child task"
Created task 3.
>>> task _get 1.depends
b4eb87e6-54f5-422e-939a-f03c673de23e,8dd2e258-525f-4ff0-a7dc-b80fbca8387c
>>> task _get {2,3}.project
test test.sub
```

### 2. 记录任务时间：`task <id> timew ...`

这个命令会被展开成 `tiemw ... <task tags, projects, uuid>`，所以用来记录某一任务消耗的时间是很方便的，比如 `task <id> timew start`。

### 3. 番茄工作法

记录时间时，如果有为 `pomodoro` 的 tag，就会进入番茄模式（具体请搜索“番茄工作法”，就不赘述了）。

所以在使用番茄工作法做某一项任务时可以使用 `task <id> timew start pomodoro`。

### 4. 统计报告

* `timew last`. 当前或最近时间统计的任务的详情；
* 完成或删除一个任务时显示其消耗的时间；
* `timew pomo_stat`. 使用番茄工作法产生的统计数据，主要用来给下一个命令用；
* `timew pomo_msg`. 当前番茄工作法所处状态，用来与 `tmux` 或 `powerline` 集成。

与 [tmux](https://github.com/tmux/tmux) 集成可在 `~/.tmux.conf` 中添加下面的配置：

```bash
set-option -g status-left "#(timew pomo_msg.py :day)"
```

与 [powerline](https://github.com/powerline/powerline) 集成可以添加这个 `segment`：

```json
{
    "function": "powerline.lib.shell.run_cmd",
    "priority": 80,
    "args": {
        "cmd": ["timew", "pomo_msg.py", ":day"]
    }
}
```

可参考分支 [ks](https://github.com/cf020031308/pomodoro-warriors/tree/ks)，里面有我个人使用的报告。

### 5. 其它改进

* `task <filter> tiny`. 适合小窗口（如 tmux 的 panes）的任务列表；
* 任务可设置 estimate 属性，用来记录自己预估任务完成所需的时间；
* `timew toggle [<tag> ...]`. 从目前时间日志的 tags 中增加或去除指定 tags，以此开始一条新的时间日志。

## 工作流举例

结合 GTD 理论和番茄工作法

### 收集

* `task add <desc>`. 只简单写任务描述就可以。

### 处理

1. 因为收集时没设置 project，可以用 `task -PROJECT` 筛选出来，一条条处理；
2. 设定一个可量化的目标，通过 `task <id> annotate <anno>` 批注（如果比较短也可以直接改描述），并通过 `task <id> modify <mods>` 设置好 project, priority, scheduled, due 等属性；
3. 用 `task <id> split <mods>` 将任务拆分成更小的子任务，越流程化越好；
4. 估计子任务所需时间（最好不要超过 8 个番茄时间），用 `task <id> modify estimate:<duration>` 记下。

### 安排

* 每天早上安排下当天要做的事情，结合 `task <id> start` 命令与 due 属性使其能在任务列表中被轻易区分出来。

### 执行

* 普通执行
    + 使用 `task <id> timew start` 开始统计一项任务的时间；
    + 使用 `timew stop` 停止统计时间；
    + 使用 `task <id> done` 结束一项任务并停止统计时间。
* 番茄工作法
    + 使用 `task <id> timew start pomodoro` 开始一个番茄；
    + 使用 `timew toggle pomodoro` 或 `timew stop pomodoro` 结束一个番茄 （但继续统计任务时间）；
    + 中途如果有重要任务插入，可以用 `task <id> modify +next` 给该任务添加一个较高的紧急度，完成当前番茄后处理；
    + 与 tmux 或 powerline 集成后可在其 status-line 看到当前番茄状态。

### 回顾

* 每天： `timew day`
* 每周： `timew week`