{"id":16610116,"url":"https://github.com/agorf/jot","last_synced_at":"2026-01-24T17:14:43.637Z","repository":{"id":136981420,"uuid":"259481359","full_name":"agorf/jot","owner":"agorf","description":"Command-line note-taking for minimalists","archived":false,"fork":false,"pushed_at":"2020-05-07T22:06:08.000Z","size":77,"stargazers_count":26,"open_issues_count":1,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-12T01:30:55.707Z","etag":null,"topics":["bash","cli","command-line","journal","minimal","note-taking","notes","plaintext","script","terminal-based","text-editor"],"latest_commit_sha":null,"homepage":"","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/agorf.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","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":"2020-04-27T23:34:14.000Z","updated_at":"2023-06-14T15:59:58.000Z","dependencies_parsed_at":"2023-03-22T12:17:13.177Z","dependency_job_id":null,"html_url":"https://github.com/agorf/jot","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agorf%2Fjot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agorf%2Fjot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agorf%2Fjot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agorf%2Fjot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agorf","download_url":"https://codeload.github.com/agorf/jot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238856081,"owners_count":19542141,"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":["bash","cli","command-line","journal","minimal","note-taking","notes","plaintext","script","terminal-based","text-editor"],"created_at":"2024-10-12T01:29:28.280Z","updated_at":"2025-10-29T17:30:51.079Z","avatar_url":"https://github.com/agorf.png","language":"Shell","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"# jot\n\n![](https://img.shields.io/github/v/tag/agorf/jot?label=version\u0026sort=semver)\n\n**jot** is a minimal, command-line note-taking program written in [Bash][].\n\n[Bash]: https://en.wikipedia.org/wiki/Bash_(Unix_shell)\n\nIt integrates seamlessly with your text editor and terminal and supports the minimum number of features, getting out of your way.\n\n## Design goals\n\n- [Small source size][source] (~250 [LOC][]: `grep -v '^#' jot | grep -v '^$' | wc -l`)\n- Easy [installation](#installation)\n- Plain text [note files](#notes) edited with a [text editor](#jot_editor)\n- Few [commands](#commands) with sensible defaults and aliases for less typing\n- Seamless integration with external programs through [custom commands](#custom-commands)\n- Extensibility and automation with custom [command hooks](#command-hooks)\n\n[source]: https://raw.githubusercontent.com/agorf/jot/master/jot\n[LOC]: https://en.wikipedia.org/wiki/Source_lines_of_code\n\nCheck out some [usage examples](#usage-examples).\n\n## Installation\n\n```shell\nwget -qO - 'https://raw.githubusercontent.com/agorf/jot/master/jot' | sudo tee /usr/local/bin/jot \u003e/dev/null\n```\n\nIf [wget][] is not available in your system, you can use [curl][]:\n\n[wget]: https://www.gnu.org/software/wget/\n[curl]: https://curl.haxx.se/\n\n```shell\ncurl -sS 'https://raw.githubusercontent.com/agorf/jot/master/jot' | sudo tee /usr/local/bin/jot \u003e/dev/null\n```\n\nFinally, make jot executable:\n\n```shell\nsudo chmod +x /usr/local/bin/jot\n```\n\n## Notes\n\nNotes are plain text files:\n\n- With a `YYYY-MM-DD` filename\n- A [`$JOT_EXT`](#jot_ext) extension\n- Kept under [`$JOT_HOME`](#jot_home)\n\n## Dates\n\n[Commands](#commands) accept _one or more_ dates and map them to note file names.\n\nFor example, if:\n\n- Today is the 15th of April, 2020\n- [`$JOT_HOME`](#jot_home) is `/home/agorf/jot/`\n- [`$JOT_EXT`](#jot_ext) is `txt`\n\nThen `today` is mapped to `/home/agorf/jot/2020-04-15.txt`\n\nThe following date aliases are supported:\n\n### `today`\n\nAlias: `td`\n\nSelf-explanatory.\n\nThis is the default date if you don't provide one.\n\n### `yesterday`\n\nAlias: `yd`\n\nSelf-explanatory.\n\n### `tomorrow`\n\nAlias: `tm`\n\nSelf-explanatory.\n\n### `prev`\n\nPrevious day with notes.\n\n### `pwd`\n\nPrevious working day.\n\nIt returns previous Friday's date when ran on Saturday, Sunday or Monday.\n\n### `nwd`\n\nNext working day.\n\nIt returns next Monday's date when ran on Friday, Saturday or Sunday.\n\n### `all`\n\nTargets all dates.\n\nThis makes it possible to execute custom commands targeting all note files.\n\nFor example, the following lists all note files:\n\n```shell\njot ls -l -- all\n```\n\n### Custom dates\n\nAny date not matching the above is passed as the value of the `--date` option to the system's `date` command (`man 1 date`).\n\nExample: `2020-04-15` for the 15th of April, 2020\n\nExample: `\"3 days ago\"`\n\nExample: `\"1 day\"` (ahead)\n\n### `dir`\n\nThis is not a date and does not map to note files. It can be used to issue commands against the `$JOT_HOME` directory.\n\nFor example, the following lists all `$JOT_HOME` directory contents:\n\n```shell\njot ls -l -- dir\n```\n\nContrast this with the following which lists all note files:\n\n```shell\njot ls -l -- all\n```\n\nAnd this which lists only today's note file:\n\n```shell\njot ls -l\n```\n\n## Commands\n\n### `edit`\n\nAlias: `e`\n\nEdit note file with [`$JOT_EDITOR`](#jot_editor)\n\nThis is the default if you don't provide one.\n\nExamples:\n\n```shell\njot edit today\njot e td\njot e\njot e yd\njot e yd td\njot e td tm\njot e all\n```\n\n### `copy`\n\nAlias: `c`\n\nCopy note file contents to the clipboard with [`$JOT_COPY`](#jot_copy)\n\nLines beginning with `#` are considered comments and are not copied. This can be used to keep note lines private when copy-pasting.\n\nExamples:\n\n```shell\njot copy today\njot c td\njot c\njot c yd\n```\n\n### `list`\n\nAlias: `l`\n\nList all note files in ascending date order (most recent, last)\n\nFor each file, the following is displayed:\n\n- Optional `\u003e` marker to signify today's note file\n- Date\n- Number of lines\n- Path\n\nExample output (truncated):\n\n```\n  Fri, 24 Apr 2020 ( 7) /home/agorf/jot/2020-04-24.txt\n  Mon, 27 Apr 2020 ( 3) /home/agorf/jot/2020-04-27.txt\n  Tue, 28 Apr 2020 ( 8) /home/agorf/jot/2020-04-28.txt\n  Wed, 29 Apr 2020 ( 8) /home/agorf/jot/2020-04-29.txt\n  Thu, 30 Apr 2020 ( 8) /home/agorf/jot/2020-04-30.txt\n\u003e Mon, 04 May 2020 ( 7) /home/agorf/jot/2020-05-04.txt\n  Tue, 05 May 2020 ( 4) /home/agorf/jot/2020-05-05.txt\n```\n\n### `help`\n\nAliases: `-h`, `--help`\n\nPrint usage help text.\n\n### `version`\n\nShow jot version.\n\n### `update`\n\nUpdate jot to latest version.\n\nNeeds `wget` or `curl` to be installed.\n\n### Custom commands\n\nIf the command is not one of the above, jot will execute it, passing to it as arguments any dates after `--` mapped to note file names.\n\nThis makes it possible to call arbitrary commands with note files!\n\nFor example, to delete yesterday's and tomorrow's note files:\n\n```shell\njot rm -- yd tm\n```\n\nTo ask for confirmation before deleting:\n\n```shell\njot rm -i -- yd tm\n```\n\nCheck out the [usage examples](#usage-examples).\n\n## Command hooks\n\nThe [edit](#edit) and [custom commands](#custom-commands) support \"pre\" and \"post\" hooks with `$JOT_HOOKS/pre` and `$JOT_HOOKS/post` respectively. Hooks are custom scripts marked as executable (`chmod +x`) that are executed before and/or after the command.\n\nFor example, the execution order for the [edit command](#edit) is:\n\n- `$JOT_HOOKS/pre`\n- `edit` command\n- `$JOT_HOOKS/post`\n\nThe following `post` hook adds changes to a [Git][] repository and pushes them to the remote, so that note files are backed up and synchronized:\n\n[Git]: https://git-scm.com/\n\n```shell\n# Place this under $JOT_HOOKS/post and make it executable with chmod +x\n\n[[ -z \"$(git status -s)\" ]] \u0026\u0026 exit\n\ngit add --all\ngit commit -m \"$(date)\"\ngit push\n```\n\n## Environment variables\n\nThe following environment variables are supported:\n\n### `JOT_HOME`\n\nDefault: `$HOME/jot`\n\nWhere note files are stored.\n\n### `JOT_HOOKS`\n\nDefault: `$JOT_HOME/hooks`\n\nWhere [hook scripts](#command-hooks) are stored.\n\n### `JOT_EDITOR`\n\nDefault: `$EDITOR`\n\nText editor to edit note files with.\n\n### `JOT_EDITOR_OPTS`\n\nDefault: (empty)\n\nOptions passed to the [`$JOT_EDITOR`](#jot_editor) command.\n\nHere's what I use for [Vim][]:\n\n[Vim]: https://www.vim.org/\n\n```\nexport EDITOR=vim\nexport JOT_EDITOR_OPTS='\"+normal G\" -O'\n```\n\nThis ensures each file is opened in a vertical split window and the cursor is placed at the end of the file.\n\n### `JOT_COPY`\n\nDefault: (none)\n\nNote file paths will be passed as parameters to this command to be copied to the clipboard.\n\njot will auto-detect the existence of the following X selection manipulation programs (in this order):\n\n- [xclip](https://github.com/astrand/xclip)\n- [xsel](http://www.vergenet.net/~conrad/software/xsel/)\n- [xcut](http://xcut.sourceforge.net/)\n- [sselp](http://tools.suckless.org/x/sselp/)\n\n### `JOT_DATE_FMT`\n\nDefault: `%a, %d %b %Y`\n\nExample: Wed, 15 Apr 2020\n\nHow note file dates are displayed with the [`list`](#l-list) command.\n\n### `JOT_EXT`\n\nDefault: `txt`\n\nFile extension used for note files.\n\n## Usage examples\n\nEdit today's notes:\n\n```shell\njot edit today\n```\n\n`edit` is aliased as `e` and `today` as `td`, so the following is equivalent:\n\n```shell\njot e td\n```\n\nSince `edit` and `today` are the defaults, you can simply execute `jot` instead:\n\n```shell\njot\n```\n\nEdit yesterday's (`yd` or `yesterday`) and today's notes:\n\n```shell\njot e yd td\n```\n\nEdit all notes:\n\n```shell\njot e all\n```\n\nCopy today's notes to the clipboard:\n\n```shell\njot copy today\n```\n\nShortened:\n\n```shell\njot c td\n```\n\nSince `today` is the default:\n\n```shell\njot c\n```\n\nList all notes:\n\n```shell\njot list\n```\n\nShortened:\n\n```shell\njot l\n```\n\nRemove tomorrow's notes, asking for confirmation:\n\n```shell\njot rm -iv -- tm\n```\n\nOpen today's notes with `less` pager:\n\n```shell\njot less -- td\n```\n\nSince today is the default:\n\n```shell\njot less\n```\n\nShow file information for today's notes:\n\n```shell\njot ls -lh\n```\n\nConcatenate yesterday's and today's notes:\n\n```shell\njot cat -- yd td\n```\n\nSearch all notes for `@agorf`, colorizing matches:\n\n```shell\njot grep --color @agorf -- all\n```\n\nDisplay number of lines for all notes:\n\n```shell\njot wc -l -- all\n```\n\nDisplay [Git][] directory status in `$JOT_HOME`:\n\n```shell\njot git status -- dir\n```\n\n## Acknowledgements\n\nI was inspired to start working on jot from [iridakos][] who wrote [stup][].\n\n[iridakos]: https://iridakos.com/\n[stup]: https://github.com/iridakos/stup\n\n## License\n\n[The MIT License][]\n\n[The MIT License]: https://github.com/agorf/jot/blob/master/LICENSE.txt\n\n## Author\n\nAngelos Orfanakos, \u003chttps://angelos.dev\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagorf%2Fjot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagorf%2Fjot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagorf%2Fjot/lists"}