pimterry / notes

:pencil: Simple delightful note taking, with more unix and less lock-in.

notes

Simple delightful note taking, with none of the lock-in.

This demo uses zsh, vim and dropbox, but don't panic, that's just me. notes will work just fine with whatever other text editor, shell and syncing solution you feel like.

Why do I want this?

You already have a tool that backs up and syncs your data (be it Dropbox, iCloud, Seafile or whatever). You already have a text editor on your desktop, your laptops, your phone and that tablet you've forgotten about.

You want to take notes.

You could use a web X.0 note taking app that reimplements all of that from scratch (poorly). You could tie yourself to a tool that holds all your data for you in its own brand-new format, locks you into its (often bloated) UI, and then steadily removes features unless you start paying (hey Evernote). You don't have to.

Instead, you could have a simple folder full of simple text files, synced with your sync-thing of choice, edited with your edit-thing of choice. It's easy to understand, easy to use, and accessible from a million other new tools too whenever you next fancy a change. You can do this with little more than windows explorer and notepad, but it's nice to have a specialised tool to add on top and make this a little neater where you can.

That's where notes comes in. Bring your own data syncing, bring your own text editor, put your notes in good old fashioned files, and notes will give you a CLI tool to neatly glue it all together.

This is just one tool in the chain. notes is a command line tool, and some people will want a proper UI, or a web interface, or something that works on mobile. You can use this in one place and solve every other step in that chain any other way you like though — there's no shortage of simple file browsers and text editors that'll get the job done on any platform you like.

How do I install this?

Automatic:

curl -Ls https://raw.githubusercontent.com/pimterry/notes/latest-release/install.sh | sudo bash

This will install notes, a default configuration, a man page, and bash completion if possible.

curl -Ls https://raw.githubusercontent.com/pimterry/notes/latest-release/install.sh | PREFIX=$HOME bash

For non-root installation(user directory).

Manual:

Download notes, chmod +x, put it in your $path. This will probably do it:

curl https://raw.githubusercontent.com/pimterry/notes/latest-release/notes > /usr/local/bin/notes && chmod +x /usr/local/bin/notes

Installing auto completion

notes includes auto completion, to let you tab-complete commands and your note names. This requires Bash > 4.0 and bash-completion, Zsh, or Fish-shell to be installed - it's probably available from your friendly local package manager.

To enable completion for notes, copy the completion script into your bash, zsh, or fish completion directory, and it should be automatically loaded. The bash completion directory is /usr/share/bash-completion/completions/ on a typical Debian install, or /usr/local/etc/bash_completion.d/ on OSX with bash-completion from homebrew. The zsh completion directory is /usr/share/zsh/functions/Completion/ in Linux. The fish completion directory is ~/.config/fish/completions or /etc/fish/completions. You may be able to find your own bash completion directory by running the following command:

pkg-config --variable=completionsdir bash-completion

Installing the completions might be as follows:

Bash

curl https://raw.githubusercontent.com/pimterry/notes/latest-release/notes.bash_completion > /usr/share/bash-completion/completions/notes

Zsh

On *buntu based distros and OSX:

curl -L https://raw.githubusercontent.com/pimterry/notes/latest-release/_notes > /usr/local/share/zsh/site-functions/_notes

On other Unix distros:

curl -L https://raw.githubusercontent.com/pimterry/notes/latest-release/_notes > /usr/share/zsh/site-functions/_notes

Fish

curl -L https://raw.githubusercontent.com/pimterry/notes/latest-release/notes.fish > ~/.config/fish/completions/notes.fish

You'll need to open a new shell for this to take effect.

What if I want to uninstall this?

If you used the automated install script to install notes, you can uninstall it the same way, by running:

curl -L https://raw.githubusercontent.com/pimterry/notes/latest-release/install.sh | bash -s -- uninstall

How do I configure this?

By default your notes live in ~/notes, but you can change that to anywhere you like by setting the $NOTES_DIRECTORY environmental variable. See how do I configure this? for more details.

To get started with you'll want to set $EDITOR to your favourite text editor, and probably $NOTES_DIRECTORY to the directory in which you'd like to use to store your notes (this defaults to ~/notes). You'll typically want to set these as environment variables in your .bashrc, .zshrc, or similar. Remember to use export command when setting environment variables on the command line in Linux.

There are also more complex options available. You can set any configuration properties either in the environment, or in a config file (stored in ~/.config/notes/config), with settings in config overriding those in your environment. This allows you to configure a different $EDITOR for notes to everything else, if you like. The config file is a good choice for more complex set ups, but probably not worth worrying about to start with. We've included an example config in this repo for you (config) that you can copy if you like.

What are the configuration options?

• QUICKNOTE_FORMAT changes the way that quicknotes are generated. The string formatted using the date command.
• NOTES_EXT changes the default extension that notes are saved with.
• TEMPLATES_DIR changes the directory in which templates are stored.
• NOTES_DIRECTORY changes the directory in which notes are stored.
• EDITOR can also be overriden here, for notes only.
• POST_COMMAND sets the command to run after any modification command (e.g. open, mv, ...) succeeds

How do I use it?

notes new [-t <template-name>] <note-name>

Opens your $EDITOR of choice for a new note, with the given name. The name can include slashes, if you want to put your note in a subfolder. Leave out the name if you want one to be generated for you (e.g. quicknote-2016-12-21.md - format configurable with $QUICKNOTE_FORMAT). If you want to place a quicknote in a subfolder, use a trailing slash: notes new subfolder/. Shorthand alias also available with notes n.

If you pass the -t flag to notes new, the note will be created from a template. The template is a file in your notes directory, with the same name as the template name you pass in. For example, if you have a template called meeting-notes in your notes directory, you can create a new note from that template with notes new -t meeting-notes new-file-name. This will open your $EDITOR with the contents of that template file, and you can edit it and save it as a new note.

If you do not supply an extension in note-name, it will be automatically appended with the default file extension (e.g. "newnote" will become "newnote.md"). However, if you include a one-to-four-letter file extension, notes will use that extension when creating the file (e.g. "newnote.tex" is created as "newnote.tex"; not "newnote.md", or "newnote.tex.md").

notes find <part-of-a-note-name>

Searches note filenames and paths for the given string, and returns every single match. If no pattern is specified, this returns every single note. Shorthand alias also available with notes f.

notes grep <part-of-some-note-content>

Searches all note content for the given string and returns all the matches. Shorthand alias also available with notes g.

notes search <part-of-a-note-name-or-note-content>

Searches all note content and note filenames for the given string and returns all the matches. Shorthand alias also available with notes s.

notes ls <directory>

Lists note names and note directories at a single level. Lists all top level notes and directories if no path is provided, or the top-level contents of a directory if one is provided. Automatically ignores hidden files or filenames ending with ~ (Vim backup files).

notes open

Opens your notes folder in your default configured file explorer. Shorthand alias also available with notes o.

notes open <note-name>

Opens a given note in your $EDITOR. Name can be an absolute path, or a relative path in your notes (.md suffix optional). Shorthand alias also available with notes o.

If no file-suffix is given in note-name, the notes will attempt to open note-name.md (or whatever your default suffix is set to). However, if the note-name is given an suffix, the default suffix will not be appended (e.g. notes open note-name.txt will open note-name.txt; not note-name.md or note-name.txt.md).

notes append <note-name> [message]

Appends message to the note-name note. If this note does not exist, a new note of will be created. This command also accepts stdin via piping. An example would be echo "hello" | notes append <note-name> Shorthand alias also available with notes a.

notes mv <note-name> <destination>|<directory>

Renames a given note to destination or moves the note to directory. Name can be an absolute path, or a relative path in your notes (.md suffix optional). Destination and directory have to be a relative path in your notes.

notes rm [-r | --recursive] <note-name>

Removes the given note if it exists. If -r or --recursive is given, deletes the folders/notes recursively.

notes cat <note-name>

Displays the note. Shorthand alias also available with notes c.

notes grep/find <pattern> | notes open

Combine these together! This opens each matching note in your $EDITOR in turn.

notes realpath [note-name]

Displays the path to the note name, if provided. Displays the root path to all notes otherwise.

Tell me of the future

All the above works. Here's what's coming next:

• More interesting and nicer looking file/grep search result formatting, perhaps only when not piping? (#27)
• Make the file extension optional (#24)
• Interactive mode? notes could open a scrollable list of notes, open your editor when you pick one, and reappear after you close it. (#17)
• Tree view (#26)
• Easy way to see short notes snippets in find/grep/tree? Could be option (--snippets) or by piping to a command (notes find | notes snippets). Maybe call it head? (#22)
• Version control - probably by finding an easy (optional) way to integrate this automatically with Git (#12)

I want to help

Great! Jump in. Feel free to play around, open an issue with new feature ideas or open PRs for fixes and improvements. Do check with an issue first if you're planning to do anything substantial to avoid disappointment.

Remember that notes is intended to be a small toolbox of commands - if it's possible to build your extension as an independent wrapper building on the existing notes commands, that's probably a better first step. Create new functionality on top of notes and then file issues to extend notes to better support that wrapper, or to merge your wrapper in as a built-in command later, once you're sure it works and it's useful.

If you want to get the code locally you'll need to:

git clone <your fork>
git submodule update --init --recursive
./test.sh # Check the tests work before you make any changes

If you install entr you can also run ./dev.sh, which will watch all files within the project directory, and rerun tests any time they change.

If you submit a PR, please make sure it:

• Doesn't break any existing tests
• Adds new tests, if appropriate
• Adds new documentation, if appropriate

Release process

To build a new release of notes:

• export NEW_VERSION="X.Y.Z" (replacing X.Y.Z with the appropriate new version)
• Run:

  # Update the version number in the source
  sed -i -e "s/notes_version=.*/notes_version=\"$NEW_VERSION\"/g" notes
  
  # Commit, tag & push the new version
  git add notes
  git commit -m $NEW_VERSION
  git tag $NEW_VERSION
  git push origin master --tags
  
  # Mark this version as the latest release
  git checkout -B latest-release
  git push --force origin latest-release
  git checkout -
  

notes's Issues

Add ZSH command and note name autocompletion

Also add to https://github.com/zsh-users/zsh-completions

Feature Request: 2 Layers of Direrctories

I haven't actually used this yet as I just saw the reddit post, so forgive me if this feature already exists!

I'd like to see if it's possible to add 2 layers of directories, such as a layer of notebooks and inside each notebook have a layer of sections. This would make it easier to use for taking notes in University, I'd have a notebook for each class, a section for each chapter, and each individual file would be like a page. (Microsoft OneNote already has this, and it's the only feature holding me back from using this program over OneNote).

Thanks for reading and I hope you like the idea!

Stop assuming .md

It'd be nice to have a configurable file extension, as nothing within notes actually depends on markdown formatting, and users might have other preferences or have their content in an existing different format.

This should be exposed through config (#21), and .md should be happily used automatically by default.

Autocompletion doesn't work for notes o or notes ls

Hello!!

First of all, thank you very much for this tool, it's just awesome. I tried to install the auto-completion package (on Ubuntu) and it works perfectly autocompleting the command names, but not for the file names. Am I missing any configuration?

Thanks in advance

Add bash completion to homebrew

https://github.com/Homebrew/homebrew-completions

Interactive Mode

I'm willing to put together a pull request for interactive mode, but I'd most likely want to depend on junegunn/fzf for the interactive functionality. @pimterry - does that jive with what you were looking to do?

Bug: Typing "notes new" without a name should error out

if you type "notes new" without a file name, you create a note just named ".md"
We should include a sanity check in the code to prevent this from happening.

Prettier grep/find/search result formatting

grep showing the matching line and context would be useful.

Would be nice to colourise and highlight the matching part of the content/filename that matches too

Need to make sure any work on this doesn't break piping results into other commands.

notes should ignore files in hidden directories

I sync my notes with syncthing, so I sometimes get copies of my files under notes/.stversions, which show up when doing 'notes grep' etc.

notes should ignore files which are under directories starting with a '.', or at least there should be a configuration option for that. An ignore file would perhaps be even better.

ZSH autocompletion URL is a 404

https://cdn.rawgit.com/pimterry/notes/v0.2.0/notes._notes spits out a 404. This breaks the line
curl https://cdn.rawgit.com/pimterry/notes/v0.2.0/notes._notes > /usr/share/zsh/site-functions/_notes

Edit and save a file that is not of the default NOTES_EXT

My NOTES_EXT variable is set to markdown, which is good, because that's what I take most of my notes in. However many of my "notes" are .c or .py files filled with comments on however the code in the file works. Whenever I open one of these files, notes makes a new blank .md file and names it exactly the same as the file I was trying to open instead of just opening the file. So, for example, if I were trying to open file.c, notes will make a new file titled file.c.md. I want to be able to edit .md notes along with .c and .py. Thanks!

Feature Request: notes grep should show the notes content entries

I think that notes grep command should not only list the notes title but also show the lines where the pattern has been found.

Add a --version option

It would be useful to have a --version option to display which would allow users to know what version they have installed.

Feature Request: ~/.notesrc config file

Rather than check for $notes_editor (proposed) and $NOTES_Directory, we should check for a config file in the home directory. This is how most applications work, and it provides a cleaner way to set all the configurations (and gives us the ability to stop worrying about adding enviorment variables)

Feature Request: notes cat command

I think a useful command would be "notes cat [pattern]".
The command should output the content of the note and partial file names specified as pattern should be accepted too.
The pattern searching should be fuzzy.

exits successfully($? is 0) when it fails to create notes

Issue Summary

When $NOTES_DIRECTORY is set to a filename, that already exists in the directory.
It opens a new note but fails to save it, and exits 0
(as the exit status depends on the editor)

Steps to Reproduce

1. touch /tmp/secret
2. env NOTES_DIRECTORY=/tmp/secret notes n leaks
3. edit and save(fails to save), quit forcefully.
4. Once you are back at shell, echo $?

Expected Behavior

exit before opening the editor and ask user to set NOTES_DIRECTORY to a safe location.
ofc, exit with non-zero status

Somehow show content snippets without breaking piping

A lot of the time, it's useful to be able to see intro snippets of content when flicking through your notes. There's a few way to do this, but an important constraint is that anything that does this needs to play nicely with piping. You must be able to pipe the results of a search into notes open and open all the matching notes.

Implementation options:

• Command line option (--snippets?) which adds snippets to output.
• Separate command which provides snippets for the given files (notes find | notes snippets? | notes head?).
• Output snippets when stdout is a tty, but hide them and output only the file names if it's not.

Thoughts welcome.

Rawgit is deprecated

this project uses rawgit to host the install script, but the rawgit.com site says their site is deprecated and would close down anytime.
Shouldn't you just use the script hosted at the repo instead?

Pass args to Post install script

Issue Summary

Post Script passes no information to the script. I write my notes in md files and I would like to write a script that uses pandoc to convert the md to pdf files when the vim process completes. However, no information is passed to the post-script to make use of a script.

Technical details:

• notes version: master (latest commit: [commit number])

The strange case of missing note

Issue Summary

Newly created note(with extension) fails to open.

Steps to Reproduce

1. notes new dylan.md
2. type in text, save and quit
3. notes o dylan.md
   3rd step opens a new note instead of the note created in step 1.
   Is this the expected behaviour? seems strange to me :\

Technical details:

In order to reassure my doubts the command below was run.
curl https://raw.githubusercontent.com/pimterry/notes/latest-release/notes > ~/bin/notes

Option to sync with git automatically

I think it might be nice to have some kind of automatic git integration. Since gdrive still isn't a first class citizen on Linux and I don't use any other sync service, some kind of git hooks would be a great alternative for me, and I would assume others.

This is a neat helper, great idea!

Zsh autocompletion not working on Mac

Issue Summary

Installing the autocompletion (following instructions) script at:
/usr/local/share/zsh/site-functions
And checking the permissions are all ok, autocompletion does not work

Steps to Reproduce

1. Install notes on a Mac:
   curl -L https://rawgit.com/pimterry/notes/latest-release/install.sh | zsh

2. Install autocompletion script
   curl -L https://rawgit.com/pimterry/notes/latest-release/_notes > /usr/local/share/zsh/site-functions/_notes

3. Set $NOTES_DIRECTORY on .zshrc

4. Relaunch shell
   notes autocompletion does not work. Other zsh completion scripts for other commands do work

thanks! :-D

Spelling errors in pull request template. see checklist point 3.

was it intentional :/

Tree view

Debatable if this is still useful, now that we have ls (#19). Would it be useful if you had a way to turn a list of note names into a tree view? E.g. notes find <pattern> | notes tree:

├── my-note.md
├── notes/
    ├── another-note.md
    └── more-notes.md

Would you find this useful? Thoughts welcome.

Allow easily getting full note paths, for compatibility with other commands

Outputting nice short names (just note.md) is great for readability when flicking through your notes. For compatibility with other commands though (e.g. cat: #9), you need a way to easily get the full file path (/home/tim/notes/note.md).

There's a couple of options:

• Only output short names to a TTY, but automatically output full paths instead when piping.
• Add a notes path command, which gives you the path to a given note (useful generally), or transforms a pipe of short note names into full note paths. E.g. notes find | notes path to get the full paths for every note you have.

Thoughts welcome!

Notes mv

A nice feature would be the ability to move notes (to other folder or renaming the file).

Syntax could be:
notes mv MyWorkTodos.md Todo/Work.md
or
notes mv MyWorkTodos Todo/Work

The latter (without the extensions) would be inline with the other commands.

Running tests

There seems to be tests in the repository, yet no instructions on how to run/use/extend them.

I suggest adding a Makefile or similar that downloads bats and runs the test

Find and search do not work if notes directory is symbolic link

Issue Summary

If the notes directory is a symbolic link, find and search are always empty.

Steps to Reproduce

1. Create symbolic link ln -s ~/Google\ Drive/Notes ~/Notes
2. Run notes find
3. No notes are returned

Seems be resolved with -H flag in script when calling find

Technical details:

• notes version: master (latest commit: bd5a895)
• shell: zsh 5.8
• OS: macOS Big Sur

"notes recent" command to show recently edited notes

It would be nice if I could see the notes I've recently edited (or perhaps even the ones I've recently accessed), with a command like notes recent. I may take a whack at this myself and submit a PR, but am interested in hearing thoughts on this before I go off coding.

BATS fails on "Show multiple files passed by pipe from find"

Issue Summary

Commit 00f9e66 which was merge request #71 to fix #38 fails BATS test for show multiple files passed by pipe from find.

The specific failure output is a reversed from expected output as shown in the Technical details section.
This may be a failing of the test itself or a failing of the find code.
However, manually running the test without BATS does not have this failing.

Steps to Reproduce

1. Run BATS.

Technical details:

• notes version: master (latest commit: 00f9e66)
  Error from BATS:

not ok 12 Show multiple files passed by pipe from find
(from function `assert_output' in file test/libs/bats-assert/src/assert.bash, line 239,
in test file test/test-cat.bats, line 65)
`assert_output $'line1\nline2'' failed
-- output differs --
expected (2 lines):
  line1
  line2
actual (2 lines):
  line2
  line1
--

Append a message to note

Quickly append a message to a note without opening the file.

'notes o' says it can't get a file descriptor on Linux

Issue Summary

notes o doesn't open a directory as expected to.

Steps to Reproduce

1. notes o

Couldn't get a file descriptor referring to the console

Apparently, open command gives the same error message, on the device I tried.
In another device, $ notes o reports "open: command not found"

Technical details:

• notes version: master

P.S:
If output of any relevant commands will help, let me know. I'll be glad to paste it here.

Templates for Issues and Pull Requests.

So Github has the ability to template pull requests and issues. I think it'd be good practice to create these for notes.

For Issues, we should make three headings and a comment at the top something like "If this is a suggested feature, please ignore" or something along that line.

• Summary of Issue
• Steps to Reproduce
• Technical Details

For pull requests, we should have a checklist of things we should be looking for to speed up PR's:

• Added tests for new functionality and they all pass
• Added documentation for added features
• Pulled my branch up to master branch's HEAD before commit

etc.

Tag support for notes

Feature Request

• Tag support for notes to find notes by tags

it would be really cool if we can add multiple tags to a note
This is already an awesome app tnx <3

Option to just print the note and exit, like cat command

Hi, I added option cat to just print the note and exit. using https://github.com/axiros/terminal_markdown_viewer to prettify. Personally I find it useful. Do you think others might like it?

settting $NOTES_DIRECTORY does not affect program

Issue Summary

$NOTES_DIRECTORY does not affect program

Steps to Reproduce

• Ubuntu WSL, installing notes via curl

• NOTES_DIRECTORY=some/directory

• $NOTES_DIRECTORY shows

-bash: some/directory: Is a directory

• notes --help

Your notes directory is /home/epo/notes. You can
override this by setting $NOTES_DIRECTORY to your preferred path.

Improve installation process

At the moment, the installation process is just putting the files into the correct spot and making them executable. There is no solid process for applying updates. I was wondering if there was some simple way to update the process so that pulling in updates was easy? I would do a pull request, but I am no unix pro so I figured I would ask for advice first.

Asside from this being part of the mainstream package managers, my first thought would be to check out the git repo, so that you can git pull on it, then symlink notes into /usr/local/bin/notes and notes.bash_completion to /usr/share/bash-completion/completions/notes. Would this cause issues or be difficult to maintain? I guess this would assume the user has git installed...

Down the road you could even apply some sort of auto-update process. If it becomes part of a package manager then it would be built in, but if we did something like the above idea with git it could do a git pull in the background when you run the notes command every so often. Maybe the notes script could check for updates and curl them in automatically so it does not rely on git.

Thoughts?

Notes open does not cd to notes directory

Issue Summary

The documentation as well as the --help command specify that using notes open|o would open my notes directory. But it does not.

Steps to Reproduce

1. Install notes
2. Specify your notes directory
3. Enter notes o

After these steps, this is the output of the script: /usr/local/bin/notes: line 232: open: command not found

Technical details:

• notes version: 1.3.0

Feature request: Add post-command hook

It would be nice to have some post-command hook in notes so that after executing a command, the user can run a custom script or command.

This idea is inspired by using git to manage the notes from #12. The easiest way to do that is to let the user handle all of this after running any command, so they can detect changes, commit them, and push them if they want.

One easy way to do that is to add an option like POST_COMMAND in the configurations. That would not bring any breaking changes as well.

If it's a good idea, I'm happy to work on it and open a PR later.

Thanks

Feature Request: Add to AUR