content/articles/bash-notes.md

   1 ---
   2 title: "Bash Notes"
   3 date: 2023-04-07T11:20:20+02:00
   4 draft: true
   5 type: article
   6 author: "danilo 'danix' m."
   7 format: "post"
   8 excerpt: "A 'sticky notes' kind of app, written in bash for all shell entusiasts."
   9 featured_image: "/img/default_article.jpg"
  10 categories:
  11   - "bash"
  12   - "notes"
  13   - "linux"
  14   - "diy"
  15 tags:
  16
  17 ---
  18
  19 # bash notes
  20
  21 ## a simple note taking script written in bash
  22
  23 I've found myself in need of a simple way to take notes, and since the other solutions available didn't meet my needs, I've decided to write my own script.
  24
  25 It's a simple (enough) bash script, the only dependence (yet) is [jq](https://stedolan.github.io/jq/).
  26
  27 here's all the functions that are now available:
  28
  29 ```bash
  30 Usage:
  31   notes.sh [PARAMS] ...
  32
  33 notes parameters are:
  34   -h | --help                   : This help text
  35   -p | --plain                  : Output is in plain text
  36                                   (without this option the output is formatted)
  37                                   (this option must precede all others)
  38   -l | --list                   : List existing notes
  39   -a | --add=["<title>"]        : Add new note
  40   -e | --edit=[<note>]          : Edit note
  41   -d | --delete=[<note> | all]  : Delete single note or all notes at once
  42   -s | --show=[<note>]          : Display note using your favourite PAGER
  43   -r | --restore=[<dir>]        : Restore a previous backup from dir
  44   -v | --version                : Print version
  45   --userconf                    : Export User config file
  46   --backup [<dest>]             : Backup your data in your destination folder
  47
  48 if a non option is passed and is a valid note ID, the note will be displayed.
  49 ```
  50
  51 All the basic functionalities are present and working, it probably needs some polishing and some testing, so if you want to give it a try, let me know what you think.
  52
  53 ### Settings
  54
  55 When you first run it, notes.sh will create all the files it needs to operate.
  56 By default the directory will be populated in `~/.local/share/bash-notes`.
  57
  58 If you want to modify the predefined settings, you can export a user configuration file by running
  59
  60 ```bash
  61 notes.sh --userconf
  62 ```
  63
  64 And you'll have all your settings in `~/.config/bash-notes.rc`. This file will be sourced every time you run the script.
  65
  66 You can change all these settings by editing the file:
  67
  68 ```bash
  69 # Binaries to use
  70 JQ=${JQ:-/usr/bin/jq}
  71 EDITOR=${EDITOR:-/usr/bin/vim}
  72 TERMINAL=${TERMINAL:-/usr/bin/alacritty}
  73 # add options for your terminal. Remember to add the last option to execute
  74 # your editor program, otherwise the script will fail.
  75 # see example in the addnote function
  76 TERM_OPTS="--class notes --title notes -e "
  77 # Setting PAGER here overrides whatever is set in your default shell
  78 # comment this option to use your default pager if set in your shell.
  79 PAGER=${PAGER:-/usr/bin/more}
  80
  81 # set this to true to have output in plain text
  82 # or use the -p option on the command line before every other option
  83 PLAIN=false
  84 # base directory for program files
  85 BASEDIR=${BASEDIR:-~/.local/share/bash-notes}
  86 # notes database in json format
  87 DB=${BASEDIR}/db.json
  88 # directory containing the actual notes
  89 NOTESDIR=${BASEDIR}/notes
  90 ```
  91
  92 Most are pretty self explanatory, the only one that might need clarification is `TERM_OPTS` which is used to set the terminal window that will run the editor while writing the note.
  93
  94 Special attention is needed when specifying the options, in my case, using [alacritty](https://github.com/alacritty/alacritty), the option that allows to run some software in the newly created window is `-e`, so I need to specify this as the last option.
  95
  96 ### Functionalities
  97
  98 bash-notes can:
  99
 100  * write a new note `--add="Your note title"` or in short `-a"Your note title"`
 101
 102  * modify an existing note `--edit=[note ID]`, short version `-e[note ID]`
 103
 104  * delete a note `--delete=[note ID]`, or `-d[note ID]`
 105
 106  * delete all notes `--delete=all`, or `-dall`
 107
 108  * list existing notes `--list` or `-l` in short
 109
 110  * display a note `--show=[note ID]`, or `-s[note ID]`.
 111
 112    It's also possible to simply pass [note ID] as an argument to the script and the corresponding note will be displayed.
 113
 114    ```bash
 115    notes.sh 1
 116    ```
 117
 118 The *note id* is assigned when the note is created, and that's how you refer to the note in the program.
 119
 120 ##### Plain listing vs "colorful"
 121
 122 The `--plain` or `-p` option in short, dictates how the output from the script is formatted, here's a sample listing of all the notes:
 123
 124 ```bash
 125 notes.sh -l
 126 listing all notes
 127
 128 [ID]    [TITLE]         [CREATED]
 129 [1]     ciao nota       25/03/2023 18:53 +0100CET
 130 [2]     hello there     25/03/2023 19:02 +0100CET
 131 ```
 132
 133 And here's the same listing with the plain option:
 134
 135 ```bash
 136 notes.sh -pl
 137 1 - ciao nota - 25/03/2023 18:53 +0100CET
 138 2 - hello there - 25/03/2023 19:02 +0100CET
 139 ```
 140
 141 It's just a proof of concept at the moment, but the idea is to use a more interesting output maybe using markup, and strip it down in plain mode. After all is still a work in progress.
 142 The plain option must precede all other options or it won't work. I'll try and fix this behavior in the future.
 143
 144 I'd love to implement some kind of searching functionality, but I'll have to look into that.
 145
 146 ##### Backups
 147
 148 Since version 0.3, this script can also handle backups of all your notes, you can specify a backup folder with
 149
 150 ```bash
 151 notes.sh --backup=/some/dir
 152 ```
 153
 154 and the script will create the directory if it doesn't exists and backup all your data, including the rc file if you made one.
 155
 156 If you want to restore a backup you can do so with
 157
 158 ```bash
 159 notes.sh --restore=/some/dir
 160 ```
 161
 162 And the script will take care of putting everything back where it belongs.
 163
 164 > ##### A bit of a warning on restoring backups
 165 >
 166 > *Keep in mind that all your existing notes will be overwritten in the process.*
 167
 168 ### Installing
 169
 170 Simply copy the script in your $PATH and make it executable, something like this should work:
 171
 172 ```bash
 173 mv notes.sh ~/bin/
 174 chmod 755 ~/bin/notes.sh
 175 ```
 176
 177 Adapt to your needs as you see fit.
 178
 179 The first time you run the script it will take care of creating all the files and folders it needs in the standard directories.
 180
 181 ### Debugging
 182
 183 If the script doesn't work for you for some reasons, you can turn on debugging by running the script like this:
 184
 185 ```bash
 186 DEBUG=true notes.sh [options]
 187 ```
 188
 189 And then you'll be able to check all that happened in the log file at `/tmp/debug_bash-notes.log`
 190
 191 ### Vision
 192
 193 Ok, maybe vision is a bit of a stretch, but I've written this script to use it in my daily workflow with [rofi](https://github.com/davatorium/rofi) and [i3wm](https://github.com/i3/i3). I'll adapt the way it works to better suit this need of mine.
 194
 195 There are of course things I'd love to add, but my main goal is for it to work the way I planned to use it.
 196
 197 ### TO DO
 198
 199 * add a way to search the notes
 200 * ~~add a way to display a note without running vim~~ *(done in version 0.3)*
 201 * markdown support?
 202    * maybe implement an export feature that builds the html or pdf file from the note
 203      (pandoc??)
 204 * write a bash completion script to enable autocomplete in the shell
 205 * other ideas may come [...]
 206
 207 ### Contributing
 208
 209 It'd mean so much to receive some feedback, patches if you feel like contributing, I'm not expecting much as this is a personal project, but feel free to interact as much as you want.
 210
 211 ### ChangeLog
 212
 213  * v0.3 - backups management. Some UX improvements
 214      * create and restore backups of all your notes and settings.
 215      * display notes using predefined PAGER variable or define your own program to use.
 216
 217  * v0.2 - debugging implemented
 218      - you can now generate a debug log in case something doesn't work
 219  * v0.1 - first public upload
 220      - all major functionalities are present and working
 221
 222 ### Mantainer
 223
 224  * [danix](https://danix.xyz) - it's just me, really...
 225
 226 ### LICENSE
 227
 228 > bash-notes © 2023 by danix is licensed under CC BY-NC 4.0. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc/4.0/