nts is pure python and runs in a terminal window on any platform that supports python >= 3.7.3. Its purpose is to facilitate both recording and retrieving information. Further information is available at github, the nts discussion group at groups.io and PyPI.
Notes are recorded in plain text files with the extension ".txt" located anywhere below the nts data directory. Note files have a simple format:
-
Each note begins with a "+" in the first column followed by a space and then the title of the note.
-
Tags, if given, are comma separated and enclosed in parentheses after the note title.
-
The note body begins on the next line and continues until another note or the end of the file is reached.
-
Lines that begin with one or more white space characters and then "+" are treated as part of the note body and not as the beginning of a new note.
-
White space in the note body is preserved but whitespace between notes is ignored.
-
Hidden files, i.e. files with names beginning with a period, are ignored.
-
Directory and file names should not contain spaces.
Suppose, e.g., that the nts data directory contains a single file
~/nts/data/parent/child/grandchild.txt
with this content:
---------------- grandchild.txt begins ---------------
+ note a (red, green)
The body of note a goes here
+ note b (blue, green)
The body of note b here
+ note c (red, blue)
And the body of note c here
---------------- grandchild.txt ends -----------------
nts provides two main views of this data.
-
Path View:
└── parent 1 └── child 2 └── grandchild.txt 3 + note a (red, green) 3-1 + note b (blue, green) 3-2 + note c (red, blue) 3-3 -
Tag View:
├── blue 1 │ + note b (blue, green) 1-1 │ + note c (red, blue) 1-2 ├── green 2 │ + note a (red, green) 2-1 │ + note b (blue, green) 2-2 └── red 3 + note a (red, green) 3-1 + note c (red, blue) 3-2
Both views are outlines with branches that end with leaves that correspond to note title lines. In path view, the nodes along the branches correspond to directory or file names and there can be many of these in each branch. In tag view, on the other hand, the nodes correspond to tag names and there can only be one of these in each branch.
The numeric identifiers appended to the lines in both views are provided by nts. These are single numbers for the nodes in the outline branches that have children and hyphenated numbers for the leaves, e.g., in path view the "3" appended to the "grandchild.txt" node and the "3-1" appended to the "+ note a (red, green)" leaf. In the leaf identifier, the first of the two numbers is the indentifier of the parent node. These identifiers are the IDENT arguments in the Command Summary given below.
nts provides two ways of interacting with the data.
-
Command mode
Commands are entered at the terminal prompt. E.g., enter
$ nts -pto display the path view in the terminal window. The output can also be piped in the standard way, e.g.,
$ nts -p | less -
Session mode
Use the
-sargument to begin session mode:$ nts -sThis begins a session in which data is loaded into memory and remains available for subsequent interaction. In this mode, nts assumes command of the terminal window. Then, e.g., pressing
pwould display the path view. Session mode adds several features not available in command mode, e.g., scrolling, incremental search, auto-completion and auto-suggestion.
| Action | Command Mode | Session Mode | Notes |
|---|---|---|---|
| help | -h | h | ~ |
| begin session | -s | ~ | ~ |
| end session | ~ | ^q or F8 | ~ |
| path view | -p | p | ~ |
| tags view | -t | t | ~ |
| hide leaves | -l | l | l |
| hide branches | -b | b | b |
| copy view | ~ | c | c |
| set max levels | -m MAX | m MAX | m |
| search | / SEARCH | / | |
| find REGEX | -f [!]REGEX | f [!]REGEX | f |
| get REGEX | -g REGEX | g REGEX | g |
| join JOIN | -j JOIN | j JOIN | j |
| inspect IDENT | -i IDENT | i IDENT | i |
| edit IDENT | -e IDENT | e IDENT | e |
| add to IDENT | -a IDENT [NAME] | a IDENT [NAME] | a |
| refresh | ~ | r | r |
| edit cfg.yaml | ~ | y | y |
| version check | -v | v | v |
-
l: Suppress showing leaves in the outline. In session mode this toggles the display of leaves off and on.
-
b: Suppress showing branches in the outline, i.e., display only the leaves. In session mode this toggles the display of the branches off and on.
-
c: Copy the active view to the system clipboard.
-
m: Limit the diplay of nodes in the branches to the integer MAX levels below the starting node. Use MAX = 0 to display all levels.
-
/|?: Start a case-insensitive, incremental search forward (/) or backward (?) for SEARCH. When the search is active, press "n" to continue the search in the same or "N" reverse direction, ",," (two commas successively) to clear the search or ".." to apply the search to the complete notes of the active view.
-
f: Show notes in the current view whose content contains a match for the case-insensitive regex REGEX. Press ",," to clear the search highlighting.
-
g: Display note titles that contain a match in the nodes leading to the note for the case-insensitive regular expression REGEX.
-
j: Display note titles for notes with tags satisfying JOIN. E.g. if JOIN = "red", then notes containing the tag "RED" would be displayed. If JOIN = "| red, blue" then notes with either the tag "red" or the tag "blue" would be displayed. Finally, if JOIN = "& red, blue", then notes with both the tags "red" and "blue" would be displayed. In general JOIN = [|&] comma-separated list of case-insensitive regular expressions.
-
i: If IDENT is the 2-number identifier for a note, then display the contents of that note. Else if IDENT is the identifier for a ".txt" file, then display the contents of that file. Otherwise limit the display to that part of the outline which starts from the corresponding node. Use IDENT = 0 to start from the root node.
-
e: If IDENT corresponds to either a note or a ".txt" file, then open that file for editing and, in the case of a note, scroll to the beginning line of the note.
-
a: If IDENT corresponds to either a note or a ".txt" file, then open that file for appending a new note. Otherwise, if IDENT corresponds to a directory and NAME is provided, add a child called NAME to that node. If NAME ends with ".txt", a new note file will be created. Otherwise, a new subdirectory called NAME will be added to the node directory. Use "0" as the IDENT to add to the root (data) node. In command mode, "IDENT NAME" should be wrapped in quotes.
-
r: reload data from the files in the data directory to incorporate external changes.
-
y: open cfg.yaml in the external editor and, when the editor is closed, incorporate any modifications into the active session.
-
v: Compare the installed version of nts with the latest version on GitHub (requires internet connection) and report the result.
Here is a link to a series of short videos illustrating basic usage:
There are no commands in nts to remove either a file or a directory. Please use your favorite file manager for these risky actions and don't forget to restart nts to update its display.
Note: when your configuraton settings specify that the external editor should open in the same terminal as nts, it may be necessary to press "Ctrl-L" to restore the display after closing the editor.
In session mode, if one of the IDENT commands (a, e or i) is invoked when the cursor is on a line ending with an IDENT, then that IDENT will automatically be entered for the command. Otherwise, when manually entering an IDENT, pressing the tab key will cycle through IDENTs that complete the current entry.
As an illustration of auto-suggestion, a common workflow is to examine a note and then, perhaps, edit it. In the screenshot above I clicked on the word "action" in the line that ends with 4-4 as its IDENT. Pressing "i", would then prompt for the IDENT:
> 4-4
with 4-4 already entered. Pressing "return" would then display the details for this note as:
./tagsort.txt 4-4
+ assigned for action (assigned bob)
In tag view, items with this tag will be sorted
in a third group and, within that group, by the
name to whom it was assigned
With the cursor still on the top line ending with the same 4-4 IDENT, pressing "e" would prompt for the IDENT:
> 4-4
with the 4-4 already entered. Pressing "return" would then open this same note in the external editor. Note that just five actions were involved: one mouse click and four key presses: "i", "return", "e" and "return".
nts runs in a terminal window that should be configured to use a fixed width (monospaced) font. Menlo Regular for OSX and DejaVu Sans Mono for Linux are good choices. A width of at least 60 characters for the terminal window is recommended.
Before you start nts for the first time, think about where you would like to keep your personal data files and any log files that nts will create. This will be your nts home directory. The nts configuration file, "cfg.yaml" will be placed in this directory as well as the data and log files in the subdirectories data and logs, respectively.
The default is to use the current working directory when you start nts as the home directory either 1) if it is empty (unused so far) or 2) if it contains subdirectories called "data" and "logs" or 3) if it contains a file called "cfg.yaml" and a subdirectory called "logs". To use this option just change to this directory before starting nts.
Alternatively, if the current working directory doesn't satisfy the requirments but there is an environmental variable, NTSHOME, that contains the path to an existing directory, then nts will use this as its home directory. To use this option, first create the directory and then set the enivonmental variable by, e.g., appending the following to your "~/.bash_profile":
export NTSHOME="complete path to the nts home directory"
Finally, if neither of the previous alternatives are satisfied, then nts will use "~/nts" as its home directory, creating this directory if necessary.
The nts "data" and "logs" directories will be created if necessary as well as the nts configuration file, "cfg.yaml" using default settings. If "data" needs to be created, the user will additionally be offered the opportunity to populate it with illustrative data. Here are the default contents of this file when the "dark" background option is chosen at installation:
# Changes to this file only take effect when nts is restarted.
# EDIT
# The following are examples using the editor vim. Tip: to use the
# native version of vim under Mac OSX, replace 'vim' in edit_command
# with:
# /Applications/MacVim.app/Contents/MacOS/Vim
edit_command: vim
# session_edit_args: arguments to edit {filepath} at {linenum} in
# session mode and await completion
session_edit_args: -g -f +{linenum} {filepath}
# session_add: arguments to edit {filepath} at end of file in session
# mode and await completion
session_add_args: -g -f + {filepath}
# command_edit_args: arguments to edit {filepath} at {linenum} in
# command mode without waiting
command_edit_args: +{linenum} {filepath}
# command_add_args: arguments to edit {filepath} at end of file
# in command mode without waiting
command_add_args: + {filepath}
# TAG SORT
# For listed keys, sort by the corresponding value. E.g. In tag view
# items with the tag "now" will be sorted as if they had the tag "!".
# Replace, remove or add keys and values with whatever you like.
tag_sort:
now: '!'
next: '#'
assigned: '%'
someday: '&'
completed: '('
# STYLE
light_background: false
style:
status: '#FFFFFF bg:#396060'
status.key: '#FFAA00'
not-searching: '#888888'
highlighted: '#000000 bg:#FFFF75'
plain: '#FAFAFA bg:#1D3030'
When the "light" background option is chosen the relevant lines are changed to these:
light_background: true
style:
status: '#FFFFFF bg:#437070'
status.key: '#FFAA00'
not-searching: '#888888'
highlighted: '#1D3030 bg:#A1CAF1'
plain: '#000000 bg:#FFF8DC'
If you make changes to "cfg.yaml" and would like to restore the defaults just delete the relevant settings from the file and restart nts - the missing settings will be restored with their default values.
From time to time, new versions of nts may add new settings to "cfg.yaml". When this happens, the new settings will automatically be added to your "cfg.yaml" the next time you start nts.
The default values for tag_sort in "cfg.yaml" mean that notes will be sorted in in tag_view so that items with the tag "now" will be sorted as if the tag were "!", items with the tag "next" as if the tag were "#" and so forth. Tags not listed in tag_sort will sorted using the actual tag. The dictionary sorting order for common keyboard characters in python is:
! # % & ( ) * + - / 1 2 3 ; < = > ? @ A B C [ ] ^ _ a b c { } ~
nts implicitly assigns the tag "~" to notes without tags and, because of this sorting order, untagged items are listed last in Tags View.
To illustrate this tag sorting with the default configuration, suppose the file
~/nts/data/tagsort.txt
is added to the grandchild example given above with the following content:
---------------- tagsort.txt begins ---------------
+ action required as soon as possible (now)
In tag view, items with this tag will be sorted
first
+ action needed when time permits (next)
In tag view, items with this tag will be sorted
after 'now' items
+ assigned for action (assigned joe)
In tag view, items with this tag will be sorted
in a third group and, within that group, by the
name to whom it was assigned
+ assigned for action (assigned bob)
In tag view, items with this tag will be sorted
in a third group and, within that group, by the
name to whom it was assigned
+ review from time to time for action (someday)
In tag view, items with this tag will be sorted
after all tagged items other than 'completed'
+ finished but kept for reference (completed)
In tag view, items with this tag will be sorted
after all tagged items
+ a note with no tags
In tag view, such items will be sorted last under
the implicit tag '~'
---------------- tagsort.txt ends -----------------
With this addition, Path View appears as:
├── parent 1
│ └── child 2
│ └── grandchild.txt 3
│ + note a (red, green) 3-1
│ + note b (blue, green) 3-2
│ + note c (red, blue) 3-3
└── tagsort.txt 4
+ action required as soon as possible (now) 4-1
+ action needed when time permits (next) 4-2
+ assigned for action (assigned joe) 4-3
+ assigned for action (assigned bob) 4-4
+ review from time to time for action (someday) 4-5
+ finished but kept for reference (completed) 4-6
+ a note with no tags 4-7
Sorting in this view is dictionary order for sibling nodes but notes are listed in the order in which they occur in the file. E.g., the siblings "parent" and "tagsort.txt" are in dictionary order but the notes in each file are listed in the order in which they occur in the file.
Tags View reflects the tag_sort setting in "cfg.yaml" with the Getting Things Done tags now, next, assigned, someday and completed first in that order, then blue, green and red in the middle in dictionary order and finally ~ (no tags) last:
├── now 1
│ + action required as soon as possible (now) 1-1
├── next 2
│ + action needed when time permits (next) 2-1
├── assigned bob 3
│ + assigned for action (assigned bob) 3-1
├── assigned joe 4
│ + assigned for action (assigned joe) 4-1
├── someday 5
│ + review from time to time for action (someday) 5-1
├── completed 6
│ + finished but kept for reference (completed) 6-1
├── blue 7
│ + note b (blue, green) 7-1
│ + note c (red, blue) 7-2
├── green 8
│ + note a (red, green) 8-1
│ + note b (blue, green) 8-2
├── red 9
│ + note a (red, green) 9-1
│ + note c (red, blue) 9-2
└── ~ 10
+ a note with no tags 10-1
Note also that within the assigned tags, the sorting is in dictionary order with assigned bob followed by assigned joe even though assigned joe occured before assigned bob in the file.
The steps for OS/X or linux are illustrated below. For details see python-virtual-environments-a-primer.
Open a terminal and begin by creating a new directory/folder for the virtual environment, say nts-pypi, in your home directory:
$ mkdir ~/nts-pypi
$ cd ~/nts-pypi
Now continue by creating the virtual environment (python >= 3.7.3 is required for nts):
$ python3 -m venv env
After a few seconds you will have an ./env directory. Now activate the virtual environment:
$ source env/bin/activate
The prompt will now change to something containing (env) to indicate that the virtual environment is active. Updating pip is now recommended:
(env) $ pip install -U pip
Note that this invokes ./env/bin/pip. Once this is finished, use pip to install nts:
(env) $ pip install -U nts-dgraham
This will install nts and all its requirements in
./env/lib/python3.x/sitepackages
and will also install an executable called nts in ./env/bin.You can then start nts using
(env) nts ARGS
using ARGS enumerated in the Command Summary section above.
If your system allows you to run sudo and you want general access system wide, then you could instead install nts using
$ sudo -H python3.x -m pip install -U nts-dgraham
replacing the 3.x with the verion of python you want to use, e.g., 3.7. This would put nts in your path (in the bin directory for python3.7).
You can then open a terminal and start nts using
$ nts ARGS
using ARGS enumerated in the Command Summary section above.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. See GNU General Public License for more details. This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.