https://github.com/vdt/posce
A note-taking toolkit for your command line.
https://github.com/vdt/posce
Last synced: 18 days ago
JSON representation
A note-taking toolkit for your command line.
- Host: GitHub
- URL: https://github.com/vdt/posce
- Owner: vdt
- License: other
- Created: 2020-03-24T08:50:42.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2020-03-24T06:03:27.000Z (over 5 years ago)
- Last Synced: 2024-04-20T16:59:48.685Z (over 1 year ago)
- Homepage:
- Size: 156 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- Changelog: changes.md
- License: license.md
Awesome Lists containing this project
- awesome-cli-apps-in-a-csv - posce - A note-taking toolkit for your command line. (<a name="note-taking"></a>Note taking)
- awesome-cli-apps - posce - A note-taking toolkit for your command line. (<a name="note-taking"></a>Note taking)
README
Posce
=====
[][py]
[][pp]
[][is]
[][li]
**Posce** (pronounced *posh·ee*) is a note-taking toolkit for your command line. It takes a single directory of plaintext note files and lets you create, edit, manipulate, and organise them to your heart's content; all in a single unified interface.
- See [changes.md][ch] for a complete changelog.
- See [license.md][li] for licensing information.
Table of Contents
-----------------
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
- [Commands](#commands)
- [`clip NAME`](#clip-name)
- [`copy NAME DEST`](#copy-name-dest)
- [`drop NAME`](#drop-name)
- [`dump FILE [-l]`](#dump-file--l)
- [`edit NAME [-e]`](#edit-name--e)
- [`find TERM [-r]`](#find-term--r)
- [`list [GLOB] [-rs]`](#list-glob--rs)
- [`make NAME [-f]`](#make-name--f)
- [`move NAME DEST`](#move-name-dest)
- [`show NAME [-w]`](#show-name--w)
- [`wget NAME URL`](#wget-name-url)
- [F.A.Q.](#faq)
- [Contribution](#contribution)
Installation
------------
Posce required [Python 3.8][py] or higher. To install, you can:
- Run `pip install posce`, or
- Download and install the [latest release][re].
Configuration
-------------
Posce only requires you to set two environment variables:
~~~bash
# The path to your notes directory.
POSCE_DIR = "~/notes"
# The extension your note files use (no dot).
POSCE_EXT = "txt"
~~~
On macOS and Linux, these variables can be set in your shell profile script, most likely `$HOME/.profile`. On Windows, you can set them in the "Environment Variables" subscreen in System Properties (search "environment" in your Start Menu).
Usage
-----
Notes are always referred to by their pure name, no extension or filepath. In addition, notes and commands are disambiguated, which means you can write abbreviated versions and — if it's unambiguous — Posce will automatically expand them for you.
For example, if you have a directory that looks like this:
~~~text
- ~/notes
- alpha.txt
- bravo.txt
- charlie.txt
~~~
Then your notes will look like this:
~~~bash
$ posce list
alpha
bravo
charlie
$ posce show c
Charliiiiiiieeeeeee!
~~~
And you can abbreviate commands like this:
~~~bash
$ posce l
alpha
bravo
charlie
$ posce s c
Charliiiiiiieeeeeee!
~~~
I recommend aliasing `posce` to `p` for maximum brevity.
Commands
--------
### `clip NAME`
Copy the existing note `NAME` to the clipboard.
~~~bash
$ posce clip alpha
# Copy "alpha.txt" to clipboard.
~~~
### `copy NAME DEST`
Copy the existing note `NAME` to the new note `DEST`.
~~~bash
$ posce copy alpha delta
# Copy "alpha.txt" to new file "delta.txt".
~~~
### `drop NAME`
Move the existing note `NAME` to the system trash/recycle bin.
~~~bash
$ posce drop alpha
# Move "alpha.txt" to trash/recycle bin.
~~~
### `dump FILE [-l]`
Create a zip archive of the notes directory at `FILE`.
- `-l` `--level INT`: Compression level from `0` to `9` (default `5`).
~~~bash
$ posce dump notes.zip
# Create zip archive "notes.zip".
$ posce dump notes.zip --level 9
# Create "notes.zip" with maximum compression.
~~~
### `edit NAME [-e]`
Edit the existing note `NAME` in your default editor.
- `e` `--editor PROG`: Open the note in the program `PROG` instead.
~~~bash
$ posce edit alpha
# Open "alpha.txt" in default "txt" editor.
$ posce edit alpha --editor notepad
# Open "alpha.txt" in "notepad".
~~~
### `find TERM [-r]`
List all notes containing the substring or regular expression `TERM`.
- `r` `--regex`: Use search term as regex.
~~~bash
$ posce find "Charliiiiiiieeeeeee!"
charlie
$ posce find "Charli{7}e{7}!" --regex
charlie
~~~
### `list [GLOB] [-rs]`
List all notes with names matching `GLOB` (default `*`).
- `-r` `--reverse`: Reverse sorting order.
- `-s` `--sort (name|size)`: Sort notes by name or size.
~~~bash
$ posce list
alpha
bravo
charlie
$ posce list al*
alpha
$ posce list --reverse --sort name
charlie
bravo
alpha
~~~
### `make NAME [-f]`
Create the new empty note `NAME`.
- `-f` `--file FILE`: Copy the note's contents from a file.
~~~bash
$ posce make delta
# Create empty file "delta.txt" in notes directory.
$ posce make delta --file ~/temp.txt
# Create "delta.txt" with contents from "~/temp.txt".
~~~
### `move NAME DEST`
Move the existing note `NAME` to the new note `DEST`.
~~~bash
$ posce move alpha delta
# Move "alpha.txt" to "delta.txt".
~~~
### `show NAME [-w]`
Print the contents of the existing note `NAME`.
- `-w` `--wrap COLS`: Wrap text to this width.
~~~bash
$ posce show alpha
This is the note Alpha!
$ posce show bravo --wrap 40
This is the much longer note Bravo, and
will be wrapped across two lines.
~~~
### `wget NAME URL`
Download a URL into the existing note `NAME`.
~~~bash
$ posce wget alpha example.com
# Download "https://example.com" and write contents to "alpha.txt".
~~~
F.A.Q.
------
### Why use this instead of `ls`/`grep`/`wget`/etc?
Posce is *one* app using *one* system on *one* directory. It's a very focused app, and that focus gives it a level of stability and uniformity I enjoy. Also, by using a single notes directory, you can [use disambiguated names](#usage) and get incredible brevity when entering commands.
### Why environment variables? Why not a config file?
The last thing you or I need is *another* configuration file clogging up our home directories. Environment variables are simpler, lighter, and can be overriden much easier. Also, if Posce did use a config file, it would only have those two variables anyway!
### Why do I have to make a new note before editing it?
It makes the code simpler and more robust, it allows for disambiguation of names, and I just prefer that kind of explicit operation.
### Why can I only trash notes and not delete them?
I'm paranoid about data loss, which means Posce will *never, ever, under any circumstances* implement file deletion. If you want to delete your files, do it yourself.
Contribution
------------
Bugs, suggestions, and feature requests are welcome! Please add them to the [issue tracker][is] with an appropriate label.
[ch]: https://github.com/posce/posce/blob/master/changes.md
[is]: https://github.com/posce/posce/issues
[li]: https://github.com/posce/posce/blob/master/license.md
[re]: https://github.com/posce/posce/releases/latest
[pp]: https://pypi.org/project/posce/
[py]: https://python.org