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

Documentation updates (#1032)

Browse source 
* Applying doc changes based on reviews of past several documentation PRs
* Update docs
  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

* Fix broken docs links
* Correct incomplete sentences and markdown formatting issues
* Make overview a little more concise
* Update some command line arguments to latest version and make it a bit more concise
* Clean up unneeded TOML modifications and other scaffolding not needed for 3.9
* Revert "Clean up unneeded TOML modifications and other scaffolding not needed for 3.9"
  This reverts commit 13b4266ed1.
* Specify that brew is also the easiest way to install jrnl on Linux
* Update docs/security.md
* Update docs/recipes.md
* Doc updates:
- Remove import/export page, fold it into formats
- Rename security to privacy-and-security.md to avoid conflation w/ github security issues
- Various small cleanup and edits from PR review

Co-authored-by: Jonathan Wren <jonathan@nowandwren.com>
This commit is contained in:
Micah Jerome Ellison 2020-10-24 15:41:58 -07:00 • committed by GitHub
parent 4ee4f388f4
commit 5b029e6117
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
11 changed files with 537 additions and 238 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

18
README.md
View file

@ -6,14 +6,9 @@ Github._
`jrnl` is a simple journal application for the command line. `jrnl` is a simple journal application for the command line.
Its goal is to facilitate the rapid creation and viewing of journal entries. It You can use it to easily create, search, and view journal entries. Journals are
is flexible enough to support different use cases and organization strategies. stored as human-readable plain text, and can also be encrypted using [AES
It is powerful enough to search through thousands of entries and display, or encryption](http://en.wikipedia.org/wiki/Advanced_Encryption_Standard).
"filter," only the entries you want to see.
`jrnl` includes support for [128-bit AES
encryption](http://en.wikipedia.org/wiki/Advanced_Encryption_Standard) using
[cryptography.Fernet](https://cryptography.io/en/latest/fernet/).
## In a Nutshell ## In a Nutshell
@ -31,9 +26,8 @@ the rest as the body. In your journal file, the result will look like this:
[2012-03-29 09:00] Called in sick. [2012-03-29 09:00] Called in sick.
Used the time to clean the house and write my book. Used the time to clean the house and write my book.
Entering `jrnl` without any arguments launches an external editor where you can If you just call `jrnl`, you will be prompted to compose your entry - but you
write your entry. `jrnl` will generate a time stamp for the entry after you save can also configure _jrnl_ to use your external editor.
and close the editor window.
For more information, please read the For more information, please read the
[documentation](https://jrnl.sh/overview/). [documentation](https://jrnl.sh/overview/).
@ -61,7 +55,7 @@ src="https://opencollective.com/jrnl/contributors.svg?width=890&button=false"
If you'd also like to help make `jrnl` better, please see our [contributing If you'd also like to help make `jrnl` better, please see our [contributing
documentation](CONTRIBUTING.md). documentation](CONTRIBUTING.md).
## Financial Backers ### Financial Backers
Another way show support is through direct financial contributions. These funds Another way show support is through direct financial contributions. These funds
go to covering our costs, and are a quick way to show your appreciation for go to covering our costs, and are a quick way to show your appreciation for

67
docs/encryption.md
View file

@ -4,26 +4,9 @@
While `jrnl` follows best practices, total security is never possible in the While `jrnl` follows best practices, total security is never possible in the
real world. There are a number of ways that people can at least partially real world. There are a number of ways that people can at least partially
compromise your `jrnl` data. See the [Privacy and Security](./security.md) page compromise your `jrnl` data. See the [Privacy and Security](./privacy-and-security.md) page
for more information. for more information.
## Dependencies
As of version 2.0, `jrnl`'s encryption functions require
[`cryptography`](https://pypi.org/project/cryptography/), which is available in
the Python Package Index (PyPI) and can be installed using `pip`:
``` sh
pip3 install cryptography
```
Previous versions of `jrnl` require
[`pycrypto`](https://pypi.org/project/pycrypto/):
```sh
pip3 install pycrypto
```
## Encrypting and Decrypting ## Encrypting and Decrypting
Existing plain text journal files can be encrypted using the `--encrypt` Existing plain text journal files can be encrypted using the `--encrypt`
@ -52,7 +35,7 @@ encrypted file untouched and create a new plain text file next to it.
## Storing Passwords in Your Keychain ## Storing Passwords in Your Keychain
There is no method to recover or reset your `jrnl` password. If you lose it, Nobody can recover or reset your `jrnl` password. If you lose it,
your data will be inaccessible forever. your data will be inaccessible forever.
For this reason, when encrypting a journal, `jrnl` asks whether you would like For this reason, when encrypting a journal, `jrnl` asks whether you would like
@ -66,16 +49,40 @@ same password again. This will trigger the keychain storage prompt.
## Manual Decryption ## Manual Decryption
Should you ever want to decrypt your journal manually, you can do so with any The easiest way to decrypt your journal is with `jrnl --decrypt`, but you could
program that supports the AES algorithm in CBC. The key used for encryption is also decrypt your journal manually if needed. To do this, you can use any
the SHA-256 hash of your password. The IV (initialization vector) is stored in program that supports the AES algorithm (specifically AES-CBC), and you'll need
the first 16 bytes of the encrypted file. The plain text is encoded in UTF-8 and the following relevant information for decryption:
padded according to PKCS\#7 before being encrypted.
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 for jrnl v2 files**:
``` python ``` python
#!/usr/bin/env python3 #!/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 base64
import getpass import getpass
@ -106,11 +113,15 @@ key = base64.urlsafe_b64encode(kdf.derive(password))
print(Fernet(key).decrypt(ciphertext).decode('utf-8')) print(Fernet(key).decrypt(ciphertext).decode('utf-8'))
``` ```
If you're still using `jrnl` version 1.X, the following script serves the same **Example for jrnl v1 files**:
purpose:
``` python ``` python
#!/usr/bin/env python3 #!/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 import argparse
from Crypto.Cipher import AES from Crypto.Cipher import AES

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
|- ...
```

342
docs/formats.md Normal file
View file

@ -0,0 +1,342 @@
# 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
[Advanced Usage](./advanced.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.
**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
### Exporting with `--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 `--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
```
#### Exporting to directories
If the `--file` argument is a directory, jrnl will export each entry into an individual file:
``` sh
jrnl --format json --file 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
|- ...
```

6
docs/installation.md
View file

@ -2,14 +2,14 @@
## Installation ## Installation
On OS X, the easiest way to install *jrnl* is using On Mac and Linux, the easiest way to install `jrnl` is using
[Homebrew](http://brew.sh/): [Homebrew](http://brew.sh/):
``` sh ``` sh
brew install jrnl brew install jrnl
``` ```
On other platforms, install *jrnl* using [Python](https://www.python.org/) 3.6+ and [pipx](https://pipxproject.github.io/pipx/): On other platforms, install `jrnl` using [Python](https://www.python.org/) 3.6+ and [pipx](https://pipxproject.github.io/pipx/):
``` sh ``` sh
pipx install jrnl pipx install jrnl
@ -37,4 +37,4 @@ Used the time to clean the house and spent 4h on writing my book.
``` ```
If you just call `jrnl`, you will be prompted to compose your entry - If you just call `jrnl`, you will be prompted to compose your entry -
but you can also configure *jrnl* to use your external editor. but you can also [configure](advanced.md) *jrnl* to use your external editor.

37
docs/overview.md
View file

@ -2,16 +2,15 @@
`jrnl` is a simple journal application for the command line. `jrnl` is a simple journal application for the command line.
`jrnl`'s goal is to facilitate the rapid creation and viewing of journal You can use it to easily create, search, and view journal entries. Journals are
entries. It is flexible enough to support different use cases and organization stored as human-readable plain text, and can also be encrypted using [AES
strategies. It is powerful enough to search through thousands of entries and encryption](http://en.wikipedia.org/wiki/Advanced_Encryption_Standard).
display, or "filter," only the entries you want to see.
`jrnl` has most of the features you need, and few of the ones you don't. `jrnl` has most of the features you need, and few of the ones you don't.
## Plain Text ## Plain Text
`jrnl` stores each journal in plain text. `jrnl` files can be stored anywhere, `jrnl` stores each journal in plain text. You can store `jrnl` files anywhere,
including in shared folders to keep them synchronized between devices. Journal including in shared folders to keep them synchronized between devices. Journal
files are compact (thousands of entries take up less than 1 MiB) and can be read files are compact (thousands of entries take up less than 1 MiB) and can be read
by almost any electronic device, now and for the foreseeable future. by almost any electronic device, now and for the foreseeable future.
@ -19,15 +18,16 @@ by almost any electronic device, now and for the foreseeable future.
## Tags ## Tags
To make it easier to find entries later, `jrnl` includes support for inline tags To make it easier to find entries later, `jrnl` includes support for inline tags
(the default tag symbol is `@`). Entries can be found and filtered (the default tag symbol is `@`). You can find and filter entries by using tags
along with other search criteria.
## Support for Multiple Journals ## Support for Multiple Journals
`jrnl` includes support for the creation and management of multiple journals, `jrnl` includes support for the creation of multiple journals, each of which
each of which can be stored as a single file or as a set of files. Entries are can be stored as a single file or as a set of files. Entries are automatically
automatically timestamped in a human-readable format that makes it easy to view timestamped in a human-readable format that makes it easy to view multiple
multiple entries at a time. `jrnl` can easily find the entries you want so that entries at a time. `jrnl` can easily find the entries you want so that you can
you can read them or edit them. read them or edit them.
## Support for External Editors ## Support for External Editors
@ -38,22 +38,19 @@ to the external editor of your choice.
## Encryption ## Encryption
`jrnl` includes support for [128-bit AES `jrnl` includes support for [AES
encryption](http://en.wikipedia.org/wiki/Advanced_Encryption_Standard) using encryption](http://en.wikipedia.org/wiki/Advanced_Encryption_Standard). See the
[cryptography.Fernet](https://cryptography.io/en/latest/fernet/). The [encryption page](./encryption.md) for more information.
[encryption page](./encryption.md) explains `jrnl`'s cryptographic framework in
more detail.
## Import and Export ## Import and Export
`jrnl` makes it easy to import entries from other sources. Existing entries can `jrnl` makes it easy to import entries from other sources. Existing entries can
be [exported](./export.md) in a variety of formats. be exported in a variety of [formats](./formats.md).
## Multi-Platform Support ## Multi-Platform Support
`jrnl` is compatible with most operating systems. Pre-compiled binaries are `jrnl` is compatible with most operating systems. You can [download](./installation.md) it using one
available through several distribution channels, and you can build from source. of a variety of package managers, or you can build from source.
See the [installation page](./installation.md) for more information.
## Open-Source ## Open-Source

89
docs/privacy-and-security.md Normal file
View file

@ -0,0 +1,89 @@
# Privacy and Security
`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 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.
### bash
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
You can disable history logging for jrnl 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
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` 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 your history
after journaling.
## Files in transit from editor to jrnl
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.
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
You may be able to hide the contents of your journal behind a layer of encryption,
but if someone has access to your configuration file, then they can figure out that
you have a journal, where that journal file is, and when you last edited it.
With a sufficient power imbalance, someone may be able to force you to unencrypt
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).

6
docs/recipes.md
View file

@ -23,7 +23,7 @@ each tag occurred in this filtered journal. Finally, we pipe this to
You can do things like You can do things like
```sh ```sh
jrnl @fixed -starred -n 10 -until "jan 2013" --short jrnl @fixed -starred -n 10 -to "jan 2013" --short
``` ```
To get a short summary of the 10 most recent, favourited entries before To get a short summary of the 10 most recent, favourited entries before
@ -34,7 +34,7 @@ January 1, 2013 that are tagged with `@fixed`.
How much did I write last year? How much did I write last year?
```sh ```sh
jrnl -from "jan 1 2013" -until "dec 31 2013" | wc -w jrnl -from "jan 1 2013" -to "dec 31 2013" | wc -w
``` ```
Will give you the number of words you wrote in 2013. How long is my Will give you the number of words you wrote in 2013. How long is my
@ -113,7 +113,7 @@ logged as a new entry in the journal you specified in the original argument.
!!! tip !!! tip
To read your journal entry or to verify the entry saved, you can use this To read your journal entry or to verify the entry saved, you can use this
command: `jrnl -n 1` (Check out [Import and Export](./export.md) for more export options). command: `jrnl -n 1` (Check out [Formats](./formats.md) for more options).
```sh ```sh
jrnl -n 1 jrnl -n 1

74
docs/security.md
View file

@ -1,74 +0,0 @@
# Privacy and Security
`jrnl` is designed with privacy and security in mind, but 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.
## 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.
### bash
You can disable history logging for jrnl in your `.bashrc`:
``` sh
HISTIGNORE="$HISTIGNORE:jrnl *"
```
### zsh
Disable history logging by adding this to your `zshrc`:
``` sh
setopt HIST_IGNORE_SPACE
alias jrnl=" jrnl"
```
### fish
Add this abbreviation to your `fish` configuration to run jrnl with
a space before it, which prevents `fish` from logging it:
``` sh
abbr --add jrnl " jrnl"
```
To delete existing `jrnl` commands from `fish`’s 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.
## 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.
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.
## Plausible deniability
You may be able to hide the contents of your journal behind a layer of encryption,
but if someone has access to your configuration file, then they can figure out that
you have a journal, where that journal file is, and when you last edited it.
With a sufficient power imbalance, someone may be able to force you to unencrypt
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).

56
docs/usage.md
View file

@ -11,6 +11,8 @@ it. Filter arguments can be combined arbitrarily. Arguments with a _double dash_
arguments are mutually exclusive (i.e., you can only specify one way to display arguments are mutually exclusive (i.e., you can only specify one way to display
or export your journal at a time). or export your journal at a time).
For a list of commands, enter `jrnl --help`.
## Composing Entries ## ## Composing Entries ##
Composing mode is entered by either starting `jrnl` without any arguments -- Composing mode is entered by either starting `jrnl` without any arguments --
@ -56,10 +58,9 @@ Behind the scenes, `jrnl` reorganizes entries in chronological order.
### Using Tags ### ### Using Tags ###
`jrnl` supports tags. Note that because `#` is a reserved character, the default `jrnl` supports tags. The default tag symbol is `@` (largely because `#` is a
tag symbol is `@`. You can specify your own tag symbol in the configuration reserved character). You can specify your own tag symbol in the configuration
file. There is no limit to how many tags you can use in an entry. To use tags, file. To use tags, preface the desired tag with the symbol:
simply preface the desired tag with the symbol:
```sh ```sh
jrnl Had a wonderful day at the @beach with @Tom and @Anna. jrnl Had a wonderful day at the @beach with @Tom and @Anna.
@ -68,6 +69,8 @@ jrnl Had a wonderful day at the @beach with @Tom and @Anna.
Although you can use capitals while tagging an entry, searches by tag are Although you can use capitals while tagging an entry, searches by tag are
case-insensitive. case-insensitive.
There is no limit to how many tags you can use in an entry.
### Starring Entries ### ### Starring Entries ###
To mark an entry as a favorite, simply "star" it using an asterisk (`*`): To mark an entry as a favorite, simply "star" it using an asterisk (`*`):
@ -83,20 +86,22 @@ _now_), the following options are equivalent:
- `jrnl *Best day of my life.` - `jrnl *Best day of my life.`
- `jrnl Best day of my life.*` - `jrnl Best day of my life.*`
!!! note Make sure that the asterisk (`*`) is **not** surrounded by whitespaces. !!! note
`jrnl Best day of my life! *` will not work because the `*` character has a Make sure that the asterisk (`*`) is **not** surrounded by whitespaces.
special meaning in most shells. `jrnl Best day of my life! *` will not work because the `*` character has a
special meaning in most shells.
## Viewing Entries ## ## Viewing and Searching Entries ##
`jrnl` can display entries in a variety of ways. Entries are filtered using commands preceded by a single dash (`-`). Type `jrnl -h` for a list of `jrnl` can display entries in a variety of ways.
commands.
It is possible to see all entries by entering `jrnl -until today`. However, in To view all entries, enter:
most cases you will likely want to use a filter to see specific entries that ```sh
meet certain criteria. `jrnl` provides several filtering commands, prefaced by a jrnl -to today
single dash (`-`), that allow you to find exactly what you're looking for. For ```
example,
`jrnl` provides several filtering commands, prefaced by a single dash (`-`), that
allow you to find a more specific range of entries. For example,
```sh ```sh
jrnl -n 10 jrnl -n 10
@ -107,15 +112,20 @@ same way. If you want to see all of the entries you wrote from the beginning of
last year until the end of this past March, you would enter last year until the end of this past March, you would enter
```sh ```sh
jrnl -from "last year" -until march jrnl -from "last year" -to march
``` ```
Filter criteria that use more than one word require surrounding quotes (`""`). Filter criteria that use more than one word require surrounding quotes (`""`).
To see entries on a particular date, use `-on`:
```sh
jrnl -on yesterday
```
### Text Search ### ### Text Search ###
The `-contains` command displays all entries containing a specific string. This The `-contains` command displays all entries containing the text you enter after it.
may be helpful when you're searching for entries and you can't remember if you This may be helpful when you're searching for entries and you can't remember if you
tagged any words when you wrote them. tagged any words when you wrote them.
You may realize that you use a word a lot and want to turn it into a tag in all You may realize that you use a word a lot and want to turn it into a tag in all
@ -153,6 +163,12 @@ in the configuration.
of the input strings look like tags. `jrnl` will assume you want to filter of the input strings look like tags. `jrnl` will assume you want to filter
by tag, rather than create a new entry that consists only of tags. by tag, rather than create a new entry that consists only of tags.
To view a list of all tags in the journal, enter:
```sh
jrnl --tags
```
### Viewing Starred Entries ### ### Viewing Starred Entries ###
To display only your favorite (starred) entries, enter To display only your favorite (starred) entries, enter
@ -169,7 +185,7 @@ editor configured in your configuration file. You can also edit only the entries
that match specific search criteria. For example, that match specific search criteria. For example,
```sh ```sh
jrnl -until 1950 @texas -and @history --edit jrnl -to 1950 @texas -and @history --edit
``` ```
opens your external editor displaying all entries tagged with `@texas` and opens your external editor displaying all entries tagged with `@texas` and
@ -227,7 +243,7 @@ removed from the journal.
To list all of your journals: To list all of your journals:
```sh ```sh
jrnl -ls jrnl --list
``` ```
The journals displayed correspond to those specified in the `jrnl` configuration The journals displayed correspond to those specified in the `jrnl` configuration

4
mkdocs.yml
View file

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