fz0x1/jrnl
1
0
Fork 0
mirror of https://github.com/jrnl-org/jrnl.git synced 2025-05-10 08:38:32 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Update docs

Browse source 
Clean up encryption docs
Clean up security docs
Delete export.md
Make new formats.md and add to sidebar. Also add all of the built-in
formats, and examples for each.
Update mkdocs config for new files
This commit is contained in:
Jonathan Wren 2020-08-29 19:46:55 -07:00
parent 353b3d9fb2
commit 4dbe453892
No known key found for this signature in database
GPG key ID: 43D5FF8722E7F68A
6 changed files with 433 additions and 124 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

60
docs/encryption.md
View file

@ -49,17 +49,40 @@ same password again. This will trigger the keychain storage prompt.
## Manual Decryption
The easiest way to decrypt your journal is with `jrnl --decrypt`, but
if you would like to decrypt your journal manually, you can do so with any
program that supports the AES algorithm in CBC. The key used for encryption is
the SHA-256 hash of your password. The IV (initialization vector) is stored in
the first 16 bytes of the encrypted file. The plain text is encoded in UTF-8 and
padded according to PKCS\#7 before being encrypted.
The easiest way to decrypt your journal is with `jrnl --decrypt`, but you could
also decrypt your journal manually if needed. To do this, you can use any
program that supports the AES algorithm (specifically AES-CBC), and you'll need
the following relevant information for decryption:
Here is a Python script that you can use to decrypt your journal:
- **Key:** The key used for encryption is the
[SHA-256](https://en.wikipedia.org/wiki/SHA-2) hash of your password.
- **Initialization vector (IV):** The IV is stored in the first 16 bytes of
your encrypted journal file.
- **The actual text of the journal** (everything after the first 16 bytes in
the encrypted journal file) is encoded in
[UTF-8](https://en.wikipedia.org/wiki/UTF-8) and padded according to
[PKCS\#7](https://en.wikipedia.org/wiki/PKCS_7) before being encrypted.
If you'd like an example of what this might look like in script form, please
see below for some examples of Python scripts that you could use to manually
decrypt your journal.
!!! note
These are only examples, and are only here to illustrate that your journal files
will still be recoverable even if `jrnl` isn't around anymore. Please use
`jrnl --decrypt` if available.
**Example 1** (for jrnl v2 files):
``` python
#!/usr/bin/env python3
"""
Decrypt a jrnl v2 encrypted journal.
Note: the `cryptography` module must be installed (you can do this with
something like `pip3 install crytography`)
"""
import base64
import getpass
@ -90,17 +113,15 @@ key = base64.urlsafe_b64encode(kdf.derive(password))
print(Fernet(key).decrypt(ciphertext).decode('utf-8'))
```
To run the above script, you'll need [`cryptography`](https://pypi.org/project/cryptography/), which you can install with `pip`:
``` sh
pip3 install cryptography
```
If you're still using `jrnl` version 1.X, the following script serves the same
purpose:
**Example 1** (for jrnl v1 files):
``` python
#!/usr/bin/env python3
"""
Decrypt a jrnl v1 encrypted journal.
Note: the `pycrypto` module must be installed (you can do this with something
like `pip3 install pycrypto`)
"""
import argparse
from Crypto.Cipher import AES
@ -124,10 +145,3 @@ plain = plain.strip(plain[-1:])
plain = plain.decode("utf-8")
print(plain)
```
This script requires
[`pycrypto`](https://pypi.org/project/pycrypto/):
```sh
pip3 install pycrypto
```

76
docs/export.md
View file

@ -1,76 +0,0 @@
# Import and Export
## Tag export
With
``` sh
jrnl --tags
```
you'll get a list of all tags you used in your journal, sorted by most
frequent. Tags occurring several times in the same entry are only
counted as one.
## List of all entries
``` sh
jrnl --short
```
Will only display the date and title of each entry.
## JSON export
Can do
``` sh
jrnl --export json
```
Why not create a [beautiful timeline](http://timeline.knightlab.com/) of
your journal?
## Markdown export
Use
``` sh
jrnl --export markdown
```
Markdown is a simple markup language that is human readable and can be
used to be rendered to other formats (html, pdf). This README for
example is formatted in markdown and github makes it look nice.
## Text export
``` sh
jrnl --export text
```
Pretty-prints your entire journal.
## Export to files
You can specify the output file of your exported journal using the
`-o` argument
``` sh
jrnl --export md -o journal.md
```
The above command will generate a file named `journal.md`. If the`-o` argument is a directory, jrnl will export each entry into an individual file
``` sh
jrnl --export json -o my_entries/
```
The contents of `my\_entries/` will then look like this:
``` output
my_entries/
|- 2013_06_03_a-beautiful-day.json
|- 2013_06_07_dinner-with-gabriel.json
|- ...
```

327
docs/formats.md Normal file
View file

@ -0,0 +1,327 @@
# Formats
`jrnl` supports a variety of alternate formats. These can be used to display your
journal in a different manner than the `jrnl` default, and can even be used to pipe data
from your journal for use in another program to create reports, or do whatever you want
with your `jrnl` data.
Any of these formats can be used with a search (e.g. `jrnl -contains "lorem ipsum"
--format json`) to display the results of that search in the given format, or can be
used alone (e.g. `jrnl --format json`) to display all entries from the selected journal.
This page shows examples of all the built-in formats, but since `jrnl` supports adding
more formats through plugins, you may have more available on your system. Please see
`jrnl --help` for a list of which formats are available on your system.
Any of these formats can be used interchangeably, and are only grouped into "display",
"data", and "report" formats below for convenience.
## Display Formats
These formats are mainly intended for displaying your journal in the terminal. Even so,
they can still be used in the same way as any other format (like written to a file, if
you choose).
### Pretty
``` sh
jrnl --format pretty
# or
jrnl -1 # any search
```
This is the default format in `jrnl`. If no `--format` is given, `pretty` will be used.
It displays the timestamp of each entry formatted to by the user config followed by the
title on the same line. Then the body of the entry is shown below.
This format is configurable through these values from your config file (see
[config](./config.md) for more details):
- `colors`
- `body`
- `date`
- `tags`
- `title`
- `indent_character`
- `linewrap`
- `timeformat`
**Example output**:
``` sh
2020-06-28 18:22 This is the first sample entry
| This is the sample body text of the first sample entry.
2020-07-01 20:00 This is the second sample entry
| This is the sample body text of the second sample entry, but this one has a @tag.
2020-07-02 09:00 This is the third sample entry
| This is the sample body text of the third sample entry.
```
### Short
``` sh
jrnl --format short
# or
jrnl --short
```
This will shorten entries to display only the date and title. It is essentially the
`pretty` format but without the body of each entry. This can be useful if you have long
journal entries and only want to see a list of entries that match your search.
**Example output**:
``` sh
2020-06-28 18:22 This is the first sample entry
2020-07-01 20:00 This is the second sample entry
2020-07-02 09:00 This is the third sample entry
```
### Fancy (or Boxed)
``` sh
jrnl --format fancy
# or
jrnl --format boxed
```
This format outlines each entry with a border. This makes it much easier to tell where
each entry starts and ends. It's an example of how free-form the formats can be, and also
just looks kinda ~*~fancy~*~, if you're into that kind of thing.
**Example output**:
``` sh
┎──────────────────────────────────────────────────────────────────────╮2020-06-28 18:22
┃ This is the first sample entry ╘═══════════════╕
┠╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
┃ This is the sample body text of the first sample entry. │
┖──────────────────────────────────────────────────────────────────────────────────────┘
┎──────────────────────────────────────────────────────────────────────╮2020-07-01 20:00
┃ This is the second sample entry ╘═══════════════╕
┠╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
┃ This is the sample body text of the second sample entry, but this one has a @tag. │
┖──────────────────────────────────────────────────────────────────────────────────────┘
┎──────────────────────────────────────────────────────────────────────╮2020-07-02 09:00
┃ This is the third sample entry ╘═══════════════╕
┠╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
┃ This is the sample body text of the third sample entry. │
┖──────────────────────────────────────────────────────────────────────────────────────┘
```
## Data Formats
These formats are mainly intended for piping or exporting your journal to other
programs. Even so, they can still be used in the same way as any other format (like
written to a file, or displayed in your terminal, if you want).
### JSON
``` sh
jrnl --format json
```
JSON is a very handy format used by many programs and has support in nearly every
programming language. There are many things you could do with JSON data. Maybe you could
use [`jq`](https://github.com/stedolan/jq) to filter through the fields in your journal.
Like this:
``` sh
$ j -3 --format json | jq '.entries[].date' jrnl-GFqVlfgP-py3.8 
"2020-06-28"
"2020-07-01"
"2020-07-02"
```
Or why not create a [beautiful timeline](http://timeline.knightlab.com/) of your journal?
**Example output**:
``` json
{
"tags": {
"@tag": 1
},
"entries": [
{
"title": "This is the first sample entry",
"body": "This is the sample body text of the first sample entry.",
"date": "2020-06-28",
"time": "18:22",
"tags": [],
"starred": false
},
{
"title": "This is the second sample entry",
"body": "This is the sample body text of the second sample entry, but this one has a @tag.",
"date": "2020-07-01",
"time": "20:00",
"tags": [
"@tag"
],
"starred": false
},
{
"title": "This is the third sample entry",
"body": "This is the sample body text of the third sample entry.",
"date": "2020-07-02",
"time": "09:00",
"tags": [],
"starred": false
}
]
}
```
### Markdown
``` sh
jrnl --format markdown
# or
jrnl --format md
```
Markdown is a simple markup language that is human readable and can be used to be
rendered to other formats (html, pdf). `jrnl`'s
[README](https://github.com/jrnl-org/jrnl/blob/develop/README.md) for example is
formatted in markdown, then Github adds some formatting to make it look nice.
The markdown format groups entries by date (first by year, then by month), and adds
header markings as needed (e.g. `#`, `##`, etc). If you already have markdown header
markings in your journal, they will be incremented as necessary to make them fit under
these new headers (i.e. `#` will become `##`).
This format can be very useful, for example, to export a journal to a program that
converts markdown to html to make a website or a blog from your journal.
**Example output**:
``` markdown
# 2020
## June
### 2020-06-28 18:22 This is the first sample entry
This is the sample body text of the first sample entry.
## July
### 2020-07-01 20:00 This is the second sample entry
This is the sample body text of the second sample entry, but this one has a @tag.
### 2020-07-02 09:00 This is the third sample entry
This is the sample body text of the third sample entry.
```
### Plain Text
``` sh
jrnl --format text
# or
jrnl --format txt
```
This outputs your journal in the same plain-text format that `jrnl` uses to store your
journal on disk. This format is particularly useful for importing and exporting journals
within `jrnl`.
You can use it, for example, to move entries from one journal to another, or to create a
new journal with search results from another journal (see [Import and
Export](./import-and-export.md) for more details).
**Example output**:
``` sh
[2020-06-28 18:22] This is the first sample entry
This is the sample body text of the first sample entry.
[2020-07-01 20:00] This is the second sample entry
This is the sample body text of the second sample entry, but this one has a @tag.
[2020-07-02 09:00] This is the third sample entry
This is the sample body text of the third sample entry.
```
### XML
``` sh
jrnl --format xml
```
This outputs your journal into XML format. XML is a commonly used data format and is
supported by many programs and programming languages.
**Example output**:
``` xml
<?xml version="1.0" ?>
<journal>
<entries>
<entry date="2020-06-28T18:22:00" starred="">This is the first sample entry This is the sample body text of the first sample entry.</entry>
<entry date="2020-07-01T20:00:00" starred="">
<tag name="@tag"/>
This is the second sample entry This is the sample body text of the second sample entry, but this one has a @tag.
</entry>
<entry date="2020-07-02T09:00:00" starred="">*This is the third sample entry, and is starred This is the sample body text of the third sample entry.</entry>
</entries>
<tags>
<tag name="@tag">1</tag>
</tags>
</journal>
```
### YAML
``` sh
jrnl --format yaml
```
This outputs your journal into YAML format. YAML is a commonly used data format and is
supported by many programs and programming languages.
**Example output**:
``` yaml
title: This is the second sample entry
date: 2020-07-01 20:00
starred: False
tags: tag
This is the sample body text of the second sample entry, but this one has a @tag.
```
## Report formats
Since formats use your journal data and display it in different ways, they can also be
used to create reports.
### Tags
``` sh
jrnl --format tags
# or
jrnl --tags
```
This format is a simple example of how formats can be used to create reports. It
displays each tag, and a count of how many entries in which tag appears in your journal
(or in the search results), sorted by most frequent.
Example output:
``` sh
@one : 32
@two : 17
@three : 4
```
## Options
### `--file`
Example: `jrnl --format json --file /some/path/to/a/file.txt`
By default, `jrnl` will output entries to your terminal. But if you provide the `--file`
along with a filename, the same output that would have been to your terminal will be
written to the file instead. This is the same as piping the output to a file.
So, in bash for example, the following two statements are equivalent:
``` sh
jrnl --format json --file myjournal.json
```
``` sh
jrnl --format json > myjournal.json
```

28
docs/import-and-export.md Normal file
View file

@ -0,0 +1,28 @@
<!--
@TODO: Update this for v2.5
-->
## Export to files
You can specify the output file of your exported journal using the
`-o` argument
``` sh
jrnl --format md -o journal.md
```
The above command will generate a file named `journal.md`. If the`-o` argument is a
directory, jrnl will export each entry into an individual file
``` sh
jrnl --format json -o my_entries/
```
The contents of `my\_entries/` will then look like this:
``` output
my_entries/
|- 2013_06_03_a-beautiful-day.json
|- 2013_06_07_dinner-with-gabriel.json
|- ...
```

63
docs/security.md
View file

@ -1,65 +1,80 @@
# Privacy and Security
`jrnl` is designed with privacy and security in mind, but there are some
limitations to be aware of.
`jrnl` is designed with privacy and security in mind, but like any other
program there are some limitations to be aware of.
## Password strength
`jrnl` doesn't enforce password strength requirements. Short or commonly-used
passwords can easily be circumvented by someone with basic security skills
and access to your encrypted `jrnl` file.
passwords can be easily circumvented by someone with basic security skills
to access to your encrypted `jrnl` file.
## Shell history
Since you can enter entries from the command line, any tool
that logs command line actions is a potential security risk. See
below for how to deal with this problem in various shells.
Since you can enter entries from the command line, any tool that logs command
line actions is a potential security risk. See below for how to deal with this
problem in various shells.
### bash
You can disable history logging for jrnl in your `.bashrc`:
You can disable history logging for jrnl by adding this line into your
`~/.bashrc` file:
``` sh
HISTIGNORE="$HISTIGNORE:jrnl *"
```
To delete existing `jrnl` commands from `bash` history, simply delete them from
your bash history file. The default location of this file is `~/.bash_history`,
but you can run `echo "$HISTFILE"` to find it if needed. Also, you can run
`history -c` to delete all commands from your history.
### zsh
Disable history logging by adding this to your `zshrc`:
You can disable history logging for jnrl by adding this to your `~/.zshrc`
file:
``` sh
setopt HIST_IGNORE_SPACE
alias jrnl=" jrnl"
```
To delete existing `jrnl` commands from `zsh` history, simply remove them from
your zsh history file. The default location of this file is `~/.zsh_history`,
but you can run `echo "$HISTFILE"` to find it if needed. Also, you can run
`history -c` to delete all commands from your history.
### fish
Add this abbreviation to your `fish` configuration to run jrnl with
a space before it, which prevents `fish` from logging it:
By default `fish` will not log any command that starts with a space. If you
want to always run jrnl with a space before it, then you can add this to your
`~/.config/fish/config.fish` file:
``` sh
abbr --add jrnl " jrnl"
```
To delete existing `jrnl` commands from `fish`’s history, run
`history delete --prefix 'jrnl '`.
To delete existing jrnl commands from `fish` history, run `history delete --prefix 'jrnl '`.
### Windows Command Prompt
Windows doesn't log history to disk, but it does keep it in your command
prompt session. Close the command prompt or press Alt+F7 to clear its
history after journaling.
Windows doesn't log history to disk, but it does keep it in your command prompt
session. Close the command prompt or press `Alt`+`F7` to clear your history
after journaling.
## Files in transit from editor to jrnl
When creating or editing an entry, `jrnl` uses a plain text temporary file on disk
to give your editor access to it. `jrnl` deletes the temporary file when it
saves the entry back to your journal.
When creating or editing an entry, `jrnl` uses a unencrypted temporary file on
disk in order to give your editor access to your journal. After you close your
editor, `jrnl` then deletes this temporary file.
If you save an entry but haven't closed your editor yet, and your computer shuts
off or the `jrnl` process is killed, the entry remains on your disk as a
temporary file. You can mitigate this issue by only saving with your editor
right before closing it.
So, if you have saved a journal entry but haven't closed your editor yet, the
unencrypted temporary remains on your disk. If your computer were to shut off
during this time, or the `jrnl` process were killed unexpectedly, then the
unencrypted temporary file will remain on your disk. You can mitigate this
issue by only saving with your editor right before closing it. You can also
manually delete these files (i.e. files named `jrnl_*.txt`) from your temporary
folder.
## Plausible deniability
@ -71,4 +86,4 @@ it through non-technical means.
## Notice any other risks?
Please let the maintainers know by [filing an issue on GitHub](https://github.com/jrnl-org/jrnl/issues).
Please let the maintainers know by [filing an issue on GitHub](https://github.com/jrnl-org/jrnl/issues).

3
mkdocs.yml
View file

@ -19,6 +19,7 @@ nav:
- Basic Usage: usage.md
- Encryption: encryption.md
- Privacy and Security: security.md
- Import and Export: export.md
- Formats: formats.md
- Import and Export: import-and-export.md
- Advanced Usage: advanced.md
- Recipes: recipes.md