notes

package module
v1.0.8 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 11, 2026 License: BSD-3-Clause Imports: 23 Imported by: 0

README

notes

A CLI tool for managing Markdown notes in the terminal. Organize notes by category, tag them, search with fuzzy matching, and optionally back everything up with Git.

Installation

Download a binary from the release page, or build from source (Go 1.26+):

go install github.com/naterator/notes/cmd/notes@latest

Quick Start

# Create a note (category is required, tags are optional)
notes new blog how-to-handle-files golang,file

# List all notes
notes ls -o

# Open notes in your editor
notes ls -e

# Search notes (supports fuzzy matching)
notes find "search query"

# Save to Git
notes save

Running notes with no arguments shows a one-line summary of all notes.

Commands

Command Alias Description
new <category> <file> [tags] Create a new note
list ls List notes (default: full paths)
find <query> Search notes by content
edit <category> <file> Open a note in your editor
save Commit (and push) notes via Git
categories cats List all categories
tags [category] List all tags
move <category> <file> <new-category> Move a note to a different category
rm <category> <file> Remove a note
config [key] Show configuration
selfupdate Update to latest release
Key Flags
  • list: --full/-f, --oneline/-o, --relative/-r, --edit/-e, --category/-c, --tag/-t, --sort/-s, --json
  • find: --full/-f, --relative/-r, --edit/-e, --sort/-s, --topone/-1, --json
  • save: --message/-m
  • selfupdate: --dry/-d
  • Global: --no-color, --color-always/-A

Sort options: created (default), modified, filename, category.

For list and find, output mode flags such as --json, --full, --edit, and --relative are mutually exclusive. --json always bypasses the pager so it is safe for scripting.

Note Format

Notes are Markdown files organized in category directories under the notes home:

<HOME>/
├── blog/
│   ├── how-to-handle-files.md
│   └── nested-category/
│       └── another-note.md
└── personal/
    └── todo.md

Each note contains a title and metadata:

# How to handle files in Go
- Category: blog
- Tags: golang, file
- Created: 2018-10-28T07:19:27+09:00

Body text here.

Metadata can be hidden in HTML comments (<!-- ... -->). See notes new --help for details.

Templates

Place a .template.md file in a category directory or at the home root. It will be automatically inserted when creating notes with notes new. Category-level templates take priority over root templates.

If the template starts with -->, metadata will be automatically wrapped in HTML comments.

Configuration

Variable Default Description
$NOTES_HOME ~/.local/share/notes Notes home directory
$NOTES_EDITOR $EDITOR Editor command (e.g. "vim -g")
$NOTES_GIT git Git executable path
$NOTES_PAGER less -R -F -X Pager for long output
$NOTES_SORT_BY created Default sort order (created, modified, filename, category)

Set any $NOTES_* variable to empty string to disable that integration.

View current config with notes config, or query a single value with keys such as home, git, editor, pager, and sort_by.

External Subcommands

Like Git, unknown subcommands are delegated to notes-<cmd> executables on your $PATH. All arguments are forwarded.

Shell Completions

zsh: Copy completions/zsh/_notes to a directory in your $fpath.

bash: Copy completions/bash/notes to your completions directory, or add to .bashrc: eval "$(notes --completion-script-bash)"

fish: Copy completions/fish/notes.fish to ~/.config/fish/completions/.

Tips

# Open last-modified note
vim "$(notes ls --sort modified | head -1)"

# Interactive filter with fzf
notes ls | fzf | xargs -o vim

# Move a note to a different category
notes move blog my-note.md personal

# Edit a specific note
notes edit blog my-note.md

# Remove a note
notes rm blog old-draft.md

# JSON output for scripting
notes ls --json | jq '.[].title'

# Force colors in pipes
notes -A ls --full | less -R

Go Library

This package can be used as a Go library. See the API documentation.

License

BSD 3-Clause

Documentation

Overview

Package notes is a library which consists notes command.

https://github.com/naterator/notes/tree/master/cmd/notes

This library is for using notes command programmatically from Go program. It consists structs which represent each subcommands.

1. Create Config instance with NewConfig 2. Create an instance of subcommand you want to run with config 3. Run it with .Do() method. It will return an error if some error occurs

import (
	"bytes"
	"fmt"
	"github.com/naterator/notes"
	"os"
	"strings"
)

var buf bytes.Buffer

// Create user configuration
cfg, err := notes.NewConfig()
if err != nil {
	panic(err)
}

// Prepare `notes list` command
cmd := &notes.ListCmd{
	Config: cfg,
	Relative: true,
	Out: &buf
}

// Runs the command
if err := cmd.Do(); err != nil {
	fmt.Fprintln(os.Stdout, err)
}

paths := strings.Split(strings.Trim(buf.String(), "\n"), "\n")
fmt.Println("Note paths:", paths)

For usage of `notes` command, please read README of the repository.

https://github.com/naterator/notes/blob/master/README.md

Example
package main

import (
	"os"
	"path/filepath"

	"github.com/fatih/color"
	"github.com/naterator/notes"
)

func main() {
	color.NoColor = true

	cwd, err := os.Getwd()
	if err != nil {
		panic(err)
	}

	cfg := &notes.Config{
		HomePath: filepath.Join(cwd, "example", "notes"),
	}

	cmd := notes.ListCmd{
		Config:  cfg,
		Oneline: true,
		Out:     os.Stdout,
	}

	// Shows oneline notes (relative file path, category, tags, title)
	if err := cmd.Do(); err != nil {
		panic(err)
	}
}
Output:
blog/daily/dialy-2018-11-20.md                         dialy-2018-11-20
blog/daily/dialy-2018-11-18.md             notes       dialy-2018-11-18
memo/tasks.md                                          My tasks
memo/notes-urls.md                         notes       URLs for notes
blog/tech/introduction-to-notes-command.md notes       introduction-to-notes-command
blog/tech/how-to-handle-files.md           golang,file How to hanle files in Go

Index

Examples

Constants

This section is empty.

Variables

View Source
var Version = "1.0.8"

Version is the version string of notes command. It conforms to semantic versioning

Functions

This section is empty.

Types

type Categories

type Categories map[string]*Category

Categories is a map from category name to Category instance

func CollectCategories

func CollectCategories(cfg *Config, mode CategoryCollectMode) (Categories, error)

CollectCategories collects all categories under home by default. The behavior of collecting categories can be customized with mode parameter. Default mode value is 0 (nothing specified).

func (Categories) Names

func (cats Categories) Names() []string

Names returns all category names as slice

func (Categories) Notes

func (cats Categories) Notes(cfg *Config) ([]*Note, error)

Notes returns all Note instances which belong to the categories

type CategoriesCmd

type CategoriesCmd struct {
	Config *Config
	// Out is a writer to write output of this command. Kind of stdout is expected
	Out io.Writer
	// contains filtered or unexported fields
}

CategoriesCmd represents `notes categories` command. Each public fields represent options of the command. Out field represents where this command should output.

func (*CategoriesCmd) Do

func (cmd *CategoriesCmd) Do() error

Do runs `notes categories` command and returns an error if occurs

type Category

type Category struct {
	// Path is a path to the category directory
	Path string
	// Name is a name of category
	Name string
	// NotePaths are paths to notes of the category
	NotePaths []string
}

Category represents a category directory which contains some notes

func (*Category) Notes

func (cat *Category) Notes(c *Config) ([]*Note, error)

Notes returns all Note instances which belong to the category

type CategoryCollectMode

type CategoryCollectMode uint

CategoryCollectMode customizes the behavior of how to collect categories

const (
	// OnlyFirstCategory is a flag to stop collecting categories earlier. If this flag is included
	// in mode parameter of CollectCategories(), it collects only first category and only first
	// note and stops finding anymore.
	OnlyFirstCategory CategoryCollectMode = 1 << iota
)

type Cmd

type Cmd interface {
	Do() error
}

Cmd is an interface for subcommands of notes command

func ParseCmd

func ParseCmd(args []string) (Cmd, error)

ParseCmd parses given arguments as command line options and returns corresponding subcommand instance. When no subcommand matches or argus contains invalid argument, it returns an error

type Config

type Config struct {
	// HomePath is a file path to directory of home of notes command. If $NOTES_HOME is set, it is used.
	// Otherwise, notes directory in XDG data directory is used. This directory is automatically created
	// when config is created
	HomePath string
	// GitPath is a file path to `git` executable. If $NOTES_GIT is set, it is used.
	// Otherwise, `git` is used by default. This is optional and can be empty. When empty, some command
	// and functionality which require Git don't work
	GitPath string
	// EditorCmd is a command of your favorite editor. If $NOTES_EDITOR is set, it is used. This value is
	// similar to $EDITOR environment variable and can contain command arguments like "vim -g". Otherwise,
	// this value will be empty. When empty, some functionality which requires an editor to open note doesn't
	// work
	EditorCmd string
	// PagerCmd is a command for paging output from 'list' subcommand. If $NOTES_PAGER is set, it is used.
	PagerCmd string
	// SortBy is the default sort order for list and find commands. If $NOTES_SORT_BY is set, it is used.
	// Valid values: "created", "modified", "filename", "category". Default is "created".
	SortBy string
}

Config represents user configuration of notes command

func NewConfig

func NewConfig() (*Config, error)

NewConfig creates a new Config instance by looking the user's environment. GitPath and EditorPath may be empty when proper configuration is not found. When home directory path cannot be located, this function returns an error

type ConfigCmd

type ConfigCmd struct {
	Config *Config
	// Name is a name of configuration. Must be one of "", "home", "git", "editor", "pager" or "sort_by"
	Name string
	// Out is a writer to write output of this command. Kind of stdout is expected
	Out io.Writer
	// contains filtered or unexported fields
}

ConfigCmd represents `notes config` command. Each public fields represent options of the command. Out field represents where this command should output.

func (*ConfigCmd) Do

func (cmd *ConfigCmd) Do() error

Do runs `notes config` command and returns an error if occurs

type EditCmd added in v1.0.6

type EditCmd struct {

	// Category is the category of the note to edit
	Category string
	// File is the filename of the note to edit
	File   string
	Config *Config
	// contains filtered or unexported fields
}

EditCmd represents `notes edit` command.

func (*EditCmd) Do added in v1.0.6

func (cmd *EditCmd) Do() error

Do runs `notes edit` command and returns an error if occurs

type ExternalCmd

type ExternalCmd struct {
	// ExePath is a path to executable of the external subcommand
	ExePath string
	// Args is arguments passed to external subcommand. Arguments specified to `notes` are forwarded
	Args []string
	// NotesPath is an executable path of the `notes` command. This is passed to the first argument of external subcommand
	NotesPath string
}

ExternalCmd represents user-defined subcommand

func NewExternalCmd

func NewExternalCmd(_ error, args []string) (*ExternalCmd, bool)

NewExternalCmd creates ExternalCmd instance from the raw CLI arguments. The parse error is accepted for compatibility with the ParseCmd caller, but detection is based on argv rather than kingpin's error string so external subcommands remain stable across parser message changes.

func (*ExternalCmd) Do

func (cmd *ExternalCmd) Do() error

Do invokes external subcommand with exec. If it did not exit successfully this function returns an error

type FindCmd

type FindCmd struct {
	Config *Config
	// Query is a query string for searching notes
	Query string
	// Relative is a flag equivalent to --relative
	Relative bool
	// SortBy is a string indicating how to sort the list. This value is equivalent to --sort option
	SortBy string
	// Edit is a flag equivalent to --edit
	Edit bool
	// TopOne is a flag equivalent to --topone
	TopOne bool
	// Full is a flag equivalent to --full
	Full bool
	// JSON is a flag equivalent to --json
	JSON bool
	// Out is a writer to write output of this command. Kind of stdout is expected
	Out io.Writer
	// contains filtered or unexported fields
}

FindCmd represents `notes find` command. Each public fields represent options of the command. Out field represents where this command should output.

func (*FindCmd) Do

func (cmd *FindCmd) Do() error

Do runs `notes find` command and returns an error if occurs

type Git

type Git struct {
	// contains filtered or unexported fields
}

Git represents Git command for specific repository

func NewGit

func NewGit(c *Config) *Git

NewGit creates Git instance from Config value. Home directory is assumed to be a root of Git repository

func (*Git) AddAll

func (git *Git) AddAll() error

AddAll runs `git add -A`

func (*Git) Command

func (git *Git) Command(subcmd string, args ...string) *exec.Cmd

Command returns exec.Command instance which runs given Git subcommand with given arguments

func (*Git) Commit

func (git *Git) Commit(msg string) error

Commit runs `git commit` with given message

func (*Git) Exec

func (git *Git) Exec(subcmd string, args ...string) (string, error)

Exec runs runs given Git subcommand with given arguments

func (*Git) Init

func (git *Git) Init() error

Init runs `git init` with no argument

func (*Git) Push

func (git *Git) Push(remote, branch string) error

Push pushes given branch of repository to the given remote

func (*Git) TrackingRemote

func (git *Git) TrackingRemote() (string, string, error)

TrackingRemote returns remote name branch name. It fails when current branch does not track any branch

type ListCmd

type ListCmd struct {
	Config *Config
	// Full is a flag equivalent to --full
	Full bool
	// Category is a regex string equivalent to --cateogry
	Category string
	// Tag is a regex string equivalent to --tag
	Tag string
	// Relative is a flag equivalent to --relative
	Relative bool
	// Oneline is a flag equivalent to --oneline
	Oneline bool
	// Tag is a string indicating how to sort the list. This value is equivalent to --sort option
	SortBy string
	// Edit is a flag equivalent to --edit
	Edit bool
	// JSON is a flag equivalent to --json
	JSON bool
	// Out is a writer to write output of this command. Kind of stdout is expected
	Out io.Writer
	// contains filtered or unexported fields
}

ListCmd represents `notes list` command. Each public fields represent options of the command Out field represents where this command should output.

func (*ListCmd) Do

func (cmd *ListCmd) Do() error

Do runs `notes list` command and returns an error if occurs

type MismatchCategoryError

type MismatchCategoryError struct {
	// contains filtered or unexported fields
}

MismatchCategoryError represents an error caused when a user specifies mismatched category

func (*MismatchCategoryError) Error

func (e *MismatchCategoryError) Error() string

func (*MismatchCategoryError) Is

func (e *MismatchCategoryError) Is(target error) bool

Is returns if given error is a MismatchCategoryError or not

type MoveCmd added in v1.0.6

type MoveCmd struct {

	// Category is the current category of the note
	Category string
	// File is the filename of the note
	File string
	// NewCategory is the destination category
	NewCategory string
	Config      *Config
	// contains filtered or unexported fields
}

MoveCmd represents `notes move` command.

func (*MoveCmd) Do added in v1.0.6

func (cmd *MoveCmd) Do() error

Do runs `notes move` command and returns an error if occurs

type NewCmd

type NewCmd struct {
	Config *Config
	// Category is a category name of the new note. This must be a name allowed for directory name
	Category string
	// Filename is a file name of the new note
	Filename string
	// Tags is a comma-separated string of tags of the new note
	Tags string
	// NoInline is a flag equivalent to --no-inline-input
	NoInline bool
	// NoEdit is a flag equivalent to --no-edit
	NoEdit bool
	// contains filtered or unexported fields
}

NewCmd represents `notes new` command. Each public fields represent options of the command

func (*NewCmd) Do

func (cmd *NewCmd) Do() error

Do runs `notes new` command and returns an error if occurs

type Note

type Note struct {
	// Config is a configuration of notes command which was created by NewConfig()
	Config *Config
	// Category is a category string. It must not be empty
	Category string
	// Tags is tags of note. It can be empty and cannot contain comma
	Tags []string
	// Created is a datetime when note was created
	Created time.Time
	// File is a file name of the note
	File string
	// Title is a title string of the note. When the note is not created yet, it may be empty
	Title string
}

Note represents a note stored on filesystem or will be created

func LoadNote

func LoadNote(path string, cfg *Config) (*Note, error)

LoadNote reads note file from given path, parses it and creates Note instance. When given file path does not exist or when the file does note contain mandatory metadata ('Category', 'Tags' and 'Created'), this function returns an error

func NewNote

func NewNote(cat, tags, file, title string, cfg *Config) (*Note, error)

NewNote creates a new note instance with given parameters and configuration. Category and file name cannot be empty. If given file name lacks file extension, it automatically adds ".md" to file name.

func (*Note) Create

func (note *Note) Create() error

Create creates a file of the note. When title is empty, file name omitting file extension is used for it. This function will fail when the file is already existing.

func (*Note) DirPath

func (note *Note) DirPath() string

DirPath returns the absolute category directory path of the note

func (*Note) FilePath

func (note *Note) FilePath() string

FilePath returns the absolute file path of the note

func (*Note) Open

func (note *Note) Open() error

Open opens the note using an editor command user set. When user did not set any editor command with $NOTES_EDITOR, this method fails. Otherwise, an editor process is spawned with argument of path to the note file

func (*Note) ReadBody

func (note *Note) ReadBody() (string, error)

ReadBody reads all body lines and returns it as string

func (*Note) ReadBodyLines

func (note *Note) ReadBodyLines(maxLines int) (string, int, error)

ReadBodyLines reads body of note until maxLines lines and returns it as string and number of lines as int

func (*Note) RelFilePath

func (note *Note) RelFilePath() string

RelFilePath returns the relative file path of the note from home directory

func (*Note) SearchableText

func (note *Note) SearchableText() (string, error)

SearchableText returns a text blob consisting of metadata and body for text search

func (*Note) TemplatePath

func (note *Note) TemplatePath() (string, bool)

TemplatePath resolves a path to template file of the note. If no template is found, it returns false as second return value

type PagerWriter

type PagerWriter struct {

	// Cmdline is a string of command line which was spawned
	Cmdline string
	// Err is an error instance which occurred while paging.
	Err error
	// contains filtered or unexported fields
}

PagerWriter is a wrapper of pager command to paging output to writer with pager command such as `less` or `more`. Starting process, writing input to process, waiting process finishes may cause an error. If one of them causes an error, later operations won't be performed. Instead, the prior error is returned.

func StartPagerWriter

func StartPagerWriter(pagerCmd string, stdout io.Writer) (*PagerWriter, error)

StartPagerWriter creates a new PagerWriter instance and spawns underlying pager process with given command. pagerCmd can contain options like "less -R". When the command cannot be parsed as shell arguments or starting underlying pager process fails, this function returns an error

func (*PagerWriter) Wait

func (pager *PagerWriter) Wait() error

Wait waits until underlying pager process finishes

func (*PagerWriter) Write

func (pager *PagerWriter) Write(p []byte) (int, error)

Write writes given payload to underlying pager process's stdin

type RmCmd added in v1.0.6

type RmCmd struct {

	// Category is the category of the note to remove
	Category string
	// File is the filename of the note to remove
	File   string
	Config *Config
	// contains filtered or unexported fields
}

RmCmd represents `notes rm` command.

func (*RmCmd) Do added in v1.0.6

func (cmd *RmCmd) Do() error

Do runs `notes rm` command and returns an error if occurs

type SaveCmd

type SaveCmd struct {
	Config *Config
	// Message is a message of Git commit which will be created to save notes. If this value is empty,
	// automatically generated message will be used.
	Message string
	// contains filtered or unexported fields
}

SaveCmd represents `notes save` command. Each public fields represent options of the command

func (*SaveCmd) Do

func (cmd *SaveCmd) Do() error

Do runs `notes save` command and returns an error if occurs

type SelfupdateCmd

type SelfupdateCmd struct {

	// Dry is a flag equivalent to --dry
	Dry bool
	// Slug is a "user/repo" string where releases are put. This field is useful when you forked
	// notes into your own repository.
	Slug string
	// Out is a writer to write output of this command. Kind of stdout is expected
	Out io.Writer
	// contains filtered or unexported fields
}

SelfupdateCmd represents `notes selfupdate` subcommand.

func (*SelfupdateCmd) Do

func (cmd *SelfupdateCmd) Do() error

Do method checks the newer version binary. If new version is available, it updates myself with the latest binary.

type TagsCmd

type TagsCmd struct {
	Config *Config
	// Category is a category name of tags. If this value is empty, tags of all categories will be output
	Category string
	// Out is a writer to write output of this command. Kind of stdout is expected
	Out io.Writer
	// contains filtered or unexported fields
}

TagsCmd represents `notes tags` command. Each public fields represent options of the command Out field represents where this command should output.

func (*TagsCmd) Do

func (cmd *TagsCmd) Do() error

Do runs `notes tags` command and returns an error if occurs

Directories

Path Synopsis
cmd
notes command
internal

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL