seanh/terminal_velocity

A fast note-taking app for the UNIX terminal

This is my unmaintained archived copy of Terminal Velocity.

Development has moved to Vincent Perricone's fork, you should use this instead: https://github.com/vhp/terminal_velocity

Terminal Velocity (seanh's archived copy)

Terminal Velocity is a fast note-taking app for the UNIX terminal, that focuses on letting you create or find a note as quickly and easily as possible, then uses your $EDITOR to open and edit the note. It is heavily inspired by the OS X app Notational Velocity. For screenshots and features, see the Terminal Velocity website.

To install Terminal Velocity, run:

pip install terminal_velocity

Then to launch it just run:

terminal_velocity

To use a different notes directory, run:

terminal_velocity path/to/your/notes/dir

To see all the command-line options, run:

terminal_velocity -h

To quit the app, press ctrl-c or ctrl-x.

To upgrade Terminal Velocity to the latest version, run:

pip install --upgrade terminal_velocity

To uninstall it, run:

pip uninstall terminal_velocity

To make a bug report or feature request, use GitHub Issues.

To contribute documentation, use the wiki.

To contribute code to Terminal Velocity, see CONTRIBUTING.

Hacking

To release a new version of Terminal Velocity:

1. Increment the version number in the setup.py file, add an entry te the changelog, commit both changes to git and push them to github. For example, see aae87b.
2. Upload the new release to the terminal_velocity package on pypi: run python setup.py sdist upload -r pypi.

For more information see https://packaging.python.org/.

terminal_velocity's Issues

Remember status on quit and restart

Remember typed text, selected note, etc. on quit and restore them on startup.

Make column titles clickable to change sort ordering of notes

Depends on #10

ctrl-n to create new note without entering title first

Sometimes you just want to type in some text and save it in your notebook as fast as possible, without having to come up with a title for the note first. ctrl-n should create a temporary file (hidden file in notes dir) and open it, the user types some text into their editor, savesm and quits the editor, then tv generates a title/filename for the note based on the file contents from the user and saves it.

If there's any text in the search box when the user hits ctrl-n, tv should paste that text into the first line of the temp file before opening it.

If a file with the generated filename already exists in the notes dir, then append a timestamp to the filename to make it unique. That should always create a unique filename but if it doesn't, just log an error and continue without saving the file, the temp file will be left in the notes dir.

Option for which filename extensions will be read

There's already an option for what filename extension to use when creating new notes, but when reading note files in the notes dir it currently reads all files regardless of extension. Add a configurable list of accepted extensions.

Add updated column to note list

Showing mtime of file. Also add "Title" and "Updated" column titles.

Error creating notes

Hi,

I just installed your app in my computer (running Ubuntu 14.04 LTS, 64 bits).
However, when I lunch the app and try to creat any note I get this error:

Traceback (most recent call last):
File "/usr/local/bin/terminal_velocity", line 116, in
main()
File "/usr/local/bin/terminal_velocity", line 110, in main
extension=args.extension, extensions=args.extensions)
File "/usr/local/lib/python2.7/dist-packages/terminal_velocity/urwid_ui.py", line 444, in launch
loop.run()
File "/usr/local/lib/python2.7/dist-packages/urwid/main_loop.py", line 272, in run
self.screen.run_wrapper(self._run)
File "/usr/local/lib/python2.7/dist-packages/urwid/raw_display.py", line 242, in run_wrapper
return fn()
File "/usr/local/lib/python2.7/dist-packages/urwid/main_loop.py", line 337, in _run
self.event_loop.run()
File "/usr/local/lib/python2.7/dist-packages/urwid/main_loop.py", line 708, in run
self._loop()
File "/usr/local/lib/python2.7/dist-packages/urwid/main_loop.py", line 787, in _loop
self._watch_filesfd
File "/usr/local/lib/python2.7/dist-packages/urwid/main_loop.py", line 388, in _update
self.process_input(keys)
File "/usr/local/lib/python2.7/dist-packages/urwid/main_loop.py", line 488, in process_input
k = self._topmost_widget.keypress(self.screen_size, k)
File "/usr/local/lib/python2.7/dist-packages/terminal_velocity/urwid_ui.py", line 332, in keypress
system(self.editor, [note.abspath], self.loop)
File "/usr/local/lib/python2.7/dist-packages/terminal_velocity/urwid_ui.py", line 41, in system
raise e
OSError: [Errno 2] Arquivo ou diretório não encontrado

The note is created but I cant see or do any thing with it.
Any suggestion?

Thanks in advance!

Keep selected note after leaving editor

The selected note in the note list changes after leaving the editor, but it stays the same in the search box, so the two are out of sync.

Need to implement a simple and reliable way to keep these two in sync.

Problems when there are multiple notes with the same filename, but different extension

They all appear in the note list, but you can't distinguish between them because filename extensions are not shown.

I think the only solution to this may be to always show filename extensions in the note list.

Detect changes to the notes dir when Terminal Velocity is running

If anything in the notes dir is changed by an external tool while Terminal Velocity is running, detect the change and update the UI.

It'd be nice to be able to edit the notes dir using a file browser, external editor, etc. while Terminal Velocity is running.

Also useful if Terminal Velocity open a files in an editor asynchronously, to respond to changes made by that editor.

Also useful when running multiple instances of Terminal Velocity at once.

Crash when location of note file changes during editing

If the user uses her editor to move the note file, then when she exits her editor and returns to tv, tv crashes

Keyboard commands to change sort ordering of notes

Order by title (ascending, descending) or mtime (ascending, descending)

Improve search

• Allow "inverted commas" to find an exact phrase
• Add support for excluding terms from search (e.g. with a dash before the -word)

ValueError: zero length field name in format

When I create a new note with tv or run tv on a directory containing text files, I get the following error (note that this is occurring on SDF's MetaArray):

Traceback (most recent call last):
  File "/meta/h/hobbsc/usr/bin/terminal_velocity", line 5, in <module>
    pkg_resources.run_script('terminal-velocity==0.1a6', 'terminal_velocity')
  File "/meta/h/hobbsc/usr/lib/python2.6/site-packages/pkg_resources.py", line 461, in run_script
    self.require(requires)[0].run_script(script_name, ns)
  File "/meta/h/hobbsc/usr/lib/python2.6/site-packages/pkg_resources.py", line 1194, in run_script
    execfile(script_filename, namespace, namespace)
  File "/meta/h/hobbsc/usr/lib/python2.6/site-packages/terminal_velocity-0.1a6-py2.6.egg/EGG-INFO/scripts/terminal_velocity", line 81, in <module>
    main()
  File "/meta/h/hobbsc/usr/lib/python2.6/site-packages/terminal_velocity-0.1a6-py2.6.egg/EGG-INFO/scripts/terminal_velocity", line 78, in main
    extension=args.extension)
  File "/meta/h/hobbsc/usr/lib/python2.6/site-packages/terminal_velocity-0.1a6-py2.6.egg/terminal_velocity/urwid_ui.py", line 431, in launch
    loop.run()
  File "/meta/h/hobbsc/usr/lib/python2.6/site-packages/urwid-1.1.1-py2.6-linux-x86_64.egg/urwid/main_loop.py", line 272, in run
    self.screen.run_wrapper(self._run)
  File "/meta/h/hobbsc/usr/lib/python2.6/site-packages/urwid-1.1.1-py2.6-linux-x86_64.egg/urwid/raw_display.py", line 242, in run_wrapper
    return fn()
  File "/meta/h/hobbsc/usr/lib/python2.6/site-packages/urwid-1.1.1-py2.6-linux-x86_64.egg/urwid/main_loop.py", line 337, in _run
    self.event_loop.run()
  File "/meta/h/hobbsc/usr/lib/python2.6/site-packages/urwid-1.1.1-py2.6-linux-x86_64.egg/urwid/main_loop.py", line 708, in run
    self._loop()
  File "/meta/h/hobbsc/usr/lib/python2.6/site-packages/urwid-1.1.1-py2.6-linux-x86_64.egg/urwid/main_loop.py", line 787, in _loop
    self._watch_files[fd]()
  File "/meta/h/hobbsc/usr/lib/python2.6/site-packages/urwid-1.1.1-py2.6-linux-x86_64.egg/urwid/main_loop.py", line 388, in _update
    self.process_input(keys)
  File "/meta/h/hobbsc/usr/lib/python2.6/site-packages/urwid-1.1.1-py2.6-linux-x86_64.egg/urwid/main_loop.py", line 488, in process_input
    k = self._topmost_widget.keypress(self.screen_size, k)
  File "/meta/h/hobbsc/usr/lib/python2.6/site-packages/terminal_velocity-0.1a6-py2.6.egg/terminal_velocity/urwid_ui.py", line 323, in keypress
    note = self.notebook.add_new(self.search_box.text)
  File "/meta/h/hobbsc/usr/lib/python2.6/site-packages/terminal_velocity-0.1a6-py2.6.egg/terminal_velocity/notebook.py", line 387, in add_new
    note = PlainTextNote(title, self, extension)
  File "/meta/h/hobbsc/usr/lib/python2.6/site-packages/terminal_velocity-0.1a6-py2.6.egg/terminal_velocity/notebook.py", line 175, in __init__
    logger.debug(u"Initialising new PlainTextNote: '{}'.".format(title))
ValueError: zero length field name in format

Running tv on an empty directory works just fine. The crash will occur before my editor ever spawns.

Crash when launching default editor if not running in shell

If Terminal Velocity is run directly inside a terminal emulator, as opposed to running a shell inside the terminal emulator and then running tv inside the shell, then tv crashes when trying to launch the default editor.

The default editor command is just vim, and tv crashes with a file not found error.

If you put editor = /usr/bin/vim in your .tvrc then it won't crash anymore.

Should /usr/bin/vim become the hard-coded default default? But how to know where the vim binary will be on the user's machine? Maybe we should run /usr/bin/env vim.

support different colors or maybe a -dark option or something

I'm am loving terminal-velocity so thanks so much for it. My problem is that I've had to change the default colors because I run in white on black terminal windows. I use light blue instead of dark and white instead of black in the palette map. I've not seen anything in the docs which indicates that I can set these colors in the configs.

And sorry but I'm not a python hacker so I can't submit a PR.

Don't create a note with no title

Including the situation when a note's title is just os.sep(), or just whitespace, etc. and gets stripped to nothing. Implement in notebook.py and raise an exception, catch in urwid_ui.py.

Support other types of file (e.g. image files)

No reason why my notes dir can't contain non-text files as well, e.g. image files (could be scanned images of paper notes). At least the filename can still be used for searching, and possibly also file metadata as well. Then open the file in an image viewer instead of a text editor.

This requires a dictionary mapping filename extensions or file types to the commands for opening (or use a command that knows how to open files of different types).

In some cases you want Terminal Velocity to wait until the command has finished, e.g. when using vim to open a text file, but in other cases you probably want Terminal Velocity to continue running e.g. when opening an image file in another window.

clear screen on exit

It'd be nice to have tv clear the screen when it exits.

Crash when notes dir already exists, but is not a directory

It could be a file, a symlink to a file or dir, a broken symlink, etc. Handle them all, either use a dir or symlink to a dir, or fail and print an error message

Faster startup with lots of notes

For some reason tv takes a long time to startup if you have tens or hundreds of thousands of notes.

No newlines in bash terminal after exiting, Ubuntu only.

In ubuntu using gnome-terminal or xterm, my terminal is messed up after quitting. Newlines are not created and entered text is hidden. Typing reset or stty sane fixes it.

Github, not pip install. Bash only as far as I can tell.

I have the same config for the most part in OSX and this does not happen.

Fails to `pip install`

IT fails to install with pip. Error log is following.

sudo -E pip install terminal_velocity
Downloading/unpacking terminal-velocity
  Could not find a version that satisfies the requirement terminal-velocity (from versions: 0.1a1, 0.1a2, 0.1a3, 0.1a4, 0.1a5, 0.1a6, 0.1a7)
Cleaning up...
No distributions matching the version for terminal-velocity
Storing debug log for failure in /home/dilawar/.pip/pip.log

Installs OK with easy_install though.

A note title with non-ascii characters makes the program crash

Hi @seanh,

I saw your mail in the Urwid mailing list and decided to try it out for giving you some feedback.

When I first ran the program and tried to insert a note with non-ascii characters in the title, terminal_velocity would crash with the following traceback:

# ...
    logger.debug("Initialising new PlainTextNote: '{}'.".format(title))
UnicodeEncodeError: 'ascii' codec can't encode character u'\xe1' in position 9: ordinal not in range(128)

Hooks for sync services

If using git to sync notes, it might be nice if tv could automatically run git pull at startup and on ctrl-l (#7). Could be implemented by adding hooks that call external scripts then adding some git integration scripts, then the same hooks could be used to support other sync services like SimpleText.

This may require #6 first, to inform the user when sync scripts run successfully or fail.

ctrl-l to refresh note list

ctrl-l should refresh the note list, in case the note files have been changed externally.

ctrl-r to rename selected note

should probably support undo as well

crash when trying to pass options to default editor

I'm trying to invoke some flag in vim at launch, ie:
terminal_velocity -e "vim -c 'set spell spelllang=en_us'" SomeLocation

terminal velocity launches, and i can search for a note, but if i create a new one or edit an existing, i get the following crash:

Traceback (most recent call last):
  File "/usr/local/bin/terminal_velocity", line 116, in <module>
    main()
  File "/usr/local/bin/terminal_velocity", line 110, in main
    extension=args.extension, extensions=args.extensions)
  File "/usr/local/lib/python2.7/site-packages/terminal_velocity/urwid_ui.py", line 444, in launch
    loop.run()
  File "/usr/local/lib/python2.7/site-packages/urwid/main_loop.py", line 272, in run
    self.screen.run_wrapper(self._run)
  File "/usr/local/lib/python2.7/site-packages/urwid/raw_display.py", line 242, in run_wrapper
    return fn()
  File "/usr/local/lib/python2.7/site-packages/urwid/main_loop.py", line 337, in _run
    self.event_loop.run()
  File "/usr/local/lib/python2.7/site-packages/urwid/main_loop.py", line 708, in run
    self._loop()
  File "/usr/local/lib/python2.7/site-packages/urwid/main_loop.py", line 787, in _loop
    self._watch_files[fd]()
  File "/usr/local/lib/python2.7/site-packages/urwid/main_loop.py", line 388, in _update
    self.process_input(keys)
  File "/usr/local/lib/python2.7/site-packages/urwid/main_loop.py", line 488, in process_input
    k = self._topmost_widget.keypress(self.screen_size, k)
  File "/usr/local/lib/python2.7/site-packages/terminal_velocity/urwid_ui.py", line 327, in keypress
    system(self.editor, [self.selected_note.abspath], self.loop)
  File "/usr/local/lib/python2.7/site-packages/terminal_velocity/urwid_ui.py", line 41, in system
    raise e
OSError: [Errno 2] No such file or directory

Hide Keyboard Interrupt traceback on ctrl-c

It's confusing because it looks like an error

Faster search function

The current search function in Terminal Velocity is very brute force, every time you type a character it iterates through your notes directory opening every file and checking the contents, there isn't even any caching.

This function actually works fine on my laptop even with thousands of notes but is too slow with tens or hundreds of thousands.

The code is written so that new search functions can easily be plugged in, and they can be compared to the basic search function to see if they produce the same results but faster.

Make the interface translatable

ctrl-h for help dialog

ctrl-h should bring up a help dialog with basic usage and keyboard commands

ctrl-del to delete selected note

should probably support undo

Subdir autocomplete

If the selected note is in a subdir and the user has typed none, or part of, the subdir name, then hitting tab should autocomplete the filename up to and including the next /, rather than all the way to the end

ctrl-v to create new note from clipboard contents

The same as ctrl-n (#2), but paste the contents of the X Windows clipboard into the temp file before opening it. ctrl-v should ignore any text in the search box. ctrl-v when there's no text in the clipboard should do nothing (except trigger a message in the footer).

Don't create a note called "Find or Create"

If the user presses enter when there's no text typed in the search bar, nothing should happen.

Not working after upgrading to big sur.

Traceback (most recent call last):
File "/usr/local/bin/terminal_velocity", line 129, in
main()
File "/usr/local/bin/terminal_velocity", line 123, in main
exclude=args.exclude)
File "/usr/local/lib/python2.7/site-packages/terminal_velocity/urwid_ui.py", line 442, in launch
loop.run()
File "/usr/local/lib/python2.7/site-packages/urwid/main_loop.py", line 272, in run
self.screen.run_wrapper(self._run)
File "/usr/local/lib/python2.7/site-packages/urwid/raw_display.py", line 242, in run_wrapper
return fn()
File "/usr/local/lib/python2.7/site-packages/urwid/main_loop.py", line 312, in _run
self.draw_screen()
File "/usr/local/lib/python2.7/site-packages/urwid/main_loop.py", line 563, in draw_screen
canvas = self._topmost_widget.render(self.screen_size, focus=True)
File "/usr/local/lib/python2.7/site-packages/urwid/widget.py", line 141, in cached_render
canv = fn(self, size, focus=focus)
File "/usr/local/lib/python2.7/site-packages/urwid/container.py", line 1058, in render
focus and self.focus_part == 'body')
File "/usr/local/lib/python2.7/site-packages/urwid/widget.py", line 141, in cached_render
canv = fn(self, size, focus=focus)
File "/usr/local/lib/python2.7/site-packages/urwid/decoration.py", line 564, in render
canv = self._original_widget.render((maxcol,)+size[1:], focus)
File "/usr/local/lib/python2.7/site-packages/urwid/widget.py", line 141, in cached_render
canv = fn(self, size, focus=focus)
File "/usr/local/lib/python2.7/site-packages/terminal_velocity/urwid_ui.py", line 192, in render
return super(NoteFilterListBox, self).render(size, self.fake_focus)
File "/usr/local/lib/python2.7/site-packages/urwid/widget.py", line 141, in cached_render
canv = fn(self, size, focus=focus)
File "/usr/local/lib/python2.7/site-packages/urwid/listbox.py", line 487, in render
canvas = widget.render((maxcol,))
File "/usr/local/lib/python2.7/site-packages/urwid/widget.py", line 141, in cached_render
canv = fn(self, size, focus=focus)
File "/usr/local/lib/python2.7/site-packages/terminal_velocity/urwid_ui.py", line 80, in render
canv = super(NoteWidget, self).render(size, focus=focus)
File "/usr/local/lib/python2.7/site-packages/urwid/widget.py", line 141, in cached_render
canv = fn(self, size, focus=focus)
File "/usr/local/lib/python2.7/site-packages/urwid/widget.py", line 1008, in render
return apply_text_layout(text, attr, trans, maxcol)
File "/usr/local/lib/python2.7/site-packages/urwid/canvas.py", line 1291, in apply_text_layout
text[s.offs:s.end])
File "/usr/local/lib/python2.7/site-packages/urwid/util.py", line 121, in apply_target_encoding
s = s.encode( _target_encoding )
UnicodeEncodeError: 'ascii' codec can't encode character u'\u0301' in position 8: ordinal not in range(128)

Add a footer / statusbar

To show error messages to the user when something goes wrong (e.g. not file could not be decoded to unicode), status messages about tasks tv runs in the background (e.g. sync support), and general info (Terminal Velocity version, notes dir, number of notes).

The statusbar doesn't have to be visible all the time, it can appear for a few seconds when it gets a message then disappear again.

It might be nice to integrate it with Python's logging module i.e. the statusbar would be a log handler.

Make version number accessible from app

The version number should be accessible from within the app (so it can be shown in the footer) and should be printed by --version arg and possibly also in logs and with -h

Repeatedly pressing Tab should cycle between title prefix matches

When there are multiple notes whose title begins with the typed text, tab should cycle the focus between these notes (unlike the up and down arrows which move between all matching notes).

config file should include "exclude directory" option

It would be nice to exclude some subdirectories (in my case ".meta") so that the txt or md files under this folder should not be searched and listed..
may be it's an easy fix but I dont know Python.. sorry..

Edit: I was using the pip install version which didn't have exclude option. Later I noticed the latest version in repo had that option. So, nevermind my comment.

Don't re-search not-matching notes when search text appended to

If the user has just added a character to the end of the search text, then any notes that didn't match before can't possibly match now, so there's no point in search them, just search the matching ones. And if there were none matching before, there will still be none, so don't search at all.

Seems like a big optimisation and an easy one,

Make the UI non-blocking

Currently the UI blocks while the search function is running. The search function should run asynchronously and not block the UI. Use a spinner widget in the search box or footer to indicate the a search is running if it takes too long.

Also applies to other things that might block the UI (e.g. reading the notes dir)

Note body previews in note list

(like Notational Velocity has)