void-rs/void

terminal-based personal organizer

void

Tutorial

Example Workflow

WARNING: this is alpha, and the default keybinds are still weird because I use colemak on top of tmux. You may want to change them, by setting the KEYFILE env var to the path to a key remap file. In the future, I may add optional modal editing to bring it more in-line with vim. Right now I'm not sure it's worth the extra keystrokes.

Feedback encouraged! If you have a hard time with something, let me know about it, and I'll work to smooth out the experience!

problems

This is an attempt to address several common situations:

1. frequently fall out of creative flow
2. day-to-day work lacks coherence
3. failure to integrate learnings into a cohesive perspective
4. execution of tasks lacks focus and motivation
5. unclear how my efforts are impacting goals

perspectives

• things we measure tend to improve
• we should regularly reevaluate priorities
• we should minimize decisions to prevent fatigue
• individual sensemaking is well served by reflection, journaling, outlining, mind-mapping, etc...
• don't impose specific workflows, but support many possibilities

implementation

• everything is a tree
• you can collapse subtrees
• you can drill-down the screen focus arbitrarily
• trees of tasks can be marked with #task, all children of marked nodes are implicitly subtasks
• tasks can be prioritized with #prio=<n>, all children implicitly inherit the lowest ancestor's priority
• a task can be chosen automatically, with priorities weighting a random selection. you should delete it or do it, don't get into the habit of drawing again until you see something you like. you chose the priorities, and you should keep them up-to-date.
• you can create your own sparklines by using #plot=done or #plot=new, in combination with #n=10 for sparkline size, #since=7d / #until=1d for specifying time window.
• overall completed subtasks are plotted on a sparkline at the top of the screen for the past week.
• you can draw arrows between nodes for mind-mapping functionality
• can shell out and execute the content of a node with C-k. if the node starts with txt: this will be opened in vim or an editor specified in the EDITOR env var.

what I do (don't do what I do, discover what works for you)

• create a #task subtree
• create different story subtrees for life goals, projects, etc... and tag them, #climbing #reading #client_143 etc...
• set up graphs for feedback on different goals/projects. #tagged=climbing #since=30d #plot=done
• start the day by fiddling with #prio=<n> tags on the stories
• hit the auto-task keybind (by default C-v) to pick an incomplete task child from one of the stories
• work on it for 25 minutes or until completion, optionally leaving a few minutes for a retrospective/reprioritization at the end
• distract myself as much as possible, let brain GC whatever I've been thinking about a little bit
• if I've completed a task, mark it done (by default, C-a)
• completed work is surfaced in the sparkline graphs I've set up for its tags
• every week or so, tweak the system

install

cargo install voidmap

if you don't have cargo, an easy way to get and manage it is via rustup. Ensure that ~/.cargo/bin is in your $PATH afterward, so that you can use the rustup and cargo commands.

If you get errors along the lines of error: the `?' operator is not stable then you need to update your rust compiler. If you installed rust with rustup, this can be accomplished with rustup update. Requires a recent stable rust compiler, 1.14.0 or higher is recommended. This can be checked with rustc --version. If you have installed rust with rustup, but you have an old version, there may be an older version previously installed on your system. Verify that which cargo outputs a path that belongs to your .cargo/bin directory.

invocation

void

this attempts to use $HOME/.void.db as a storage file. if you'd like to specify a different storage file:

void [/path/to/savefile]

keys

feature	control	feature	control
new node	C-n	new node (child of selected)	Tab
new node (freeform)	click blank space	new node (sibling of selected)	Enter
delete selected node and its children	Delete	move subtree	drag parent to new location
undo delete	C-z	auto arrange nodes in view	C-p
mark selected node complete	C-a	drill-down into selected node	C-w
pop up selection	C-q	hide children of selected	C-t
open text editor for txt:... node	C-k	prefix-jump with no selection	type a letter
prefix-jump with other selected	C-f	hide completed children of node	C-h
select arrow start/destination	C-r	erase arrow	select start, C-r, then destination, C-r
show debug log	C-l	reparent node	drag node to new parent
scroll up	PgUp	scroll down	PgDn
select up	Up	select down	Down
select subtree to left	Left	select subtree to right	Right
de-select node	Esc	save	C-x
exit	Esc with nothing selected	exit	C-c
jump to weighted next task	C-v	cut / paste node	C-y
move selected up in child list	C-g	move selected down in child list	C-d
search for node at or below current view	C-u	Select parent	A-S-p (alt shift)
Select next sibling	A-n	select previous sibling	A-p

can be customized by setting the KEYFILE env var to the path of a key configuration file

known bugs

doesn't properly handle very long text. if you want to embed an essay, create a node that begins with txt: and hit C-k to open its contents in an external text editor, specifiable by setting the EDITOR env var.

optional configuration

setting the LOGFILE environment variable will allow you to log debugging info to a file.

setting the EDITOR environment variable will allow you to specify which text editor is opened when hitting C-k on a node whose name begins with txt: . defaults to vim.

setting the KEYFILE environment variable to the path of a keyfile allows you to customize the controls

setting the LOCATION_QUERY environment variable to anything will enable an http request that is sent out at startup to get approximate latitude and longitude coordinates associated with your internet-facing IP. this is added to any nodes created during a session, and eventually will allow you to trace the rough path you've taken over time. aimed mostly at users who travel a lot, may eventually have a more interesting implementation.

notes

This came about in the midst of an (ongoing) obsessive inquiry into a cluster of topics roughly related to "effectiveness" while stumbling through various mountain ranges and cities in central europe and the american northeast.

• conversations with @matthiasn and being introduced to his wonderful iWasWhere system
• writings of eliezer s. yudkowsky, how to solve it, society of mind
• various subtopics of operations research
• occult assumption confrontation: undoing yourself with energized meditation, prometheus rising
• military C2 theory, recognition/metacognition, OODA, etc... A Review of Time Critical Decision Making Models and Human Cognitive Processes
• personal productivity literature: pomodoro, GTD, eat that frog, flow

The primary thing when you take a sword in your hands is your intention to cut the enemy, whatever the means. Whenever you parry, hit, spring, strike or touch the enemy’s cutting sword, you must cut the enemy in the same movement. It is essential to attain this. If you think only of hitting, springing, striking or touching the enemy, you will not be able actually to cut him. More than anything, you must be thinking of carrying your movement through to cutting him... When you appreciate the power of nature, knowing the rhythm of any situation, you will be able to hit the enemy naturally and strike naturally. All this is the Way of the Void. - Miyamoto Musashi

void's Issues

Mention Windows compatibility in README

Build fails on Windows because of Termion.

Question: Would switching `txt:` and shell be a better behavior?

I noticed that if you hit c-k on a node with no special handling, it just executes it as a shell command. If you want to open it in an editor, you have to type txt: first. Wouldn't a better default be to open text in a text editor and for shelling out to require explicit handling with something like a shell: prefix?

[Feature Request] Support for more key combinations

Currently, there exists no way to describe the following key combinations:

• Ctrl or Alt plus any non-character key (e.g. Ctrl+Right, Alt+Fn1, or Ctrl+Backspace)
• Shift as a modifier to any character which doesn't have a shifted variant on the users keyboard (e.g. Shift+Tab or Shift+Right)
• Combinations of Ctrl and Alt (and implicitly Shift) (e.g. Ctrl+Alt+f)

This poses an issue as these are common shortcuts used in many applications, and requests for features bound to these combinations by default have come up in numerous issues, thereby making this issue a prerequisite for

• #45, which requests Shift+Tab as a binding to move a node up a level
• #61, which requests Shift+Direction as a shortcut to pan the view (opened by me)
• Likely #15, which doesn't specifically request any shortcuts, but due to the innate directionality of the request, would likely need to be bound to arrow keys + a modifier, or use some sort of modal control such as in #58

umlaut handling

after typing an umlaut the next few keystrokes are not accepted.
to reproduce:
setxkbmap de; void; setxbmap en
in voidmap press type the button right of the L into a label, then try to type something else

Allow configuring default browser

When an entry is a url starting with http, pressing C-k will try to spawn a "firefox" process, that will probably fail if you don't have your browser configured like that.

Adding some kind of configuration or env var to change the browser used would be helpful. For example, on mac, using open instead will open the URL with whatever default application you use to handle URLs. On linux, defaulting to xdg-open would probably be a good default too.

imag collaboration?

Hi,

I am the author of the imag project.

Would you like to collaborate on implementing a terminal based organizer? I have a big infrastructure for implementing PIM-related domains for CLI/TUI usage and I would love to collaborate to build a terminal based organizer tool based on the imag infrastructure...

Let me hear what you think!

Keep track of selection focus after close

From the PR (#18) initially implementing this:

I often use deep trees, and currently every time you reopen void, the view gets reset to the home level. This makes it so the view stack and the current focus view are restored between runs. Maybe it's not the best way to things (just exposing fields with pub), but it might be helpful anyway.
The changes should work on existing documents, as all the new proto fields are optional, but I haven't done exhaustive testing of this.

An alternative implementation was added with PR #27. Unfortunately adding this feature isn't quite that simple. It requires an update to the protobuf generated code which leads to horrible data loss if not done correctly.

Therefore this feature is blocked on a few changes around configurable data formats

• Existing data files (legacy) need to keep working without data loss
• New storage format needs to include current selection
• There needs to be a convenient way to migrate from the legacy format to the new one

I'll also add a milestone to this once we can estimate how much work is actually required for this

xdg

use the xdg standard for saving status.

Implementing better CI

There have been a lot of new features implemented recently by PR's (mostly by @alok 😉). I'd be happy to do a release soon but I really want to improve the CI and testing of the project first.

Pinning an old version of void to write a datafile and then opening it again in the current master branch would catch most data loss issues.
If you've got ideas for more testing opportunities, please post them as comments.

I'll try to find the time to take a stab at it this week

Rearrangement without mouse

Unless I've missed something from the docs, it doesn't currently seem possible to rearrange some subtree without using the mouse?

Can this be added?

Please add sig(term) signal handler

As a continuation of #9, i would like to see a SIGTERM handler so that a regular shutdown/reboot of my laptop will actually save my work

---

n.b.: I've tried to add this myself, but… as I'm only very newly acquainted with Rust, i felt very much out of my waters, especially, since this app doesn't already have any signal handlers, and rust itself has no… standard signal handlers see rust-lang/rfcs#1368 vs https://crates.io/search?q=signal

Changing the completed node character

Hello! First of all, thanks for this project!

The skull character used to mark nodes as complete is not very readable with the font I'm using, and I was wondering if I could change it to something else. Can this be added as a configuration?

Request: jump selection to parent node

This is handy for navigating the tree. If no node is selected or the node is at root level and has no parent, it should be a no-op.

Void doesn't save .db if you crash?

I had void up in a terminal, and ran my laptop out of batteries. many days of void items disappeared into the, well, into the void. Could void save intermittently?

Creating new file

This project looks really useful. However after creating a new file with either cargo run or ./void I can't seem to do anything. Hitting space shows a choice option but won't let me type anything. No other key seems to do anything. What am I doing wrong?

Auto Save

Auto saving would catch this up to modern editors.

Document graphs

How do I create a graph like the one described in the README? #tagged=climbing #since=30d #plot=done. Maybe I am misunderstanding what it means.

keybinds not working

Howdy!

Neat project. Ive been giving it a go and have run into a snag with the custom keybinds.

Ive set the env var and pointed it to the default.keys found in this repo. It errors out with the below until I remove he lines for undo_delete and help:

thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: Error { repr: Custom(Custom { kind: Other, error: StringError("invalid config at line 30: undo_delete:C-z") }) }', src/libcore/result.rs:860
note: Run with `RUST_BACKTRACE=1` for a backtrace.

Removing those gets it to launch, but the app still responds to the default bindings and does not appear to notice any changes I make.

Have you run into this before?

Suggestion: Key Combo to move current item up a scope

It would be nice to be able to hit a key combo to move the current item up one scope level. By default I would suggest "Shift + Tab" (to de-indent). This would move the currently selected item to be at the same level as its' parent.

[Feature Request] Key bindings for panning / moving view

Heya!

New user here, trying out void to put some ideas in my head down about a ttrpg campaign I'm trying to plan out.

I have a big pile of ideas that I'm interrelating with arrows (story elements leading to other story elements, connections between physical places, relationships between characters).

I'm using manual layout because I need to group nodes by category (plot vs place vs person) as well as chronology or physical location. (Also because in auto layout the arrows are impossible to follow). Anyway, I quickly run into issues with space, the most signifigant being that it's a little hard to navigate.

After rebinding scrolling commands (my laptop doesn't have page keys), I found that they helped, but because it jumps a whole page at a time, it can be hard to get the view, and the nodes, where I want them to be. As far as I'm aware, there's also now way to scroll to the side, which becomes a problem when my window shrinks.

I'd like to suggest keybindings for scrolling, maybe three characters at a time, in any cardinal direction. I personally feel that this might make it easier to navigate large, manually arranged maps, and just generally increase comfort and control.

I'd suggest Shift+, but IIRC there's no way to describe that in the config atm, and honestly I'd be down for whatever.

Thanks for hearing me out!

Test/add Windows support

Hi,
since this is written in a modern language, I had the expectation it would work on Windows as well.

clear screen on exit

or restore previous screen

Crash + lost work on drag starting from window, ending at screen y-coordinate 0

Platform: Lenovo X220, Arch Linux, Awesome window manager, rxvt terminal.

Reproduction:

1. Start holding left mouse button anywhere in the terminal hosting a void instance.
2. Touch top of the entire screen, not the top of the terminal window.
3. -> Application exits with exit code 101, which is rustc for "panic", without a trace on debug logs (as far as I reckon).

Other notable

• Left edge (x=0) of screen does not produce this issue.

Seems like a pretty simple out-of-bounds or a division by zero-like issue. I will investigate and try to implement a fix when I get back from work in 6 hours.

Keep the completed skull from hiding the + sign

When you're working with a large tree and you begin marking trees containing branches as complete, you can no longer see the + sign that indicates subtrees as the skull seems to clobber/hide the symbol, consider instead, making it only prepend the skull. In addition, consider making it so that the plus sign and skull symbols do not cover the first part of the node text. Instead of covering the text, have it prepend the node text.

backing up .void.db file

Does anyone have a solution to backup the .void.db file. A private/public gist or github repo would be ideal.

A general and agnostic implementation would be to enable pre and post hooks for void. (pre-open?? post-close??). This would allow the implementation details for backups and other operations to be though out later.

---

git back up implementation assuming pre/post hooks

personally I use void only on one computer so my commands would look as follows

• pre-hook would do a git pull
• post-hook would do a git push
• failure due to network or other reasons would fail silently.. maybe a place to show error messages within void??

Feature request: Key to exit search

Sometimes I want to cancel a search, so I press escape out of habit. This doesn't do anything. C-g also fails, and then out of habit I hit c-c, which kills the whole program.

It'd be nice if esc could exit a search, as it's the universal cancel button for user apps.

clean up dependencies

as stated earlier, networking should be optional, so hyper and all its dependencies can be made an optional feature
maplit is largely useless, as you can just do vec![(a,b),(c,d),...].into_iter().collect() and get a hashmap.
rust_crypto is a) not secure to use according to the authors, and b) not even used.

use a default path if none is given on command line, instead of failing saves quietly

scheduled and due dates for tasks

For tasks, it is usually good to have scheduled and due dates. Scheduled is wen one is supposed to start work and due is when it should be done. One can have either or both. Then a feature to arrange nodes or items withing a node by either date allows a user to view their work in time order. In todo.txt they use t:yyy-mm-dd for start/scheduled and due:yyy-mm-dd for these dates.

Any way to export?

Is there any way to export one's data? Many thanks in advance!

I'm in this repo and I don't like it

problems

This is an attempt to address several cognitive defects.

frequently fall out of creative flow
day-to-day work lacks coherence
failure to integrate learnings into a cohesive perspective
execution of tasks lacks focus and motivation
unclear how my efforts are impacting goals

KEYFILE not working

I am getting an error when trying to use KEYFILE env var. The contents of the void.keys file is a copy of the default.keys from the repo.

Let me know if I can help debug.

➜  ~ export KEYFILE=/Users/toidiu/void.keys
➜  ~ void
thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: Custom { kind: Other, error: StringError("invalid config at line 0: # Comments are supported.") }', src/libcore/result.rs:997:5
note: Run with `RUST_BACKTRACE=1` environment variable to display a backtrace.
➜  ~

file content

# Comments are supported.

unselect:esc
scroll_up:pgup
scroll_down:pgdn
delete:del
select_up:up
select_down:down
select_left:left
select_right:right
erase:backspace
create_sibling:enter
create_child:tab
create_free_node:C-n
execute:C-k
drill_down:C-w
pop_up:C-q
jump:C-f
toggle_completed:C-a
toggle_hide_completed:C-h
arrow:C-r
auto_arrange:C-p
toggle_collapsed:C-t
quit:C-c
save:C-x
toggle_show_logs:C-l
enter_command:C-e
find_task:C-v
yank_paste_node:C-y
raise_selected:C-g
lower_selected:C-d
search:C-u
undo_delete:C-z
help:?

clarify network usage

for some reason this application builds a connection to ipinfo.io, querrying http://ipinfo.io/loc thereby determining the location.
can you explain why this is done, and disable this from happening by default?
is is bad to do a network connection without explicit confirmation.
also this operation blocks/delays startup.

Consider embedding neovim

You mention in the README that you may want to add modal editing someday. If you decide to do that, embedding neovim may help out. Just a thought, I'd take it with a grain of salt.