diff --git a/README.md b/README.md index 54b36b7d..22bc6a26 100644 --- a/README.md +++ b/README.md @@ -6,14 +6,9 @@ Github._ `jrnl` is a simple journal application for the command line. -Its goal is to facilitate the rapid creation and viewing of journal entries. It -is flexible enough to support different use cases and organization strategies. -It is powerful enough to search through thousands of entries and display, or -"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/). +You can use it to easily create, search, and view journal entries. Journals are +stored as human-readable plain text, and can also be encrypted using [AES +encryption](http://en.wikipedia.org/wiki/Advanced_Encryption_Standard). ## 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. Used the time to clean the house and write my book. -Entering `jrnl` without any arguments launches an external editor where you can -write your entry. `jrnl` will generate a time stamp for the entry after you save -and close the editor window. +If you just call `jrnl`, you will be prompted to compose your entry - but you +can also configure _jrnl_ to use your external editor. For more information, please read the [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 documentation](CONTRIBUTING.md). -## Financial Backers +### Financial Backers 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 diff --git a/docs/encryption.md b/docs/encryption.md index a4f0a35a..6b966aa3 100644 --- a/docs/encryption.md +++ b/docs/encryption.md @@ -4,26 +4,9 @@ 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 -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. -## 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 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 -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. 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 -Should you ever want 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 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 @@ -106,11 +113,15 @@ key = base64.urlsafe_b64encode(kdf.derive(password)) print(Fernet(key).decrypt(ciphertext).decode('utf-8')) ``` -If you're still using `jrnl` version 1.X, the following script serves the same -purpose: - +**Example 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 diff --git a/docs/export.md b/docs/export.md deleted file mode 100644 index 464dd550..00000000 --- a/docs/export.md +++ /dev/null @@ -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 -|- ... -``` diff --git a/docs/formats.md b/docs/formats.md new file mode 100644 index 00000000..5861fd72 --- /dev/null +++ b/docs/formats.md @@ -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 + + + + This is the first sample entry This is the sample body text of the first sample entry. + + + This is the second sample entry This is the sample body text of the second sample entry, but this one has a @tag. + + *This is the third sample entry, and is starred This is the sample body text of the third sample entry. + + + 1 + + +``` + +### 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 +|- ... +``` diff --git a/docs/installation.md b/docs/installation.md index 4c80eb0d..278522ec 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -2,14 +2,14 @@ ## 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/): ``` sh 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 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 - -but you can also configure *jrnl* to use your external editor. +but you can also [configure](advanced.md) *jrnl* to use your external editor. diff --git a/docs/overview.md b/docs/overview.md index 6f977ce7..fdfb2159 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -2,16 +2,15 @@ `jrnl` is a simple journal application for the command line. -`jrnl`'s goal is to facilitate the rapid creation and viewing of journal -entries. It is flexible enough to support different use cases and organization -strategies. It is powerful enough to search through thousands of entries and -display, or "filter," only the entries you want to see. +You can use it to easily create, search, and view journal entries. Journals are +stored as human-readable plain text, and can also be encrypted using [AES +encryption](http://en.wikipedia.org/wiki/Advanced_Encryption_Standard). `jrnl` has most of the features you need, and few of the ones you don't. ## 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 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. @@ -19,15 +18,16 @@ by almost any electronic device, now and for the foreseeable future. ## 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 -`jrnl` includes support for the creation and management of multiple journals, -each of which can be stored as a single file or as a set of files. Entries are -automatically timestamped in a human-readable format that makes it easy to view -multiple entries at a time. `jrnl` can easily find the entries you want so that -you can read them or edit them. +`jrnl` includes support for the creation of multiple journals, each of which +can be stored as a single file or as a set of files. Entries are automatically +timestamped in a human-readable format that makes it easy to view multiple +entries at a time. `jrnl` can easily find the entries you want so that you can +read them or edit them. ## Support for External Editors @@ -38,22 +38,19 @@ to the external editor of your choice. ## Encryption -`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/). The -[encryption page](./encryption.md) explains `jrnl`'s cryptographic framework in -more detail. +`jrnl` includes support for [AES +encryption](http://en.wikipedia.org/wiki/Advanced_Encryption_Standard). See the +[encryption page](./encryption.md) for more information. ## Import and Export `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 -`jrnl` is compatible with most operating systems. Pre-compiled binaries are -available through several distribution channels, and you can build from source. -See the [installation page](./installation.md) for more information. +`jrnl` is compatible with most operating systems. You can [download](./installation.md) it using one +of a variety of package managers, or you can build from source. ## Open-Source diff --git a/docs/privacy-and-security.md b/docs/privacy-and-security.md new file mode 100644 index 00000000..b93e99a1 --- /dev/null +++ b/docs/privacy-and-security.md @@ -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). diff --git a/docs/recipes.md b/docs/recipes.md index 92399591..a80a0c09 100644 --- a/docs/recipes.md +++ b/docs/recipes.md @@ -23,7 +23,7 @@ each tag occurred in this filtered journal. Finally, we pipe this to You can do things like ```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 @@ -34,7 +34,7 @@ January 1, 2013 that are tagged with `@fixed`. How much did I write last year? ```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 @@ -113,7 +113,7 @@ logged as a new entry in the journal you specified in the original argument. !!! tip 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 jrnl -n 1 diff --git a/docs/security.md b/docs/security.md deleted file mode 100644 index e8525b78..00000000 --- a/docs/security.md +++ /dev/null @@ -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). \ No newline at end of file diff --git a/docs/usage.md b/docs/usage.md index d56c9418..df683b0d 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -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 or export your journal at a time). +For a list of commands, enter `jrnl --help`. + ## Composing Entries ## 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 ### -`jrnl` supports tags. Note that because `#` is a reserved character, the default -tag symbol is `@`. 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, -simply preface the desired tag with the symbol: +`jrnl` supports tags. The default tag symbol is `@` (largely because `#` is a +reserved character). You can specify your own tag symbol in the configuration +file. To use tags, preface the desired tag with the symbol: ```sh 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 case-insensitive. +There is no limit to how many tags you can use in an entry. + ### Starring Entries ### 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.*` -!!! note Make sure that the asterisk (`*`) is **not** surrounded by whitespaces. -`jrnl Best day of my life! *` will not work because the `*` character has a -special meaning in most shells. +!!! note + Make sure that the asterisk (`*`) is **not** surrounded by whitespaces. + `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 -commands. +`jrnl` can display entries in a variety of ways. -It is possible to see all entries by entering `jrnl -until today`. However, in -most cases you will likely want to use a filter to see specific entries that -meet certain criteria. `jrnl` provides several filtering commands, prefaced by a -single dash (`-`), that allow you to find exactly what you're looking for. For -example, +To view all entries, enter: +```sh +jrnl -to today +``` + +`jrnl` provides several filtering commands, prefaced by a single dash (`-`), that +allow you to find a more specific range of entries. For example, ```sh 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 ```sh -jrnl -from "last year" -until march +jrnl -from "last year" -to march ``` 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 ### -The `-contains` command displays all entries containing a specific string. This -may be helpful when you're searching for entries and you can't remember if you +The `-contains` command displays all entries containing the text you enter after it. +This may be helpful when you're searching for entries and you can't remember if you 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 @@ -153,6 +163,12 @@ in the configuration. 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. +To view a list of all tags in the journal, enter: + +```sh +jrnl --tags +``` + ### Viewing Starred Entries ### 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, ```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 @@ -227,7 +243,7 @@ removed from the journal. To list all of your journals: ```sh -jrnl -ls +jrnl --list ``` The journals displayed correspond to those specified in the `jrnl` configuration diff --git a/mkdocs.yml b/mkdocs.yml index 9fd3bfc1..9e7d62c1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -19,7 +19,7 @@ nav: - Quickstart: installation.md - Basic Usage: usage.md - Encryption: encryption.md - - Privacy and Security: security.md - - Import and Export: export.md + - Privacy and Security: privacy-and-security.md + - Formats: formats.md - Advanced Usage: advanced.md - Recipes: recipes.md