notes - Simple. Git-based. Notes.


version 0.013


    Usage: notes command [arguments]

    Available Commands:
        add     add a new note, and edit it
        append  append to a note ( from STDIN )
        delete  delete the note
        edit    edit a note
        help    show syntax and available commands
        init    Initiliazie notes (optionally from remote repo)
        list    lists id and subject of all notes
        replace replace the contents of the note ( from STDIN )
        show    show the contents of the note
        sync    Sync notes with remote (pull + push)

    # To get started
    $ notes init
    # Or, optionally, get started with an existing git repo
    $ notes init

    # Create a note and edit it (with $EDITOR, or vim by default)
    # Note name will be Hello-World
    $ notes add Hello World
    # Add another (markdown) note via STDIN
    $ echo "# Title" | notes add

    # List notes
    $ notes list

    # List notes w/filter (case-insensitive)
    $ notes list te

    # Create a new note
    # This will open up your $EDITOR for you to type your note
    $ notes add groceries

    # Edit a note (finds the most recently edited match, case insensitive)
    # This will open up the Hello-World note created above
    $ notes edit hel

    # Will replace the contents of Hello-World with "Hello, World"
    $ echo "Hello, World" | notes replace hel

    # Will append "END" to Hello-World
    $ echo "END" | notes append he

    # Sync notes with remote (if your git repo has a remote)
    $ notes sync


App::Notes is a very simple command line tool that lets you creat, edit, search, and manage simple text-based notes inside of a git repository.

This is very useful for keeping notes in a repository (especially a gist on GitHub) that can be sync'ed across machines. Since it is backed by git, you will have a history of all your changes.



    notes add <name>
    echo hello | notes add <name>

Creates a new note. A name argument is required. This command will open your $EDITOR (such as vim or emacs) for you to type your note. When you are done, simply save and quit out of your editor and your note will be created. If you pipe to STDIN, then your editor will not be opened. Your note will be created with the contents from STDIN.


    $ echo bananas | notes append 'Favorite Foods'

Appends the content from STDIN to the given note.


    $ notes delete foo


    $ notes edit
    $ notes edit <name | filter>

Edits the given note. This command will open your $EDITOR (such as vim or emacs) for you to edit your note. Once you are done editing, simply save and quit your editor. If called with no arguments, this command will edit your last note.


    $ notes init
    $ notes init <git url>

Initializes the git repository. This must be called once before using this application.


    $ notes list
    $ notes list <filter>

Lists all of your notes


    $ echo hola | notes replace hello

Replaces the contents of the given note with the contents from STDIN.


    $ notes show
    $ notes show <name | filter>

Displays the contents of your note. With no arguments, displays the contents of your last note.


    $ notes sync

Syncs your notes by doing a git pull and push. Normally this is not necesary, since by default syncs happen during each command. You can turn the auto sync off if you set the environment variable APP_NOTES_AUTOSYNC=0. Then you have to remember to call sync manually.


Using a github gist

A recommended way to use this app is with a github gist. An advantage of this is that you get a nice user interface for free. You can bookmark the gist in your browser and be able to view and edit your notes from there if you like. To get started, you need a github account. Then simply create a new gist. It doesn't matter what you name your gist. Also, github requires that your gist have some content in the main file. Just type something in, it doesn't matter. You can choose to create a public or private gist. For this application, you most likely will want to create a private gist, unless you want to make your notes public. Once you have created your gist, copy it's url. The url should be displayed at the top and it will be of the form: Then run this on the command line:

    git init <git url>

Now if you run notes list and there should be one note listed. This was the file you made when you created your gist. Feel free to delete this note if you want. Running notes add will add a new note and it will show up in your gist as a new file. Try adding a note and verify that it shows up in your gist on github. Changes you make via the notes tool should show up in your gist and vice versa. Have fun!

Accessing your last note

If you want to edit your last note, simply call edit with no arguments:

    $ notes edit

To see your last note, simply call show with no arguments:

    $ notes show

Every time a note is created, modified or removed, App::Notes will commit the change to the git repo. By default, it will pull before a command executes and push when its done. Except on commands where it doesn't make sense. For example, a push will not happen after calling list or show. To turn this behavior off, set APP_NOTES_AUTOSYNC=0. If you do this, make sure to remember to manually call notes sync, or your notes will get out of sync.


Create a shorter alias for notes, such as n. Run which notes on the command line to find the path that notes was installed to. Then create an alias in your ~/.bashrc:

    alias n=</path/to/notes>

Now you can run notes by just typing n.


Do some magic with vim. Learn about vim filters if you haven't already by running :help filter inside of a vim session. Once you understand vim filters, start using them to create and edit notes. For example, type a note inside of vim. Highlight the text you just wrote in visual mode. Now type !notes add foo to create a new note named foo with the contents you had highlighted.

Want to write notes about super secret stuff that needs to be secure? It's incredibly easy to use vim + gnupg.vim to create and edit encrypted notes. Just create a note with a .gpg extension and the plugin will pick it up.

    notes add super-secret-stuff.gpg

Vim should open up a bottom window where you can enter GPG Recipients (via ID, email, name, etc.)i to encrypt the note for. You can use your own key here, and on save, the note will always be encrypted to disk. The gnupg.vim also ensures that vim does not write plaintext swap files to disk when editing gpg encrypted files.

Go forth and secure your notes!


  • William Wolf <>

  • Naveed Massjouni <>


William Wolf has dedicated the work to the Commons by waiving all of his or her rights to the work worldwide under copyright law and all related or neighboring legal rights he or she had in the work, to the extent allowable by law.

Works under CC0 do not require attribution. When citing the work, you should not imply endorsement by the author.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 500:

Unknown directive: =GPG