kdheepak/taskwarrior-tui
1
0
Fork 0
mirror of https://github.com/kdheepak/taskwarrior-tui.git synced 2025-08-24 05:26:42 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Update docs

Browse source
This commit is contained in:
Dheepak Krishnamurthy 2021-03-24 10:51:04 -06:00
parent ea458db64c
commit 420a29c5df
10 changed files with 293 additions and 265 deletions
Download patch file Download diff file Expand all files Collapse all files

33
.github/workflows/docs.yml vendored Normal file
View file

@ -0,0 +1,33 @@
name: Deploy docs
on:
push:
branches:
- master
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
with:
submodules: "recursive"
fetch-depth: 0
- name: Setup Python
uses: actions/setup-python@v1
with:
python-version: '3.8'
architecture: 'x64'
- name: Install dependencies
run: |
python3 -m pip install --upgrade pip # install pip
python3 -m pip install mkdocs # install mkdocs
python3 -m pip install mkdocs-material # install material theme
python3 -m pip install pygments pymdown-extensions mkdocs-material-extensions termcolor mkdocs-material mkdocs-macros-plugin
- name: Build site
run: mkdocs build
- name: Github Pages Deploy
uses: peaceiris/actions-gh-pages@v3
with:
personal_token: ${{ secrets.GITHUB_TOKEN }}
publish_branch: gh-pages
publish_dir: ./site
force_orphan: true

266
README.md
View file

@ -11,268 +11,4 @@ A Terminal User Interface for [Taskwarrior](https://taskwarrior.org/).
![](https://user-images.githubusercontent.com/1813121/97066323-acd41500-1571-11eb-90c2-d74faa21e1ad.png) ![](https://user-images.githubusercontent.com/1813121/97066323-acd41500-1571-11eb-90c2-d74faa21e1ad.png)
## Installation See <https://kdheepak.com/taskwarrior-tui> for documentation.
Unless otherwise specified, you will need to install `taskwarrior` first. See <https://taskwarrior.org/download/> for more information.
**Manual** ( _Recommended_ ) [![](https://img.shields.io/github/v/tag/kdheepak/taskwarrior-tui)](https://github.com/kdheepak/taskwarrior-tui/releases/latest) [![](https://img.shields.io/github/downloads/kdheepak/taskwarrior-tui/total)](https://github.com/kdheepak/taskwarrior-tui/releases/latest)
1. Download the tar.gz file for your OS from [the latest release](https://github.com/kdheepak/taskwarrior-tui/releases/latest).
2. Unzip the tar.gz file
3. Run with `./taskwarrior-tui`.
**Install from source** [![](https://img.shields.io/badge/branch-master-red)](https://github.com/kdheepak/taskwarrior-tui)
```bash
git clone https://github.com/kdheepak/taskwarrior-tui.git
cd taskwarrior-tui
cargo build --release
```
**Using [`brew`](https://brew.sh/)** [![](https://img.shields.io/homebrew/v/taskwarrior-tui)](https://formulae.brew.sh/formula/taskwarrior-tui) [![](https://img.shields.io/homebrew/installs/dy/taskwarrior-tui)](https://formulae.brew.sh/formula/taskwarrior-tui)
This installs `task` from `homebrew` as well.
```bash
brew install taskwarrior-tui
```
**Installation for Arch Linux** [![](https://img.shields.io/archlinux/v/community/x86_64/taskwarrior-tui)](https://archlinux.org/packages/community/x86_64/taskwarrior-tui/) [![](https://img.shields.io/aur/version/taskwarrior-tui-git)](https://aur.archlinux.org/packages/taskwarrior-tui-git/)
Use [pacman](https://wiki.archlinux.org/index.php/Pacman) to install it from the [community repository](https://archlinux.org/packages/community/x86_64/taskwarrior-tui/):
```bash
pacman -S taskwarrior-tui
```
Or use your favorite [AUR helper](https://wiki.archlinux.org/index.php/AUR_helpers) to download the [git](https://aur.archlinux.org/packages/taskwarrior-tui-git/) package maintained by [**@loki7990**](https://github.com/loki7990). For example:
```bash
yay -S taskwarrior-tui-git # build from source master
```
**Using [`snap`](https://snapcraft.io/)** [![](https://snapcraft.io/taskwarrior-tui/badge.svg)](https://snapcraft.io/taskwarrior-tui)
```bash
snap install taskwarrior-tui
```
<!--
**Using [`cargo`](https://crates.io/)** [![](https://img.shields.io/crates/v/taskwarrior-tui)](https://libraries.io/cargo/taskwarrior-tui)
```bash
cargo install taskwarrior-tui
```
-->
**Using [`zdharma/zinit`](https://github.com/zdharma/zinit)** [![](https://img.shields.io/github/v/tag/kdheepak/taskwarrior-tui)](https://github.com/kdheepak/taskwarrior-tui/releases/latest)
Add the following to your `~/.zshrc`:
```zsh
zinit ice wait:2 lucid extract"" from"gh-r" as"command" mv"taskwarrior-tui* -> tt"
zinit load kdheepak/taskwarrior-tui
```
## Usage
_Tip_: Alias `tt` to `taskwarrior-tui`.
Add the following to your dotfiles (e.g. `~/.bashrc`, `~/.zshrc`):
```
alias tt="taskwarrior-tui"
```
### See it in action:
<details>
<summary> Click to expand! </summary>
![](https://user-images.githubusercontent.com/1813121/89620056-4ed64200-d84c-11ea-9153-9e08bc26d3b4.gif)
</details>
### Easy to use interface:
<details>
<summary> Click to expand! </summary>
See [KEYBINDINGS.md](./KEYBINDINGS.md) for full list.
![](https://user-images.githubusercontent.com/1813121/88654924-40896880-d08b-11ea-8709-b29cc970da4c.gif)
</details>
### Context switcher:
<details>
<summary> Click to expand! </summary>
![](https://user-images.githubusercontent.com/1813121/97959948-a746ae00-1d6d-11eb-9ffe-8f76f2a2b32d.gif)
</details>
### `readline`-like functionality:
<details>
<summary> Click to expand! </summary>
- `<Ctrl-a>` : Go to beginning of the line
- `<Ctrl-e>` : Go to end of the line
- `<Ctrl-u>` : Delete from beginning of the line
- `<Ctrl-k>` : Delete to end of the line
- `<Ctrl-w>` : Delete previous word
![](https://user-images.githubusercontent.com/1813121/95651612-ce7cc900-0aa8-11eb-8686-42442ed9ee43.gif)
</details>
### Calendar view
<details>
<summary> Click to expand! </summary>
`taskwarrior-tui` supports a Calendar view, which you can get to by hitting the `]` key:
![](https://user-images.githubusercontent.com/1813121/96957124-0c211f00-14b7-11eb-9d29-b3b68420af44.gif)
This highlights the days for your due tasks in a calendar view.
You can configure the number of months in a row by changing the `uda.taskwarrior-tui.calendar.months-per-row` attribute in your `taskrc` file.
See the next section for more information.
You can switch back to the task view by hitting the `[` key.
</details>
### Configure `taskwarrior-tui` using `~/.taskrc`:
<details>
<summary> Click to expand! </summary>
`taskwarrior-tui` reads values from your `taskwarrior`'s `taskrc` file (default: `~/.taskrc`).
![](https://user-images.githubusercontent.com/1813121/96684390-bf173e80-1338-11eb-971c-ae64233d142e.png)
For example, `color.active` is used to style the active task.
If you would like to try it, open your `taskrc` file and change `color.active=white on blue`.
So `color.active` will take precedence over `color.overdue`. You can see what `color.active` is by running `task show color.active` in your favorite shell prompt.
The following color attributes are supported:
```plaintext
color.deleted
color.completed
color.active
color.overdue
color.scheduled
color.due.today
color.due
color.blocked
color.blocking
color.recurring
color.tagged
```
Other `taskwarrior-tui` configuration options are possible using the user defined attribute feature of `taskwarrior`.
All `taskwarrior-tui` specific configuration options will begin with `uda.taskwarrior-tui.`.
The following is a full list of all the options available and their default values implemented by `taskwarrior-tui` if not defined in your `taskrc` file.
```plaintext
uda.taskwarrior-tui.selection.indicator=•
uda.taskwarrior-tui.selection.bold=yes
uda.taskwarrior-tui.selection.italic=no
uda.taskwarrior-tui.selection.dim=no
uda.taskwarrior-tui.selection.blink=no
uda.taskwarrior-tui.calendar.months-per-row=4
uda.taskwarrior-tui.task-report.show-info=true
uda.taskwarrior-tui.task-report.looping=true
uda.taskwarrior-tui.style.context.active=black on rgb444
uda.taskwarrior-tui.style.calendar.title=black on rgb444
```
And here are the default key bindings:
```plaintext
uda.taskwarrior-tui.keyconfig.quit=q
uda.taskwarrior-tui.keyconfig.refresh=r
uda.taskwarrior-tui.keyconfig.go-to-bottom=G
uda.taskwarrior-tui.keyconfig.go-to-top=g
uda.taskwarrior-tui.keyconfig.down=j
uda.taskwarrior-tui.keyconfig.up=k
uda.taskwarrior-tui.keyconfig.page-down=J
uda.taskwarrior-tui.keyconfig.page-up=K
uda.taskwarrior-tui.keyconfig.delete=x
uda.taskwarrior-tui.keyconfig.done=d
uda.taskwarrior-tui.keyconfig.start-stop=s
uda.taskwarrior-tui.keyconfig.undo=u
uda.taskwarrior-tui.keyconfig.edit=e
uda.taskwarrior-tui.keyconfig.modify=m
uda.taskwarrior-tui.keyconfig.shell=!
uda.taskwarrior-tui.keyconfig.log=l
uda.taskwarrior-tui.keyconfig.add=a
uda.taskwarrior-tui.keyconfig.annotate=A
uda.taskwarrior-tui.keyconfig.filter=/
uda.taskwarrior-tui.keyconfig.zoom=z
uda.taskwarrior-tui.keyconfig.context-menu=c
uda.taskwarrior-tui.keyconfig.next-tab=]
uda.taskwarrior-tui.keyconfig.previous-tab=[
```
</details>
#### Configure user defined shortcuts:
<details>
<summary> Click to expand! </summary>
You can configure shortcuts to execute custom commands from your `taskwarrior`'s `taskrc` file (default: `~/.taskrc`).
You can do this by mapping a shortcut to an executable file:
```plaintext
uda.taskwarrior-tui.shortcuts.1=~/.config/taskwarrior-tui/shortcut-scripts/add-personal-tag.sh
uda.taskwarrior-tui.shortcuts.2=~/.config/taskwarrior-tui/shortcut-scripts/sync.sh
...
```
The file can have any name in any location, but must be executable.
By default, keys `1`-`9` are available to run shortcuts.
When you hit the shortcut, the script will be executed with the `selected_task_uuid` as an argument:
```bash
~/.config/taskwarrior-tui/shortcut-scripts/add-personal-tag.sh $selected_tasks_uuid
```
For example, you can add the `personal` tag to the currently selected task with the following script in `~/.config/taskwarrior-tui/shortcut-scripts/add-personal-tag.sh` :
```plaintext
task rc.bulk=0 rc.confirmation=off rc.dependency.confirmation=off rc.recurrence.confirmation=off "$@" modify +personal
```
By default, shortcuts are linked to the `1-9` number row keys.
They can be customized as any other keys through `uda.taskwarrior-tui.keyconfig.shortcut1=<key>`.
For example:
```plaintext
uda.taskwarrior-tui.keyconfig.shortcut1=n
```
You can set up shortcuts to run `task sync` or any custom bash script that you'd like.
</details>
# Related
For a similar effort, check out `vit`:
- `vit`: <https://github.com/vit-project/vit>

54
docs/configuration/advanced.md Normal file
View file

@ -0,0 +1,54 @@
# Advanced configuration
Other `taskwarrior-tui` configuration options are possible using the user defined attribute feature of `taskwarrior`.
All `taskwarrior-tui` specific configuration options will begin with `uda.taskwarrior-tui.`.
The following is a full list of all the options available and their default values implemented by `taskwarrior-tui` if not defined in your `taskrc` file.
```plaintext
uda.taskwarrior-tui.selection.indicator=•
uda.taskwarrior-tui.selection.bold=yes
uda.taskwarrior-tui.selection.italic=no
uda.taskwarrior-tui.selection.dim=no
uda.taskwarrior-tui.selection.blink=no
uda.taskwarrior-tui.calendar.months-per-row=4
uda.taskwarrior-tui.task-report.show-info=true
uda.taskwarrior-tui.task-report.looping=true
uda.taskwarrior-tui.style.context.active=black on rgb444
uda.taskwarrior-tui.style.calendar.title=black on rgb444
```
## Configure user defined shortcuts:
You can configure shortcuts to execute custom commands from your `taskwarrior`'s `taskrc` file (default: `~/.taskrc`).
You can do this by mapping a shortcut to an executable file:
```plaintext
uda.taskwarrior-tui.shortcuts.1=~/.config/taskwarrior-tui/shortcut-scripts/add-personal-tag.sh
uda.taskwarrior-tui.shortcuts.2=~/.config/taskwarrior-tui/shortcut-scripts/sync.sh
...
```
The file can have any name in any location, but must be executable.
By default, keys `1`-`9` are available to run shortcuts.
When you hit the shortcut, the script will be executed with the `selected_task_uuid` as an argument:
```bash
~/.config/taskwarrior-tui/shortcut-scripts/add-personal-tag.sh $selected_tasks_uuid
```
For example, you can add the `personal` tag to the currently selected task with the following script in `~/.config/taskwarrior-tui/shortcut-scripts/add-personal-tag.sh` :
```plaintext
task rc.bulk=0 rc.confirmation=off rc.dependency.confirmation=off rc.recurrence.confirmation=off "$@" modify +personal
```
By default, shortcuts are linked to the `1-9` number row keys.
They can be customized as any other keys through `uda.taskwarrior-tui.keyconfig.shortcut1=<key>`.
For example:
```plaintext
uda.taskwarrior-tui.keyconfig.shortcut1=n
```
You can set up shortcuts to run `task sync` or any custom bash script that you'd like.

26
docs/configuration/colors.md Normal file
View file

@ -0,0 +1,26 @@
# Color configuration
`taskwarrior-tui` reads values from your `taskwarrior`'s `taskrc` file (default: `~/.taskrc`).
![](https://user-images.githubusercontent.com/1813121/96684390-bf173e80-1338-11eb-971c-ae64233d142e.png)
For example, `color.active` is used to style the active task.
If you would like to try it, open your `taskrc` file and change `color.active=white on blue`.
So `color.active` will take precedence over `color.overdue`. You can see what `color.active` is by running `task show color.active` in your favorite shell prompt.
The following color attributes are supported:
```plaintext
color.deleted
color.completed
color.active
color.overdue
color.scheduled
color.due.today
color.due
color.blocked
color.blocking
color.recurring
color.tagged
```

32
docs/configuration/keys.md Normal file
View file

@ -0,0 +1,32 @@
# Key configuration
Configure `taskwarrior-tui` using `~/.taskrc`:
`taskwarrior-tui` reads values from your `taskwarrior`'s `taskrc` file (default: `~/.taskrc`).
```plaintext
uda.taskwarrior-tui.keyconfig.quit=q
uda.taskwarrior-tui.keyconfig.refresh=r
uda.taskwarrior-tui.keyconfig.go-to-bottom=G
uda.taskwarrior-tui.keyconfig.go-to-top=g
uda.taskwarrior-tui.keyconfig.down=j
uda.taskwarrior-tui.keyconfig.up=k
uda.taskwarrior-tui.keyconfig.page-down=J
uda.taskwarrior-tui.keyconfig.page-up=K
uda.taskwarrior-tui.keyconfig.delete=x
uda.taskwarrior-tui.keyconfig.done=d
uda.taskwarrior-tui.keyconfig.start-stop=s
uda.taskwarrior-tui.keyconfig.undo=u
uda.taskwarrior-tui.keyconfig.edit=e
uda.taskwarrior-tui.keyconfig.modify=m
uda.taskwarrior-tui.keyconfig.shell=!
uda.taskwarrior-tui.keyconfig.log=l
uda.taskwarrior-tui.keyconfig.add=a
uda.taskwarrior-tui.keyconfig.annotate=A
uda.taskwarrior-tui.keyconfig.filter=/
uda.taskwarrior-tui.keyconfig.zoom=z
uda.taskwarrior-tui.keyconfig.context-menu=c
uda.taskwarrior-tui.keyconfig.next-tab=]
uda.taskwarrior-tui.keyconfig.previous-tab=[
```

11
docs/developer/guide.md Normal file
View file

@ -0,0 +1,11 @@
# Developer guide
## Docs
See `docs/` folder in the repository.
## Internals of `taskwarrior-tui`
<!-- TODO -->
`taskwarrior-tui` is a state driven terminal user interface.

12
docs/index.md Normal file
View file

@ -0,0 +1,12 @@
# `taskwarrior-tui`
[![CI](https://github.com/kdheepak/taskwarrior-tui/workflows/CI/badge.svg)](https://github.com/kdheepak/taskwarrior-tui/actions?query=workflow%3ACI)
[![](https://img.shields.io/github/license/kdheepak/taskwarrior-tui)](./LICENSE)
[![](https://img.shields.io/github/v/release/kdheepak/taskwarrior-tui)](https://github.com/kdheepak/taskwarrior-tui/releases/latest)
[![](https://img.shields.io/static/v1?label=platform&message=linux-64%20|%20osx-64%20|%20win-32%20|%20win-64&color=lightgrey)](https://github.com/kdheepak/taskwarrior-tui/releases/latest)
[![](https://img.shields.io/github/languages/top/kdheepak/taskwarrior-tui)](https://github.com/kdheepak/taskwarrior-tui)
[![](https://img.shields.io/coveralls/github/kdheepak/taskwarrior-tui)](https://coveralls.io/github/kdheepak/taskwarrior-tui)
A Terminal User Interface for [Taskwarrior](https://taskwarrior.org/).
![](https://user-images.githubusercontent.com/1813121/97066323-acd41500-1571-11eb-90c2-d74faa21e1ad.png)

56
docs/installation.md Normal file
View file

@ -0,0 +1,56 @@
# Installation
Unless otherwise specified, you will need to install `taskwarrior` first. See <https://taskwarrior.org/download/> for more information.
**Manual** ( _Recommended_ ) [![](https://img.shields.io/github/v/tag/kdheepak/taskwarrior-tui)](https://github.com/kdheepak/taskwarrior-tui/releases/latest) [![](https://img.shields.io/github/downloads/kdheepak/taskwarrior-tui/total)](https://github.com/kdheepak/taskwarrior-tui/releases/latest)
1. Download the tar.gz file for your OS from [the latest release](https://github.com/kdheepak/taskwarrior-tui/releases/latest).
2. Unzip the tar.gz file
3. Run with `./taskwarrior-tui`.
**Install from source** [![](https://img.shields.io/badge/branch-master-red)](https://github.com/kdheepak/taskwarrior-tui)
```bash
git clone https://github.com/kdheepak/taskwarrior-tui.git
cd taskwarrior-tui
cargo build --release
```
**Using [`brew`](https://brew.sh/)** [![](https://img.shields.io/homebrew/v/taskwarrior-tui)](https://formulae.brew.sh/formula/taskwarrior-tui) [![](https://img.shields.io/homebrew/installs/dy/taskwarrior-tui)](https://formulae.brew.sh/formula/taskwarrior-tui)
This installs `task` from `homebrew` as well.
```bash
brew install taskwarrior-tui
```
**Installation for Arch Linux** [![](https://img.shields.io/archlinux/v/community/x86_64/taskwarrior-tui)](https://archlinux.org/packages/community/x86_64/taskwarrior-tui/) [![](https://img.shields.io/aur/version/taskwarrior-tui-git)](https://aur.archlinux.org/packages/taskwarrior-tui-git/)
Use [pacman](https://wiki.archlinux.org/index.php/Pacman) to install it from the [community repository](https://archlinux.org/packages/community/x86_64/taskwarrior-tui/):
```bash
pacman -S taskwarrior-tui
```
Or use your favorite [AUR helper](https://wiki.archlinux.org/index.php/AUR_helpers) to download the [git](https://aur.archlinux.org/packages/taskwarrior-tui-git/) package maintained by [**@loki7990**](https://github.com/loki7990). For example:
```bash
yay -S taskwarrior-tui-git # build from source master
```
**Using [`snap`](https://snapcraft.io/)** [![](https://snapcraft.io/taskwarrior-tui/badge.svg)](https://snapcraft.io/taskwarrior-tui)
```bash
snap install taskwarrior-tui
```
**Using [`zdharma/zinit`](https://github.com/zdharma/zinit)** [![](https://img.shields.io/github/v/tag/kdheepak/taskwarrior-tui)](https://github.com/kdheepak/taskwarrior-tui/releases/latest)
Add the following to your `~/.zshrc`:
```zsh
zinit ice wait:2 lucid extract"" from"gh-r" as"command" mv"taskwarrior-tui* -> tt"
zinit load kdheepak/taskwarrior-tui
```

16
docs/quick_start.md Normal file
View file

@ -0,0 +1,16 @@
# Quick Start
1. Install `taskwarrior` and `taskwarrior-tui`.
2. Run the following in a shell.
`$ taskwarrior-tui`
3. Use `vim` like keys to navigate your task list. Press `?` for more information.
_Tip_: Alias `tt` to `taskwarrior-tui`.
Add the following to your dotfiles (e.g. `~/.bashrc`, `~/.zshrc`):
```
alias tt="taskwarrior-tui"
```
![](https://user-images.githubusercontent.com/1813121/89620056-4ed64200-d84c-11ea-9153-9e08bc26d3b4.gif)

52
mkdocs.yml Normal file
View file

@ -0,0 +1,52 @@
site_name: taskwarrior-tui - A terminal user interface for taskwarrior
site_url: https://kdheepak.com/taskwarrior-tui
site_author: Dheepak Krishnamurthy
# Source code repository
repo_name: kdheepak/taskwarrior-tui
repo_url: https://github.com/kdheepak/taskwarrior-tui
# Copyright
copyright: Copyright &copy; 2021 Dheepak Krishnamurthy
markdown_extensions:
- admonition
- attr_list
- footnotes
- pymdownx.highlight
- pymdownx.superfences
# Plugins
plugins:
- search
# Theme
theme:
name: material
favicon: assets/favicon.png
features:
- navigation.tabs
include_search_page: false
language: en
palette:
primary: deep blue
search_index_only: true
# Customization
extra:
social:
- icon: fontawesome/brands/github
link: https://github.com/kdheepak
# Page tree
nav:
- Home: index.md
- Getting Started:
- Installation: installation.md
- Quick Start: quick_start.md
- Configuration:
- Key configuration: configuration/keys.md
- Color configuration: configuration/colors.md
- Advanced: configuration/advanced.md
# - Developer Guide:
# - Guide: developer/guide.md