Create and manage notes.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Michał Góral 63cc4f014c For `notes ls` display a list of all files. 5 years ago
tests First test 5 years ago
LICENSE Added license 5 years ago
_notes Automatically manage git repository. 5 years ago
notes Missing executable 5 years ago For `notes ls` display a list of all files. 5 years ago
readme.adoc Automatically manage git repository. 5 years ago
tox.ini Updated pytest version 5 years ago


= Notes User Manual
:author: Michał Góral
:revnumber: 1.0
:toc: left
:toclevels: 3
:doctype: book
:sectnumlevels: 2
:icons: font

notes - create, edit, read and manage your personal notes as simple (or complex)
text files.

== Architecture

_notes_ manages text files grouped in projects, which are stored somewhere in
your filesystem. By default all notes' files are stored in `~/notes`.
directory. You can change the root directory of notes by setting `$NOTES_PATH`
environment variable.

Each project can have arbitrarily complex file/directory structure inside.
Default project is simply named *default*.

For example

.Projects structure example

some important note.adoc

== Creating notes

To create a new note, simply edit it:

$ notes edit note

This will create a new note in a default project and open it in a default
editor. If you want to create a note in a different project, type it before a
note name:

$ notes edit foo/note

NOTE: Notes are edited in a default editor configured via `$EDITOR` environment
variable. If it isn't set, _vi_ is used by default.

=== Archetypes

Notes are created from so called archetypes. Archetypes are per-project files
placed in _archetypes_ directory (a sibling to _projects_ one). Each note
inherits archetype's content and file extension. So for example, if archetype is
a markdown file (_foo.md_), then creating a new note via `$ notes edit foo/note`
will create a new file named **. this note can be accessed later either
by editing _note_ or _note.md_.

Archetype can have several markers, which are automatically replaced by some

.Archetype's markers
[.center, cols="^1m,^3", options="header"]
| Marker | Description

| {title}
| replaced by a note title (file name)

| {user}
| replaced by current user name

.Example archetype
# archetypes/

author: {user}
# {title}


== Displaying notes

`notes show <note>` displays notes. If project is not specified, a note from a
default project is displayed.

NOTE: Notes are displayed in a configured pager (`$PAGER` environment variable).
If `$PAGER` isn'te set, _less_ is used.
variable. If it isn't set, vi is used by default.

Notes can be compiled by setting *-c,--compile* option and a compilation command
can be set with *-C,--compile-cmd* option. When compiled, notes are opened
either by a web browser or an external program supplied with *-e,--external*

Compilation command accepts the following markers, which are replaced with
correct values for a current note:

.Compilation markers
[.center, cols="^1m,^3", options="header"]
| Marker | Description

| {note}
| note's absolute path

| {html}
| absolute path to the result of compilation (html file)

For example:

$ notes show foo/bar.adoc

$ notes show -c -C 'asciidoctor {note} -o -' foo/bar.adoc | lynx -stdin

$ notes show -e x-www-browser -c -C 'asciidoctor {note} -o {html}' foo/bar.adoc

If you don't want to open a note after compilation (for example you already have
it opened and will simply refresh the view after few edits), you can pass
*--only-compile* switch to `notes show` command.

== Browsing notes

There are two simple commands which allow you to browse your projects and notes:
`notes projects`, which displays all projects, and `notes ls <project name>`,
which displays notes in a given project. `notes ls` additionally accepts *-a*
switch, which will display absolute paths to notes in a given project:

.notes ls examples
$ notes projects

$ notes ls foo

$ notes ls -a foo

$ notes ls -a

== Removing notes

To remove a note, use `$notes rm <note>`.

== Integration with Git

If project is inside a Git repository, adding, editing and removing will be
automatically tracked by Git. You can later call `$ notes sync` to synchronize
(git pull and git push) it with a remote Git server.

You can also run any Git command inside a project's directory by using `notes
git <project> <command>`:

$ notes git foo status

notes will assist you when initializing a new Git repository. If you initialize
a new Git repository via `notes git <project> init`, notes will automatically
add and commit all notes in a selected project. This doesn't take effect when
reinitializing existing Git repositories.

== License

Copyright (C) 2017 {author}.

Notes 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

Notes 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. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with
Notes. If not, see