README.md

   1 # bash notes
   2
   3 ## a simple note taking script written in bash
   4
   5 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.
   6
   7 It's a simple (enough) bash script, the only dependence (yet) is [jq](https://stedolan.github.io/jq/).
   8
   9 here's all the functions that are now available:
  10
  11 ```bash
  12 Usage:
  13   notes.sh [PARAMS] ...
  14
  15 notes parameters are:
  16   -h | --help                   : This help text
  17   -p | --plain                  : Output is in plain text
  18                                   (without this option the output is formatted)
  19                                   (this option must precede all others)
  20   -l | --list                   : List existing notes
  21   -a | --add=["<title>"]        : Add new note
  22   -e | --edit=[<note>]          : Edit note
  23   -d | --delete=[<note> | all]  : Delete single note or all notes at once
  24   -s | --show=[<note>]          : Display note using your favourite PAGER
  25   -r | --restore=[<dir>]        : Restore a previous backup from dir
  26   -v | --version                : Print version
  27   --userconf                    : Export User config file
  28   --backup [<dest>]             : Backup your data in your destination folder
  29
  30 if a non option is passed and is a valid note ID, the note will be displayed.
  31 ```
  32
  33 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.
  34
  35 ### Settings
  36
  37 When you first run it, notes.sh will create all the files it needs to operate.
  38 By default the directory will be populated in `~/.local/share/bash-notes`.
  39
  40 If you want to modify the predefined settings, you can export a user configuration file by running
  41
  42 ```bash
  43 notes.sh --userconf
  44 ```
  45
  46 And you'll have all your settings in `~/.config/bash-notes.rc`. This file will be sourced every time you run the script.
  47
  48 You can change all these settings by editing the file:
  49
  50 ```bash
  51 # Binaries to use
  52 JQ=${JQ:-/usr/bin/jq}
  53 EDITOR=${EDITOR:-/usr/bin/vim}
  54 TERMINAL=${TERMINAL:-/usr/bin/alacritty}
  55 # add options for your terminal. Remember to add the last option to execute
  56 # your editor program, otherwise the script will fail.
  57 # see example in the addnote function
  58 TERM_OPTS="--class notes --title notes -e "
  59 # Setting PAGER here overrides whatever is set in your default shell
  60 # comment this option to use your default pager if set in your shell.
  61 PAGER=${PAGER:-/usr/bin/more}
  62
  63 # set this to true to have output in plain text
  64 # or use the -p option on the command line before every other option
  65 PLAIN=false
  66 # base directory for program files
  67 BASEDIR=${BASEDIR:-~/.local/share/bash-notes}
  68 # notes database in json format
  69 DB=${BASEDIR}/db.json
  70 # directory containing the actual notes
  71 NOTESDIR=${BASEDIR}/notes
  72 ```
  73
  74 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.
  75
  76 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.
  77
  78 ### Functionalities
  79
  80 bash-notes can:
  81
  82  * write a new note `--add="Your note title"` or in short `-a"Your note title"`
  83
  84  * modify an existing note `--edit=[note ID]`, short version `-e[note ID]`
  85
  86  * delete a note `--delete=[note ID]`, or `-d[note ID]`
  87
  88  * delete all notes `--delete=all`, or `-dall`
  89
  90  * list existing notes `--list` or `-l` in short
  91
  92  * display a note `--show=[note ID]`, or `-s[note ID]`.
  93
  94    It's also possible to simply pass [note ID] as an argument to the script and the corresponding note will be displayed.
  95
  96    ```bash
  97    notes.sh 1
  98    ```
  99
 100 The *note id* is assigned when the note is created, and that's how you refer to the note in the program.
 101
 102 ##### Plain listing vs "colorful"
 103
 104 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:
 105
 106 ```bash
 107 notes.sh -l
 108 listing all notes
 109
 110 [ID]    [TITLE]         [CREATED]
 111 [1]     ciao nota       25/03/2023 18:53 +0100CET
 112 [2]     hello there     25/03/2023 19:02 +0100CET
 113 ```
 114
 115 And here's the same listing with the plain option:
 116
 117 ```bash
 118 notes.sh -pl
 119 1 - ciao nota - 25/03/2023 18:53 +0100CET
 120 2 - hello there - 25/03/2023 19:02 +0100CET
 121 ```
 122
 123 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.
 124 The plain option must precede all other options or it won't work. I'll try and fix this behavior in the future.
 125
 126 I'd love to implement some kind of searching functionality, but I'll have to look into that.
 127
 128 ##### Backups
 129
 130 Since version 0.3, this script can also handle backups of all your notes, you can specify a backup folder with
 131
 132 ```bash
 133 notes.sh --backup=/some/dir
 134 ```
 135
 136 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.
 137
 138 If you want to restore a backup you can do so with
 139
 140 ```bash
 141 notes.sh --restore=/some/dir
 142 ```
 143
 144 And the script will take care of putting everything back where it belongs.
 145
 146 > ##### A bit of a warning on restoring backups
 147 >
 148 > *Keep in mind that all your existing notes will be overwritten in the process.*
 149
 150 ### Installing
 151
 152 Simply copy the script in your $PATH and make it executable, something like this should work:
 153
 154 ```bash
 155 mv notes.sh ~/bin/
 156 chmod 755 ~/bin/notes.sh
 157 ```
 158
 159 Adapt to your needs as you see fit.
 160
 161 The first time you run the script it will take care of creating all the files and folders it needs in the standard directories.
 162
 163 ### Debugging
 164
 165 If the script doesn't work for you for some reasons, you can turn on debugging by running the script like this:
 166
 167 ```bash
 168 DEBUG=true notes.sh [options]
 169 ```
 170
 171 And then you'll be able to check all that happened in the log file at `/tmp/debug_bash-notes.log`
 172
 173 ### Vision
 174
 175 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.
 176
 177 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.
 178
 179 ### TO DO
 180
 181 * add a way to search the notes
 182 * ~~add a way to display a note without running vim~~ *(done in version 0.3)*
 183 * markdown support?
 184    * maybe implement an export feature that builds the html or pdf file from the note
 185      (pandoc??)
 186 * write a bash completion script to enable autocomplete in the shell
 187 * other ideas may come [...]
 188
 189 ### Contributing
 190
 191 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.
 192
 193 ### ChangeLog
 194
 195  * v0.3 - backups management. Some UX improvements
 196      * create and restore backups of all your notes and settings.
 197      * display notes using predefined PAGER variable or define your own program to use.
 198
 199  * v0.2 - debugging implemented
 200      - you can now generate a debug log in case something doesn't work
 201  * v0.1 - first public upload
 202      - all major functionalities are present and working
 203
 204 ### Mantainer
 205
 206  * [danix](https://danix.xyz) - it's just me, really...
 207
 208 ### LICENSE
 209
 210 > 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/