0ade724f |
1 | # bash notes |
2 | |
6c152f7e |
3 | ## a simple note taking script written in bash |
0ade724f |
4 | |
6c152f7e |
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. |
0ade724f |
6 | |
efa3e607 |
7 | It's a simple (enough) bash script, the only dependence (yet) is [jq](https://stedolan.github.io/jq/). |
0ade724f |
8 | |
6c152f7e |
9 | here's all the functions that are now available: |
0ade724f |
10 | |
11 | ```bash |
efa3e607 |
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 |
3bd93e7f |
29 | --showconf : Display running options |
30 | --sync : Sync notes to git repository |
efa3e607 |
31 | |
32 | if a non option is passed and is a valid note ID, the note will be displayed. |
0ade724f |
33 | ``` |
34 | |
6c152f7e |
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 | |
efa3e607 |
44 | ```bash |
45 | notes.sh --userconf |
46 | ``` |
6c152f7e |
47 | |
efa3e607 |
48 | And you'll have all your settings in `~/.config/bash-notes.rc`. This file will be sourced every time you run the script. |
6c152f7e |
49 | |
efa3e607 |
50 | You can change all these settings by editing the file: |
6c152f7e |
51 | |
04781825 |
52 | ```bash |
6c152f7e |
53 | # Binaries to use |
3bd93e7f |
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 |
6c152f7e |
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 " |
efa3e607 |
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. |
3bd93e7f |
65 | PAGER=/usr/bin/more |
6c152f7e |
66 | |
cb8fcb2f |
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 |
6c152f7e |
70 | # base directory for program files |
3bd93e7f |
71 | BASEDIR=~/.local/share/bash-notes |
6c152f7e |
72 | # notes database in json format |
73 | DB=${BASEDIR}/db.json |
74 | # directory containing the actual notes |
75 | NOTESDIR=${BASEDIR}/notes |
3bd93e7f |
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="" |
6c152f7e |
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 | |
3bd93e7f |
95 | This script can: |
fe606f6a |
96 | |
efa3e607 |
97 | * write a new note `--add="Your note title"` or in short `-a"Your note title"` |
3bd93e7f |
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. |
efa3e607 |
100 | |
101 | * modify an existing note `--edit=[note ID]`, short version `-e[note ID]` |
3bd93e7f |
102 | - EG. `notes.sh --edit=7` will let you modify note n. 7 |
efa3e607 |
103 | |
104 | * delete a note `--delete=[note ID]`, or `-d[note ID]` |
3bd93e7f |
105 | - EG. `notes.sh --delete=7` will delete note n. 7 |
efa3e607 |
106 | |
107 | * delete all notes `--delete=all`, or `-dall` |
108 | |
6c152f7e |
109 | * list existing notes `--list` or `-l` in short |
110 | |
efa3e607 |
111 | * display a note `--show=[note ID]`, or `-s[note ID]`. |
112 | |
3bd93e7f |
113 | It's also possible to simply pass `[note ID]` as an argument to the script and the corresponding note will be displayed. |
efa3e607 |
114 | |
115 | ```bash |
116 | notes.sh 1 |
117 | ``` |
118 | |
3bd93e7f |
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. |
6c152f7e |
120 | |
efa3e607 |
121 | ##### Plain listing vs "colorful" |
122 | |
6c152f7e |
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 | |
04781825 |
125 | ```bash |
6c152f7e |
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 | |
04781825 |
136 | ```bash |
6c152f7e |
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. |
efa3e607 |
143 | The plain option must precede all other options or it won't work. I'll try and fix this behavior in the future. |
6c152f7e |
144 | |
145 | I'd love to implement some kind of searching functionality, but I'll have to look into that. |
146 | |
efa3e607 |
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 | |
3bd93e7f |
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 | |
034ff3eb |
178 | ### Installing |
179 | |
180 | Simply copy the script in your $PATH and make it executable, something like this should work: |
181 | |
04781825 |
182 | ```bash |
034ff3eb |
183 | mv notes.sh ~/bin/ |
184 | chmod 755 ~/bin/notes.sh |
185 | ``` |
186 | |
187 | Adapt to your needs as you see fit. |
188 | |
efa3e607 |
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 | |
cb8fcb2f |
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 | |
6c152f7e |
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 | |
efa3e607 |
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 [...] |
6c152f7e |
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 | |
abf04f28 |
221 | ### ChangeLog |
222 | |
3bd93e7f |
223 | * v0.4 - GIT support. Some UX improvements |
224 | - Sync all your notes to a git remote. |
225 | |
efa3e607 |
226 | * v0.3 - backups management. Some UX improvements |
3bd93e7f |
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. |
efa3e607 |
229 | |
abf04f28 |
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 | |
6c152f7e |
235 | ### Mantainer |
236 | |
237 | * [danix](https://danix.xyz) - it's just me, really... |
efa3e607 |
238 | |
6c152f7e |
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/ |