{"id":13587840,"url":"https://github.com/pimterry/notes","last_synced_at":"2025-05-15T23:04:49.120Z","repository":{"id":40660115,"uuid":"75203277","full_name":"pimterry/notes","owner":"pimterry","description":":pencil: Simple delightful note taking, with more unix and less lock-in.","archived":false,"fork":false,"pushed_at":"2024-01-05T19:20:20.000Z","size":939,"stargazers_count":1303,"open_issues_count":14,"forks_count":81,"subscribers_count":24,"default_branch":"master","last_synced_at":"2025-04-08T10:17:43.669Z","etag":null,"topics":["markdown","note-taking","notes","productivity","shell-script","sync","unix","zsh"],"latest_commit_sha":null,"homepage":"https://github.com/pimterry/notes","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pimterry.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-11-30T16:04:48.000Z","updated_at":"2025-04-07T04:56:29.000Z","dependencies_parsed_at":"2025-03-11T03:33:25.835Z","dependency_job_id":"6de7d930-eaea-4738-9358-07095a5e263c","html_url":"https://github.com/pimterry/notes","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pimterry%2Fnotes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pimterry%2Fnotes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pimterry%2Fnotes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pimterry%2Fnotes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pimterry","download_url":"https://codeload.github.com/pimterry/notes/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254436944,"owners_count":22070946,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["markdown","note-taking","notes","productivity","shell-script","sync","unix","zsh"],"created_at":"2024-08-01T15:06:23.145Z","updated_at":"2025-05-15T23:04:49.092Z","avatar_url":"https://github.com/pimterry.png","language":"Shell","readme":"# notes [![Build Status](https://github.com/pimterry/notes/workflows/CI/badge.svg)](https://github.com/pimterry/notes/actions)\nSimple delightful note taking, with none of the lock-in.\n\n[![Asciicast demo](asciicast.gif)](https://asciinema.org/a/2pmdb9vyv71skgwx4r7mlnea8?speed=2\u0026t=1\u0026autoplay=1)\n\nThis 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.\n\n## Why do I want this?\n\nYou 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.\n\nYou want to take notes.\n\nYou 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.\n\nInstead, 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.\n\n**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.**\n\nThis 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 \u0026mdash; there's no shortage of simple file browsers and text editors that'll get the job done on any platform you like.\n\n## How do I install this?\n\n### Automatic:\n\n```bash\ncurl -Ls https://raw.githubusercontent.com/pimterry/notes/latest-release/install.sh | sudo bash\n```\nThis will install `notes`, a default configuration, a man page, and bash completion if possible.\n\n```bash\ncurl -Ls https://raw.githubusercontent.com/pimterry/notes/latest-release/install.sh | PREFIX=$HOME bash\n```\nFor non-root installation(user directory).\n\n### Manual:\n\nDownload `notes`, `chmod +x`, put it in your `$path`. This will probably do it:\n\n```bash\ncurl https://raw.githubusercontent.com/pimterry/notes/latest-release/notes \u003e /usr/local/bin/notes \u0026\u0026 chmod +x /usr/local/bin/notes\n```\n\n#### Installing auto completion\n\n`notes` includes auto completion, to let you tab-complete commands and your note names. This requires Bash \u003e 4.0 and [bash-completion](https://github.com/scop/bash-completion), Zsh, or Fish-shell to be installed - it's probably available from your friendly local package manager.\n\nTo 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:\n\n    pkg-config --variable=completionsdir bash-completion\n\nInstalling the completions might be as follows:\n\n**Bash**\n\n```bash\ncurl https://raw.githubusercontent.com/pimterry/notes/latest-release/notes.bash_completion \u003e /usr/share/bash-completion/completions/notes\n```\n\n**Zsh**\n\nOn *buntu based distros and OSX:\n```bash\ncurl -L https://raw.githubusercontent.com/pimterry/notes/latest-release/_notes \u003e /usr/local/share/zsh/site-functions/_notes\n```\n\nOn other Unix distros:\n\n```bash\ncurl -L https://raw.githubusercontent.com/pimterry/notes/latest-release/_notes \u003e /usr/share/zsh/site-functions/_notes\n```\n**Fish**\n\n```fish\ncurl -L https://raw.githubusercontent.com/pimterry/notes/latest-release/notes.fish \u003e ~/.config/fish/completions/notes.fish\n```\n\nYou'll need to open a new shell for this to take effect.\n\n## What if I want to uninstall this?\nIf you used the automated install script to install notes, you can uninstall it the same way, by running:\n```bash\ncurl -L https://raw.githubusercontent.com/pimterry/notes/latest-release/install.sh | bash -s -- uninstall\n```\n\n## How do I configure this?\n\nBy 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?](#how-do-i-configure-this) for more details.\n\nTo 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.\n\nThere 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](config)) that you can copy if you like.\n\n### What are the configuration options?\n\n* `QUICKNOTE_FORMAT` changes the way that quicknotes are generated. The string formatted using the `date` command.\n* `NOTES_EXT` changes the default extension that notes are saved with.\n* `TEMPLATES_DIR` changes the directory in which templates are stored.\n* `NOTES_DIRECTORY` changes the directory in which notes are stored.\n* `EDITOR` can also be overriden here, for `notes` only.\n* `POST_COMMAND` sets the command to run after any modification command (e.g. `open`, `mv`, ...) succeeds\n\n\n## How do I use it?\n\n### `notes new [-t \u003ctemplate-name\u003e] \u003cnote-name\u003e`\n\nOpens 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`.\n\nIf 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.\n\nIf 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\").\n\n### `notes find \u003cpart-of-a-note-name\u003e`\n\nSearches 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`.\n\n### `notes grep \u003cpart-of-some-note-content\u003e`\n\nSearches all note content for the given string and returns all the matches. Shorthand alias also available with `notes g`.\n\n### `notes search \u003cpart-of-a-note-name-or-note-content\u003e`\n\nSearches all note content and note filenames for the given string and returns all the matches. Shorthand alias also available with `notes s`.\n\n### `notes ls \u003cdirectory\u003e`\n\nLists 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).\n\n### `notes open`\n\nOpens your notes folder in your default configured file explorer. Shorthand alias also available with `notes o`.\n\n### `notes open \u003cnote-name\u003e`\n\nOpens 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`.\n\nIf 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`).\n\n### `notes append \u003cnote-name\u003e [message]`\n\nAppends `message` to the `note-name` note. If this note does not exist, a new note of \u003cnote-name\u003e will be created. This command also accepts stdin via piping. An example would be `echo \"hello\" | notes append \u003cnote-name\u003e` Shorthand alias also available with `notes a`.\n\n### `notes mv \u003cnote-name\u003e \u003cdestination\u003e|\u003cdirectory\u003e`\n\nRenames 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.\n\n### `notes rm [-r | --recursive] \u003cnote-name\u003e`\n\nRemoves the given note if it exists. If `-r` or `--recursive` is given, deletes the folders/notes recursively.\n\n### `notes cat \u003cnote-name\u003e`\nDisplays the note. Shorthand alias also available with `notes c`.\n\n### `notes grep/find \u003cpattern\u003e | notes open`\n\nCombine these together! This opens each matching note in your `$EDITOR` in turn.\n\n### `notes realpath [note-name]`\n\nDisplays the path to the note name, if provided. Displays the root path to all notes otherwise.\n\n## Tell me of the future\n\nAll the above works. Here's what's coming next:\n\n- [ ] More interesting and nicer looking file/grep search result formatting, perhaps only when not piping? (https://github.com/pimterry/notes/issues/27)\n- [ ] Make the file extension optional (https://github.com/pimterry/notes/issues/24)\n- [ ] Interactive mode? `notes` could open a scrollable list of notes, open your editor when you pick one, and reappear after you close it. (https://github.com/pimterry/notes/issues/17)\n- [ ] Tree view (https://github.com/pimterry/notes/issues/26)\n- [ ] 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`? (https://github.com/pimterry/notes/issues/22)\n- [ ] Version control - probably by finding an easy (optional) way to integrate this automatically with Git (https://github.com/pimterry/notes/issues/12)\n\n## I want to help\n\nGreat! 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.\n\nRemember 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.\n\nIf you want to get the code locally you'll need to:\n\n```bash\ngit clone \u003cyour fork\u003e\ngit submodule update --init --recursive\n./test.sh # Check the tests work before you make any changes\n```\n\nIf you install [`entr`](http://entrproject.org/) you can also run `./dev.sh`, which will watch all files within the project directory, and rerun tests any time they change.\n\nIf you submit a PR, please make sure it:\n\n* Doesn't break any existing tests\n* Adds new tests, if appropriate\n* Adds new documentation, if appropriate\n\n### Release process\n\nTo build a new release of `notes`:\n\n* `export NEW_VERSION=\"X.Y.Z\"` (replacing X.Y.Z with the appropriate new version)\n* Run:\n    ```\n    # Update the version number in the source\n    sed -i -e \"s/notes_version=.*/notes_version=\\\"$NEW_VERSION\\\"/g\" notes\n\n    # Commit, tag \u0026 push the new version\n    git add notes\n    git commit -m $NEW_VERSION\n    git tag $NEW_VERSION\n    git push origin master --tags\n\n    # Mark this version as the latest release\n    git checkout -B latest-release\n    git push --force origin latest-release\n    git checkout -\n    ```\n","funding_links":[],"categories":["Shell"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpimterry%2Fnotes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpimterry%2Fnotes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpimterry%2Fnotes/lists"}