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

Cleaned up usage.md for clarity, formatting, and grammar. (#956)

Browse source 
* Cleaned up usage.md for clarity, formatting, and grammar.

While working on it, I hard-wrapped the lines to 80 characters. Hope that doesn't complicate things.

Note: I changed the Steve Buscemi quote to maintain compliance with the Code of Conduct.

* more changes to the usage page

Includes information about two new functions (`--delete`) and (`-contains`).
It's starting to look quite different from the original...
This commit is contained in:
Guy B. deBros 2020-05-27 17:07:43 -04:00 • committed by GitHub
parent 3550e56273
commit ce0dd6881c
1 changed files with 158 additions and 84 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

242
docs/usage.md
View file

@ -1,56 +1,44 @@
# Basic Usage # Basic Usage #
`jrnl` has two modes: **composing** and **viewing**. Basically, whenever `jrnl` has two modes: **composing** and **viewing**. Whenever you don't enter
you _don't_ supply any arguments that start any arguments that start with a dash (`-`) or double-dash (`--`), you're in
with a dash or double-dash, you're in composing mode, meaning you can composing mode, meaning that you can write your entry on the command line.
write your entry on the command line or an editor of your choice.
We intentionally break a convention on command line arguments: all We intentionally break a convention on command line arguments: all arguments
arguments starting with a _single dash_ starting with a _single dash_ (`-`) will _filter_ your journal before viewing
will _filter_ your journal before viewing it. Filter arguments can be combined arbitrarily. Arguments with a _double dash_
it, and can be combined arbitrarily. Arguments with a (`--`) will _control_ how your journal is displayed or exported. Control
_double dash_ will control how your journal arguments are mutually exclusive (i.e., you can only specify one way to display
is displayed or exported and are mutually exclusive (ie. you can only or export your journal at a time).
specify one way to display or export your journal at a time).
## Listing Journals ## Composing Entries ##
You can list the journals accessible by jrnl Composing mode is entered by either starting `jrnl` without any arguments --
which will launch an external editor -- or by just writing an entry on the
command line:
```sh ```sh
jrnl -ls jrnl today at 3am: I just met Steve Buscemi in a bar! What a nice guy.
```
The journals displayed correspond to those specified in the jrnl
configuration file.
## Composing Entries
Composing mode is entered by either starting `jrnl` without any
arguments -- which will prompt you to write an entry or launch your
editor -- or by just writing an entry on the prompt, such as
```sh
jrnl today at 3am: I just met Steve Buscemi in a bar! He looked funny.
``` ```
!!! note !!! note
Most shell contains a certain number of reserved characters, such as `#` Most shells contain a certain number of reserved characters, such as `#` and
and `*`. Unbalanced quotes, parenthesis, and so on will also get into `*`. These characters, as well as unbalanced single or double quotation
the way of your editing. marks, parentheses, and others, likely will cause problems. Although
For writing longer entries, just enter `jrnl` reserved characters can be escaped using `\`, this is not ideal for
and hit `return`. Only then enter the text of your journal entry. long-form writing. The solution: first enter `jrnl` and hit `return`. You
Alternatively, `use an external editor <advanced>`). can then enter the text of your journal entry. Alternatively, you can [use
an external editor](./advanced.md)).
You can also import an entry directly from a file You can also import an entry directly from a file:
```sh ```sh
jrnl < my_entry.txt jrnl < my_entry.txt
``` ```
### Smart timestamps ### Specifying Date and Time ###
Timestamps that work: If you don't specify a date and time (e.g., `jrnl finished writing letter to brother`), `jrnl` will create an entry using the current date and time. For retrospective entries, you can use a timestamp to tell `jrnl` where to put the entry. Timestamps can be entered using a variety of formats. Here are some that work:
- at 6am - at 6am
- yesterday - yesterday
@ -59,102 +47,188 @@ Timestamps that work:
- 2 march 2012 - 2 march 2012
- 7 apr - 7 apr
- 5/20/1998 at 23:42 - 5/20/1998 at 23:42
- 2020-05-22T15:55-04:00
### Starring entries If you don't use a timestamp, `jrnl` will create an entry using the current
time. If you use a date only (no time), `jrnl` will use the default time
specified in your configuration file (see [advanced usage](./advanced.md)).
Behind the scenes, `jrnl` reorganizes entries in chronological order.
To mark an entry as a favourite, simply "star" it ### 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:
```sh
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.
### Starring Entries ###
To mark an entry as a favorite, simply "star" it using an asterisk (`*`):
```sh ```sh
jrnl last sunday *: Best day of my life. jrnl last sunday *: Best day of my life.
``` ```
If you don't want to add a date (ie. your entry will be dated as now), If you don't want to add a date (i.e., you want the date to be entered as
The following options are equivalent: _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.`
- `jrnl Best day of my life.*` - `jrnl Best day of my life.*`
!!! note !!! note Make sure that the asterisk (`*`) is **not** surrounded by whitespaces.
Just make sure that the asterisk sign is **not** surrounded by `jrnl Best day of my life! *` will not work because the `*` character has a
whitespaces, e.g. `jrnl Best day of my life! *` will **not** work (the special meaning in most shells.
reason being that the `*` sign has a special meaning on most shells).
## Viewing ## Viewing 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.
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,
```sh ```sh
jrnl -n 10 jrnl -n 10
``` ```
will list you the ten latest entries (if you're lazy, `jrnl -10` will do lists the ten most recent entries. `jrnl -10` is even more concise and works the
the same), 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 ```sh
jrnl -from "last year" -until march jrnl -from "last year" -until march
``` ```
everything that happened from the start of last year to the start of Filter criteria that use more than one word require surrounding quotes (`""`).
last march. To only see your favourite entries, use
### 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
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
of your previous entries.
```sh ```sh
jrnl -starred jrnl -contains "dogs" --edit
``` ```
## Using Tags opens your external editor so that you can add a tag symbol (`@` by default) to
all instances of the word "dogs."
Keep track of people, projects or locations, by tagging them with an `@` ### Filtering by Tag ###
in your entries
```sh You can filter your journal entries by tag. For example,
jrnl Had a wonderful day on the @beach with @Tom and @Anna.
```
You can filter your journal entries just like this:
```sh ```sh
jrnl @pinkie @WorldDomination jrnl @pinkie @WorldDomination
``` ```
Will print all entries in which either `@pinkie` or `@WorldDomination` displays all entries in which either `@pinkie` or `@WorldDomination`
occurred. occurred. Tag filters can be combined with other filters:
```sh ```sh
jrnl -n 5 -and @pinkie @WorldDomination jrnl -n 5 @pinkie -and @WorldDomination
``` ```
the last five entries containing both `@pinkie` **and** `@worldDomination`. displays the last five entries containing _both_ `@pinkie` _and_
You can change which symbols you'd like to use for tagging in the `@worldDomination`. You can change which symbols you'd like to use for tagging
configuration. in the configuration.
!!! note !!! note
`jrnl @pinkie @WorldDomination` will switch to viewing mode because Entering `jrnl @pinkie @WorldDomination` will display entries in which both
although **no** command line arguments are given, all the input strings tags are present because, although no command line arguments are given, all
look like tags - _jrnl_ will assume you want to filter by tag. 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.
## Editing older entries ### Viewing Starred Entries ###
You can edit selected entries after you wrote them. This is particularly To display only your favorite (starred) entries, enter
useful when your journal file is encrypted. To use this feature, you need
to have an editor configured in your journal configuration file (see ```sh
`advanced usage <advanced>`) jrnl -starred
```
## Editing Entries ##
You can edit entries after writing them. This is particularly useful when your
journal file is encrypted. To use this feature, you need to have an external
editor configured in your configuration file. You can also edit only the entries
that match specific search criteria. For example,
```sh ```sh
jrnl -until 1950 @texas -and @history --edit jrnl -until 1950 @texas -and @history --edit
``` ```
Will open your editor with all entries tagged with `@texas` and opens your external editor displaying all entries tagged with `@texas` and
`@history` before 1950. You can make any changes to them you want; after `@history` that were written before 1950. After making changes, save and close
you save the file and close the editor, your journal will be updated. the file, and only those entries will be modified (and encrypted, if
applicable).
Of course, if you are using multiple journals, you can also edit e.g. If you are using multiple journals, it's easy to edit specific entries from
the latest entry of your work journal with `jrnl work -n 1 --edit`. In specific journals. Simply prefix the filter string with the name of the journal.
any case, this will bring up your editor and save (and, if applicable, For example,
encrypt) your edited journal after you save and exit the editor.
You can also use this feature for deleting entries from your journal
```sh ```sh
jrnl @texas -until 'june 2012' --edit jrnl work -n 1 --edit
``` ```
Just select all text, press delete, and everything is gone... opens the most recent entry in the 'work' journal in your external editor.
## Deleting Entries ##
The `--delete` command opens an interactive interface for deleting entries. The
date and title of each entry in the journal are presented one at a time, and you
can choose whether to keep or delete each entry.
If no filters are specified, `jrnl` will ask you to keep or delete each entry in
the entire journal, one by one. If there are a lot of entries in the journal, it
may be more efficient to filter entries before passing the `--delete` command.
Here's an example. Say you have a journal into which you've imported the last 12
years of blog posts. You use the `@book` tag a lot, and for some reason you want
to delete some, but not all, of the entries in which you used that tag, but only
the ones you wrote at some point in 2004 or earlier. You're not sure which
entries you want to keep, and you want to look through them before deciding.
This is what you might enter:
```sh
jrnl -to 2004 @book --delete
```
`jrnl` will show you only the relevant entries, and you can choose the ones you
want to delete.
You may want to delete _all_ of the entries containing `@book` that you wrote in
2004 or earlier. If there are dozens or hundreds, the easiest way would be to
use an external editor. Open an editor with the entries you want to delete...
```sh
jrnl -to 2004 @book --edit
```
...select everything, delete it, save and close, and all of those entries are
removed from the journal.
## Listing Journals ##
To list all of your journals:
```sh
jrnl -ls
```
The journals displayed correspond to those specified in the `jrnl` configuration
file.