{"id":17027898,"url":"https://github.com/sobjornstad/dreamdir","last_synced_at":"2025-04-12T12:07:40.036Z","repository":{"id":148978639,"uuid":"57424279","full_name":"sobjornstad/dreamdir","owner":"sobjornstad","description":"The Unix dream journal format","archived":false,"fork":false,"pushed_at":"2024-01-20T20:38:09.000Z","size":221,"stargazers_count":8,"open_issues_count":7,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-26T06:51:07.275Z","etag":null,"topics":["dream","journal","note-taking","notes","shell","unix"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sobjornstad.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","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}},"created_at":"2016-04-30T02:48:53.000Z","updated_at":"2024-01-20T20:37:18.000Z","dependencies_parsed_at":"2024-01-20T21:33:35.866Z","dependency_job_id":"fff07c31-0c53-49ad-964e-28cd18ef59fa","html_url":"https://github.com/sobjornstad/dreamdir","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sobjornstad%2Fdreamdir","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sobjornstad%2Fdreamdir/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sobjornstad%2Fdreamdir/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sobjornstad%2Fdreamdir/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sobjornstad","download_url":"https://codeload.github.com/sobjornstad/dreamdir/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248565061,"owners_count":21125416,"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":["dream","journal","note-taking","notes","shell","unix"],"created_at":"2024-10-14T07:51:11.367Z","updated_at":"2025-04-12T12:07:40.015Z","avatar_url":"https://github.com/sobjornstad.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"**Dreamdir** – the Unix dream journal format\n\nOverview\n========\n\n*Dreamdir* is a format for storing a dream journal inspired by the popular\n[Maildir](https://en.wikipedia.org/wiki/Maildir) mailbox format and the\n[RFC 2822](https://tools.ietf.org/html/rfc2822) email format itself.\n\n## Philosophy\n\nDreamdir follows the [Unix philosophy](https://en.wikipedia.org/wiki/Unix_philosophy),\nas follows:\n\n* All dreams are stored in plain text formatted in a consistent way.\n  The format is human-readable and is normally read and written directly.\n* Dreamdir is first and foremost a format, not an application.\n  Simple code designed to do one thing well is provided\n  to make working with the format easier.\n* In addition to the provided code,\n  standard Unix text-processing tools and simple scripts\n  can easily manipulate dreams stored in a Dreamdir.\n\n## Important factoids\n\nData format:\n\n* Each dream is stored in its own plain text file.\n* Each dream file begins with a list of data fields (called *headers*),\n  which can store things like the date, the names of people who appeared in the dream, and tags.\n* The remainder of the dream file is the text of your entry.\n\nApplication:\n\n* The `dr` script offers powerful and intuitive search functionality\n  and several other useful tools to create new dreams, combine tags, and so on.\n  It easily integrates with other Unix tools.\n* Example user scripts are provided for tasks like graphing day-to-day recall\n  and generating indexes. A small Python library is also available.\n* Free and open source:\n  the Dreamdir format itself and this documentation are public domain,\n  and all code is provided under the MIT license (see the LICENSE file for details).\n\n\nDreamdir format\n===============\n\nSpecification -- Requirements\n-----------------------------\n\nDreamdir scripts are permitted to assume that the rules specified in this\nsection are followed, so you should definitely follow them. Conformance to the\nmost basic rules can be checked with the `dr check-validity` command.\n\nThe easiest way to learn the format is to look at an example dream file (people’s names are censored here but are written out in full in the actual file format):\n\n    Id:\t00952\n    Date:\t2015-11-19\n    Time:\t6:02\n    People:\tM., Md., T.\n    Places:\tWal-Mart\n    Tags:\tstore, radio, cottage, enchantment, police\n\n    I'm in some kind of large store which sells food, perhaps a supermarket or\n    Wal-Mart or something of that nature.  I have found two small individual\n    packages of applesauce and eaten them, and I now am wondering if that's\n    okay and how I will pay for them.  I'm with M here.  Near the back of the\n    store, there's a small table with a store walkie-talkie on it.  I pick this\n    up, and though I'm not sure exactly how this happened, I soon get into a\n    heated argument with a store manager over the radio.  It starts off being\n    about the applesauce in some fashion, but it soon turns into a tirade about\n    consumerism and the advertising in their store.  Eventually the manager\n    gets so pissed at what I'm saying (though I wasn't *trying* to upset him, I\n    also wasn't trying to be careful) that he tells me he's going to have the\n    police come and arrest me.  I don't question that he has the authority to\n    do this, and so M and I decide that we should leave quickly before they\n    arrive.  We head out of the store; as a final \"screw you\" I grab a Snickers\n    bar that's sitting on a table as I leave.\n\n    [remainder of dream clipped]\n\nAt the top you see the *headers*.\nEach header is separated from its *values* by a colon followed by a hard tab.\n(The requirement of a tab makes commands like `grep` easier to use,\n    since a colon will not be followed by a tab in running text.)\nFor headers that can take multiple values,\n    such as People, Places, and Tags,\n    individual values are separated by a comma and a space.\n\nTwo headers are **required** to form a valid dream file:\n    the *Id* number and the *Date*.\nAll other headers are optional.\nThere are no rules about what constitutes a valid header name\n    (except that of course it cannot contain a colon followed by a hard tab),\n    and it is fine for some dreams\n    to not have a particular optional header at all.\nThe headers can come in any order.\nA blank line follows the headers.\n\nThe two required headers are fussier, as follows:\n\n* **Id**: Dreamdir uses fixed-width five-digit ID numbers,\n  beginning at `00001` and increasing for each dream up to `99999`.\n  (If you manage to record 100,000 dreams, updates to the program and a beer are on me!)\n* **Date**: Dreamdir scripts expect [ISO 8601](https://xkcd.com/1179/)-formatted\n  dates (YYYY-MM-DD).\n\nBeneath the headers, following a blank line, comes the text of the dream.\nAs long as you don’t begin any later line with a header\n    (i.e., a line containing a colon immediately followed by a hard tab),\n    you can do anything you like here,\n    though you may wish to look at the “Formatting guidelines” section, below.\n\n\nSpecification -- Suggestions\n----------------------------\n\n* **Emphasis**: Use `*single stars*` or `_underlines_` around the area to be emphasized.\n* **Commentary**: Place notes that are not actually part of the dream in `[square brackets]`. The commentary may continue over multiple lines.\n* **Verbatim quoting**: Place text that is directly quoted from some earlier form of notes (such as a notebook you scribbled in in bed) in `` `backticks` ``.\n* **Lucid sections**: If you lucid dream, you can place sections where you knew you were dreaming in `{curly braces}`. I also use the header `Lucid:\t1` to make it easier to find these dreams.\n\nEmphasis and verbatim quoting\n    are recognized by the syntax highlighting functionality.\nLucid sections and commentary are recognized by the word count scripts\n    (word counts can be split into “normal,” “lucid,” and “notes”).\n\nI use one physical line per paragraph\n    and [double-space between sentences](http://stevelosh.com/blog/2012/10/why-i-two-space/),\n    but I don’t see those conventions ever being expected by any code.\n\n\nSuggested headers\n-----------------\n\nAs mentioned earlier,\n    you can use any headers you like as long as you include the ID number and the date.\n    As a starting point, here are the ones I currently use:\n\n* **People**: Comma-separated list of waking-life people who appeared in the dream.\n* **Places**: Ditto for places with proper names and general geographic regions.\n* **Tags**: List of motifs, categories, and other elements that are useful to track across multiple dreams but don’t fit into other headers.\n* **Title**: A title...\n* **Time**: If I had a clock handy and remembered to write it down, the time at which I woke up from the dream.\n* **Lucid**: Included and with a value of 1 if the dream was lucid at any point.\n\n\nFile names and locations\n------------------------\n\nAll dreams are kept in the root of the dreamdir.\nA dream’s filename is its ID number with a `.dre` extension, e.g., `00592.dre`.\n\n    -rw-------  1 soren soren   623 Dec 14  2014 00001.dre\n    -rw-rw-r--  1 soren soren   210 Feb 14 19:00 00002.dre\n    [...]\n    -rw-------  1 soren soren  3075 Apr 28 21:25 01227.dre\n    -rw-------  1 soren soren  1600 Apr 27 13:21 01228.dre\n    -rw-rw-r--  1 soren soren     0 Apr 29 15:56 .dreamdir\n\nNote the `.dreamdir` file, which marks this directory as a Dreamdir.\nThe content is currently unimportant,\n    but scripts may check for this file to ensure they’re working in a dreamdir.\n\n`dr` uses the current directory as the dreamdir\n    if it contains that `.dreamdir` file.\nOtherwise, it checks the environment variable `DREAMDIR`\n    for a path and uses that location if it’s set to a valid dreamdir.\nIf neither of these locations are valid dreamdirs,\n    `dr` will exit without doing anything.\n\n\nInstallation / creating a Dreamdir\n==================================\n\nBegin by copying the `dr` script to somewhere on your system path.\n\nIf you want to use the `word-count` functionality,\n    which differs from the standard `wc` in that it ignores headers\n    and can count marked lucid and notes sections separately,\n    change into the `drwc` directory and run `make` (this requires `gcc`),\n    then install the compiled `drwc` binary to your system path as well.\n\nIf you want to use the ctags generation functionality,\n    make sure you have `python3` available on your PATH.\n\nFinally, create a directory for your dreamdir and use `touch .dreamdir`\n    to mark the directory as a dreamdir.\nYou should now be able to use `dr new` to create your first dream file.\n\nYou may also wish to set the environment variable `DREAMDIR`\n    to the path to your dreamdir;\n    this way you can run `dr` from anywhere in your filesystem.\n\nI keep my dreamdir under `git` control\n    to keep track of any revisions I make to headers and dreams\n    and as an extra backup against scripting and [PEBKAC][] errors.\n    You may wish to do likewise.\n\n[PEBKAC]: https://en.wikipedia.org/wiki/User_error#Acronyms_and_other_names\n\n\nInstalling on MacOS\n-------------------\n\n`dr` works great on MacOS,\n    but you will have to install newer versions of a couple of utilities.\nInstallation through [Homebrew][] is recommended.\nAfter following the steps above:\n\n    brew install bash python bats\n\nInstallation of `bats` is not required,\n    but it allows you to run `tests/test_dr`\n    to confirm you have all the right utilities\n    and your installation works correctly,\n    which may otherwise be difficult to do:\n\n    cd dreamdir\n    tests/test_dr\n\n[Homebrew]: https://brew.sh/\n\n\nDependencies\n------------\n\nUtilities needed by dr that are not part of POSIX:\n\n* `bash` 4.0+\n* `python3` (needed for `regenerate-tags`)\n\ndr tries to stick to POSIX standards,\n    but we have limited ability to test that we have done so\n    across multiple systems.\nIf something in `dr` doesn’t work right in your version of a POSIX utility,\n    or if a system in common use doesn’t comply with the relevant aspects\n    of a POSIX standard `dr` relies upon,\n    please submit a bug report.\n\n(dr also uses `seq`, `tac`, and `shuf` when available,\n    but includes slower, more memory-intensive fallback methods\n    for when GNU coreutils aren’t present,\n    so they are not necessary.)\n\n\nDreamdir scripts\n================\n\nA number of example scripts, largely written in Python, are provided in the\n`scripts/` directory of this repository; you may wish to use some of these as\nmodels for building your own scripts. Of particular note is `ddirparse.py`,\nwhich is a general library for use in developing Dreamdir scripts.\n\nI don’t make any guarantees about the general applicability or correctness of\nthese scripts. Some have not been tested recently. *You must read through the\ncode of any script that looks interesting before using it*; you may find there\nare still file paths, system-specific constants, or other surprises lurking\nsomewhere.\n\n\nVim plugin\n==========\n\nFor those who use vim, syntax highlighting and ftplugin files are located in\nthe `vim/` directory; you can install these to your `~/.vim` directory directly\nor use your favorite plugin manager.\n\nYou may want to remove the `setlocal cpoptions+=J` (`:help cpo-J`) line from\n`vim/ftplugin/dream.vim` if you don’t want to double-space between sentences\n(see the “Formatting guidelines” section above).\n\nCtags functionality is included in dreamdir. The tags file contains tags for\nall dream ID numbers and all header values. You can do a number of handy things\nwith this in vim. Among others:\n\n* With a dream open, jump to a different dream N with `:ta N`, e.g., `:ta 900`.\n* With the cursor on a dream number (*see #900*), press `Control-]` to open\n  that dream.\n* With a header value highlighted in visual mode, or with the cursor on top of\n  a single-word header value, press `g]` to show all matching tags. This will\n  show all the dreams that use that header value, along with the whole header\n  line and the Title header of the matching dream (if available).\n* Search for header values containing *foo* with `:tjump /foo`. Along with\n  being a handy way to do a quick search without having to leave your editor\n  and run `dr` again, this is an easy way to answer questions about what tags\n  you’ve previously used when you’re thinking of tags for the dream you’re\n  currently writing up.\n\nTags are stored in the file `.dreams.ctags` in your dreamdir folder. They need\nto be initially created as well as updated periodically by running `dr\nregenerate-tags`; any changes to headers or new dreams will not be known to Vim\nuntil the tags file is updated.\n\n\nThe `dr` script\n===============\n\nThe `dr` script provides convenient tools to manage your dreamdir. The script\nassumes the current directory is your dreamdir, so it may be run like this:\n\n    $ cd ~/dreams\n    $ dr new\n\nAlternatively, `dr` recognizes the environment variable `DREAMDIR` as the path\nto your dreamdir. If this variable is defined and you are not currently in a\ndreamdir when you run `dr`, that directory will be used instead.\n\nDetailed help on all the functions and options you have can be obtained at the\ncommand line. Type `dr help` for the basics, and it will refer you to other help pages\n(e.g., `dr help search`) where appropriate.\n\nNote that all commands can be abbreviated by their initials; `find` is `f`, for\nexample, and `dump-headers` is `dh`. Keywords in search expressions can be\nabbreviated similarly, so to find dreams tagged with `Maud` in the `People`\nfield, we can use `dr f t People Maud` as well as `dr find tagged People Maud`.\nThe long names are normally used throughout the documentation for clarity, and\nthey are easier to remember when you’re getting started, but once you know what\nyou’re doing you can save quite a few keystrokes this way.\n\n\nSupport \u0026 Development\n=====================\n\n![Azure DevOps badge](https://dev.azure.com/thetechnicalgeekery/dreamdir/_apis/build/status/sobjornstad.dreamdir?branchName=master)\n\nPlease post bugs on the Github issue tracker; if you prefer you can email me at\n`contact@sorenbjornstad.com`. If you have a problem with `dr`, please mention\nyour operating system and version of bash.\n\nImprovements and pull requests are welcome as long as you release your code\nunder the MIT license and they are consistent with the project’s philosophy.\nPlease make sure that `tests/pre-commit-hook.sh` exits successfully before\nsubmitting any modifications to `dr`; this requires\n[shellcheck](http://www.shellcheck.net/),\n[BATS](https://github.com/sstephenson/bats), and GCC. If you have modified the\nbehavior of `dr`, you may need to change the tests in `tests/test_dr`; they are\npretty easy to figure out. If you don’t want to install `shellcheck` (it\nrequires Haskell and takes some time to install), you can paste the code on the\nshellcheck website and then run `tests/test_dr` and `cd scripts \u0026\u0026 make clean\n\u0026\u0026 make` manually to finish the pre-commit tests.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsobjornstad%2Fdreamdir","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsobjornstad%2Fdreamdir","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsobjornstad%2Fdreamdir/lists"}