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   --showconf                    : Display running options
  30   --sync                        : Sync notes to git repository
  31
  32 if a non option is passed and is a valid note ID, the note will be displayed.
  33 ```
  34
  35 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.
  36
  37 ### Settings
  38
  39 When you first run it, notes.sh will create all the files it needs to operate.
  40 By default the directory will be populated in `~/.local/share/bash-notes`.
  41
  42 If you want to modify the predefined settings, you can export a user configuration file by running
  43
  44 ```bash
  45 notes.sh --userconf
  46 ```
  47
  48 And you'll have all your settings in `~/.config/bash-notes.rc`. This file will be sourced every time you run the script.
  49
  50 You can change all these settings by editing the file:
  51
  52 ```bash
  53 # Binaries to use
  54 JQ=/usr/bin/jq
  55 EDITOR=/usr/bin/vim
  56 TERMINAL=/usr/bin/alacritty
  57 # Git binary only used if $USEGIT is true - See below
  58 GIT=/usr/bin/git
  59 # add options for your terminal. Remember to add the last option to execute
  60 # your editor program, otherwise the script will fail.
  61 # see example in the addnote function
  62 TERM_OPTS="--class notes --title notes -e "
  63 # Setting PAGER here overrides whatever is set in your default shell
  64 # comment this option to use your default pager if set in your shell.
  65 PAGER=/usr/bin/more
  66
  67 # set this to true to have output in plain text
  68 # or use the -p option on the command line before every other option
  69 PLAIN=false
  70 # base directory for program files
  71 BASEDIR=~/.local/share/bash-notes
  72 # notes database in json format
  73 DB=${BASEDIR}/db.json
  74 # directory containing the actual notes
  75 NOTESDIR=${BASEDIR}/notes
  76
  77 ### GIT SUPPORT
  78
  79 # If you want to store your notes in a git repository set this to true
  80 USEGIT=true
  81 # Address of your remote repository. Without this GIT will refuse to work
  82 GITREMOTE=""
  83 # How long should we wait (in seconds) between sync on the git remote. Default 3600 (1 hour)
  84 GITSYNCDELAY="3600"
  85 # The name of this client. If left empty, defaults to the output of hostname
  86 GITCLIENT=""
  87 ```
  88
  89 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.
  90
  91 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.
  92
  93 ### Functionalities
  94
  95 This script can:
  96
  97  * write a new note `--add="Your note title"` or in short `-a"Your note title"`
  98    - EG. `notes.sh --add="this is a nice note"`
  99    If the title is left empty, two random words will be assigned as title.
 100
 101  * modify an existing note `--edit=[note ID]`, short version `-e[note ID]`
 102    - EG. `notes.sh --edit=7` will let you modify note n. 7
 103
 104  * delete a note `--delete=[note ID]`, or `-d[note ID]`
 105    - EG. `notes.sh --delete=7` will delete note n. 7
 106
 107  * delete all notes `--delete=all`, or `-dall`
 108
 109  * list existing notes `--list` or `-l` in short
 110
 111  * display a note `--show=[note ID]`, or `-s[note ID]`.
 112
 113    It's also possible to simply pass `[note ID]` as an argument to the script and the corresponding note will be displayed.
 114
 115    ```bash
 116    notes.sh 1
 117    ```
 118
 119 The *note id* is assigned when the note is created, and that's how you refer to the note in the program. You can see the IDs assigned to each note when listing them.
 120
 121 ##### Plain listing vs "colorful"
 122
 123 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:
 124
 125 ```bash
 126 notes.sh -l
 127 listing all notes
 128
 129 [ID]    [TITLE]         [CREATED]
 130 [1]     ciao nota       25/03/2023 18:53 +0100CET
 131 [2]     hello there     25/03/2023 19:02 +0100CET
 132 ```
 133
 134 And here's the same listing with the plain option:
 135
 136 ```bash
 137 notes.sh -pl
 138 1 - ciao nota - 25/03/2023 18:53 +0100CET
 139 2 - hello there - 25/03/2023 19:02 +0100CET
 140 ```
 141
 142 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.
 143 The plain option must precede all other options or it won't work. I'll try and fix this behavior in the future.
 144
 145 I'd love to implement some kind of searching functionality, but I'll have to look into that.
 146
 147 ##### Backups
 148
 149 Since version 0.3, this script can also handle backups of all your notes, you can specify a backup folder with
 150
 151 ```bash
 152 notes.sh --backup=/some/dir
 153 ```
 154
 155 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.
 156
 157 If you want to restore a backup you can do so with
 158
 159 ```bash
 160 notes.sh --restore=/some/dir
 161 ```
 162
 163 And the script will take care of putting everything back where it belongs.
 164
 165 > ##### A bit of a warning on restoring backups
 166 >
 167 > *Keep in mind that all your existing notes will be overwritten in the process.*
 168
 169 ##### Git
 170
 171 Starting with version 0.4, git support has been added, so now you can sync your notes to a git remote. The program lets you specify a few options like:
 172  - your git executable
 173  - the remote address
 174  - how long before syncing again to the remote
 175  - a nickname for the computer where this script is running.
 176    This is helpful if you want to sync your notes on multiple computers, to know from which client something has appened to git.
 177
 178 ### Installing
 179
 180 Simply copy the script in your $PATH and make it executable, something like this should work:
 181
 182 ```bash
 183 mv notes.sh ~/bin/
 184 chmod 755 ~/bin/notes.sh
 185 ```
 186
 187 Adapt to your needs as you see fit.
 188
 189 The first time you run the script it will take care of creating all the files and folders it needs in the standard directories.
 190
 191 ### Debugging
 192
 193 If the script doesn't work for you for some reasons, you can turn on debugging by running the script like this:
 194
 195 ```bash
 196 DEBUG=true notes.sh [options]
 197 ```
 198
 199 And then you'll be able to check all that happened in the log file at `/tmp/debug_bash-notes.log`
 200
 201 ### Vision
 202
 203 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.
 204
 205 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.
 206
 207 ### TO DO
 208
 209 * add a way to search the notes
 210 * ~~add a way to display a note without running vim~~ *(done in version 0.3)*
 211 * markdown support?
 212    * maybe implement an export feature that builds the html or pdf file from the note
 213      (pandoc??)
 214 * write a bash completion script to enable autocomplete in the shell
 215 * other ideas may come [...]
 216
 217 ### Contributing
 218
 219 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.
 220
 221 ### ChangeLog
 222
 223  * v0.4 - GIT support. Some UX improvements
 224      - Sync all your notes to a git remote.
 225
 226  * v0.3 - backups management. Some UX improvements
 227      - create and restore backups of all your notes and settings.
 228      - display notes using predefined PAGER variable or define your own program to use.
 229
 230  * v0.2 - debugging implemented
 231      - you can now generate a debug log in case something doesn't work
 232  * v0.1 - first public upload
 233      - all major functionalities are present and working
 234
 235 ### Mantainer
 236
 237  * [danix](https://danix.xyz) - it's just me, really...
 238
 239 ### LICENSE
 240
 241 > 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/